Lua:Class:Form
Jump to navigation
Jump to search
The Form class represents a window or dialog form.
A Form inherits from ScrollingWinControl, CustomControl, WinControl, Control, Component, and Object. Forms can contain controls, menus, callbacks, and event handlers, and can be shown normally or as modal dialogs.
Contents
Inheritance
| Class | Inherits From | Description |
|---|---|---|
| Form | ScrollingWinControl | A window or dialog form. |
| ScrollingWinControl | CustomControl | Base class for controls that can contain scrollable child controls. |
| CustomControl | WinControl | Base class for custom windowed controls. |
| WinControl | Control | Base class for windowed controls. |
| Control | Component | Base class for visual controls. |
| Component | Object | Base class for components. |
Properties
| Property | Type | Description |
|---|---|---|
| DesignTimePPI | Integer | The PPI or DPI value at the time the form was designed. |
| AllowDropFiles | Boolean | Allows files to be dragged onto the form. |
| ModalResult | Integer | The current ModalResult value of the form. When this value is set, the modal form will close. |
| Menu | MainMenu | The main menu of the form. |
| OnClose | Function | The function to call when the form gets closed. |
| OnDropFiles | Function | The function to call when files are dragged onto the form. |
| FormState | String | The current state of the form. This property is read-only. |
Events
| Event | Function Signature | Description |
|---|---|---|
| OnClose | function(sender) | Called when the form gets closed. |
| OnDropFiles | function(sender, filenames) | Called when files are dragged onto the form. The filenames parameter is an array table containing the dragged files. |
FormState Values
| Value | Description |
|---|---|
| fsCreating | The form is being created. |
| fsVisible | The form is visible. |
| fsShowing | The form is being shown. |
| fsModal | The form is being shown as a modal form. |
| fsCreatedMDIChild | The form was created as an MDI child. |
| fsBorderStyleChanged | The border style of the form has changed. |
| fsFormStyleChanged | The form style has changed. |
| fsFirstShow | The form is being shown for the first time. |
| fsDisableAutoSize | Automatic sizing is disabled. |
Methods
| Method | Return Type | Description |
|---|---|---|
| fixDPI() | void | Resizes controls and fonts based on the current DPI and the DPI used to create the form. Only use this on forms that are not designed with variable DPI in mind. |
| centerScreen() | void | Places the form at the center of the screen. |
| hide() | void | Hides the form. |
| show() | void | Shows the form. |
| close() | void | Closes the form. Without an OnClose handler, this behaves the same as hide(). |
| bringToFront() | void | Brings the form to the foreground. |
| showModal() | Integer | Shows the form as a modal dialog and waits for it to close. Returns the close result. |
| isForegroundWindow() | Boolean | Returns true if the specified form has focus. |
| setOnClose(function) | void | Sets the OnClose handler. The function receives the sender and can return a CloseAction to determine how to close the window. |
| getOnClose() | Function | Returns the current OnClose handler function. |
| getMenu() | MainMenu | Returns the MainMenu object of this form. |
| setMenu(mainmenu) | void | Sets the MainMenu object of this form. |
| setBorderStyle(borderstyle) | void | Sets the border style of the form. |
| getBorderStyle() | Integer | Returns the current border style of the form. |
| printToRasterImage(rasterimage) | void | Draws the contents of the form to a RasterImage class object. |
| registerCreateCallback(function(f)) | Userdata | Registers a function to be called when the form has finished being created. |
| unregisterCreateCallback(userdata) | void | Removes the specified create callback. |
| registerFirstShowCallback(function(f)) | Userdata | Registers a function to be called when the form is shown for the first time. |
| unregisterFirstShowCallback(userdata) | void | Removes the specified first-show callback. |
| registerCloseCallback(function(f)) | Userdata | Registers a function to be called when the form has been closed. |
| unregisterCloseCallback(userdata) | void | Removes the specified close callback. |
| dragNow() | void | Starts dragging the whole form. Call this from a mouse-down event on any object to allow dragging borderless windows. Dragging stops when the mouse button is released. |
| saveFormPosition(integers) | void | Saves the current form position, dimensions, and an optional integer table. The form name must be set to a unique name. |
| loadFormPosition() | Boolean, Table or nil | Restores the form position and dimensions. On success, returns true and an integer table if one was saved. The form name must be set to a unique name. |
Callback Methods
| Method | Callback Signature | Description |
|---|---|---|
| registerCreateCallback(function(f)) | function(f) | Registers a callback that runs when the form has finished being created. |
| registerFirstShowCallback(function(f)) | function(f) | Registers a callback that runs when the form is shown for the first time. |
| registerCloseCallback(function(f)) | function(f) | Registers a callback that runs when the form has been closed. |
Examples
1 local form = createForm()
2 form.Caption = "Form Example"
3 form.Width = 400
4 form.Height = 250
5
6 form.centerScreen()
7 form.show()
1 local form = createForm()
2 form.Caption = "Modal Form Example"
3 form.Width = 300
4 form.Height = 150
5
6 local button = createButton(form)
7 button.Parent = form
8 button.Caption = "OK"
9 button.Left = 20
10 button.Top = 20
11 button.ModalResult = mrOK
12
13 local result = form.showModal()
14
15 print("Modal result: " .. tostring(result))
16
17 form.destroy()
1 local form = createForm()
2 form.Caption = "Drop Files Example"
3 form.Width = 400
4 form.Height = 200
5 form.AllowDropFiles = true
6
7 form.OnDropFiles = function(sender, filenames)
8 for i = 1, #filenames do
9 print("Dropped file: " .. filenames[i])
10 end
11 end
12
13 form.show()
1 local form = createForm()
2 form.Name = "UniqueFormPositionExample"
3 form.Caption = "Position Example"
4 form.Width = 400
5 form.Height = 250
6
7 local restored = form.loadFormPosition()
8
9 if not restored then
10 form.centerScreen()
11 end
12
13 form.OnClose = function(sender)
14 sender.saveFormPosition({1, 2, 3})
15 end
16
17 form.show()
1 local form = createForm()
2 form.Caption = "Borderless Drag Example"
3 form.BorderStyle = bsNone
4 form.Width = 400
5 form.Height = 200
6
7 form.OnMouseDown = function(sender)
8 sender.dragNow()
9 end
10
11 form.show()
