Difference between revisions of "Lua:Class:Form"

From Cheat Engine
Jump to navigation Jump to search
m (Class Template Implementation.)
 
(7 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
[[Category:Lua]]
 
[[Category:Lua]]
−
'''Form Class''' (Inheritance ScrollingWinControl->CustomControl->WinControl->Control->Component->Object)
+
{{Class|'''class''' Form ''':''' ScrollingWinControl}}
−
  The Form class is a window
 
  
 +
The Form class represents a window or dialog form.
  
−
'''createForm'''(visible OPT)
+
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.
−
  Creates a Form class object(window) and returns the pointer for it. Visible is default true but can be changed
 
  
 +
===Inheritance===
 +
{|width="85%" cellpadding="10%" cellspacing="0" border="0"
 +
!align="left"|Class
 +
!align="left"|Inherits From
 +
!style="width: 80%;background-color:white;" align="left"|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.
 +
|}
  
−
'''createFormFromFile'''(filename)
+
===Properties===
−
  Creates a Form class object and initializes it based on the data in the given file.
+
{|width="85%" cellpadding="10%" cellspacing="0" border="0"
−
  It returns the generated form
+
!align="left"|Property
 +
!align="left"|Type
 +
!style="width: 80%;background-color:white;" align="left"|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.
 +
|}
  
−
== Properties ==
+
===Events===
 +
{|width="85%" cellpadding="10%" cellspacing="0" border="0"
 +
!align="left"|Event
 +
!align="left"|Function Signature
 +
!style="width: 80%;background-color:white;" align="left"|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===
 +
{|width="85%" cellpadding="10%" cellspacing="0" border="0"
 +
!align="left"|Value
 +
!align="left"|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 ==
+
===Methods===
 +
{|width="85%" cellpadding="10%" cellspacing="0" border="0"
 +
!align="left"|Method
 +
!align="left"|Return Type
 +
!style="width: 80%;background-color:white;" align="left"|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===
 +
{|width="85%" cellpadding="10%" cellspacing="0" border="0"
 +
!align="left"|Method
 +
!align="left"|Callback Signature
 +
!style="width: 80%;background-color:white;" align="left"|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.
 +
|}
  
−
'''saveToFile'''(filename)  
+
===Examples===
−
  Saves a userdefined form. (DOES NOT WORK ON NORMAL FORMS LIKE MAINFORM)
+
<syntaxhighlight lang="lua" line>
 +
local form = createForm()
 +
form.Caption = "Form Example"
 +
form.Width = 400
 +
form.Height = 250
  
 +
form.centerScreen()
 +
form.show()
 +
</syntaxhighlight>
  
−
'''centerScreen'''()
+
<syntaxhighlight lang="lua" line>
−
  Places the form at the center of the screen
+
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
  
−
'''hide'''()
+
local result = form.showModal()
−
  Hide the form
 
  
 +
print("Modal result: " .. tostring(result))
  
−
'''show'''()
+
form.destroy()
−
  Show the form
+
</syntaxhighlight>
  
 +
<syntaxhighlight lang="lua" line>
 +
local form = createForm()
 +
form.Caption = "Drop Files Example"
 +
form.Width = 400
 +
form.Height = 200
 +
form.AllowDropFiles = true
  
−
'''showModal'''()  
+
form.OnDropFiles = function(sender, filenames)
−
   Show the form and wait for it to close and get the close result
+
   for i = 1, #filenames do
 +
    print("Dropped file: " .. filenames[i])
 +
  end
 +
end
  
 +
form.show()
 +
</syntaxhighlight>
  
−
'''isForegroundWindow'''()  
+
<syntaxhighlight lang="lua" line>
−
  returns true if the specified form has focus
+
local form = createForm()
 +
form.Name = "UniqueFormPositionExample"
 +
form.Caption = "Position Example"
 +
form.Width = 400
 +
form.Height = 250
  
 +
local restored = form.loadFormPosition()
  
−
'''onClose'''(function) 
+
if not restored then
−
   function (sender) Return a CloseAction to determine how to close the window
+
   form.centerScreen()
 +
end
  
 +
form.OnClose = function(sender)
 +
  sender.saveFormPosition({1, 2, 3})
 +
end
  
−
'''getMenu'''(form)
+
form.show()
−
  Returns the mainmenu object of this form
+
</syntaxhighlight>
  
 +
<syntaxhighlight lang="lua" line>
 +
local form = createForm()
 +
form.Caption = "Borderless Drag Example"
 +
form.BorderStyle = bsNone
 +
form.Width = 400
 +
form.Height = 200
  
−
'''setMenu'''(mainmenu)
+
form.OnMouseDown = function(sender)
−
  Sets a menu for the form
+
   sender.dragNow()
−
 
 
−
Example:
 
−
<pre>
 
−
function goodbyeMessage(sender)
 
−
   print "called by form_onClose"
 
−
  closeCE()                   -- Just closes ce
 
 
end
 
end
  
−
local forms = createForm(true) -- true = visible(optional), false = not visible when created.
+
form.show()
−
forms.hide()              -- hides the form
+
</syntaxhighlight>
−
sleep(3000)
 
−
forms.show()               -- again makes the form visible
 
−
sleep(3000)
 
−
forms.centerScreen()      -- Places the form at the center of the screen
 
−
if forms.isForegroundWindow(forms)  then
 
−
  print "form in focus"
 
−
end
 
−
forms.onClose(goodbyeMessage)  -- delegates goodbyeMessage function. goodbyeMessage should have the prototype "goodbyeMessage(oneArgument)"
 
−
</pre>
 
  
 +
{{LuaSeeAlso}}
  
−
{{LuaSeeAlso}}
+
{{Forms}}

Latest revision as of 23:20, 26 June 2026

{} Class

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[edit]

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[edit]

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[edit]

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[edit]

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[edit]

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[edit]

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[edit]

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()

Main Pages

Core Lua documentation entry points

◆ Lua
◆ Script Engine

Form Related Classes



Retrieved from "https://wiki.cheatengine.org/index.php?title=Lua:Class:Form&oldid=8424"