Lua:Class:Form

<> Lua API Reference

class Form : ScrollingWinControl

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.

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

local form = createForm()
form.Caption = "Form Example"
form.Width = 400
form.Height = 250

form.centerScreen()
form.show()

local form = createForm()
form.Caption = "Modal Form Example"
form.Width = 300
form.Height = 150

local button = createButton(form)
button.Parent = form
button.Caption = "OK"
button.Left = 20
button.Top = 20
button.ModalResult = mrOK

local result = form.showModal()

print("Modal result: " .. tostring(result))

form.destroy()

local form = createForm()
form.Caption = "Drop Files Example"
form.Width = 400
form.Height = 200
form.AllowDropFiles = true

form.OnDropFiles = function(sender, filenames)
  for i = 1, #filenames do
    print("Dropped file: " .. filenames[i])
  end
end

form.show()

local form = createForm()
form.Name = "UniqueFormPositionExample"
form.Caption = "Position Example"
form.Width = 400
form.Height = 250

local restored = form.loadFormPosition()

if not restored then
  form.centerScreen()
end

form.OnClose = function(sender)
  sender.saveFormPosition({1, 2, 3})
end

form.show()

local form = createForm()
form.Caption = "Borderless Drag Example"
form.BorderStyle = bsNone
form.Width = 400
form.Height = 200

form.OnMouseDown = function(sender)
  sender.dragNow()
end

form.show()

Main Pages

Core Lua documentation entry points

◆ Lua
◆ Script Engine