Module `GUI`

Allows to access UI elements of the game.

See the GUI Compendium for a broader explanation of how to use the GUI module and what you can do with it.

Functions

createDialog (args)	Shows a dialog on the screen.
createMenu (args)	Shows a menu with various actions in it.
createRenameDialog (args)	Shows a dialog that allows the user to enter some text.
createSelectDraftDialog (args)	Shows a dialog that allows the user to select a single or multiple drafts from a list of drafts.
get (id)	Finds a GUI object by its id.
getRoot ()	Returns the root GUI object.

Class GUI

gui:addButton (args)	Adds a button object.
gui:addCanvas (args)	Adds a canvas object.
gui:addHotkey (key[, mod=nil])	Adds a hotkey to a GUI object.
gui:addIcon (args)	Adds an icon object.
gui:addLabel (args)	Adds a label object.
gui:addLayout (args)	Adds a layout object.
gui:addListBox (args)	Adds a listbox object.
gui:addPanel (args)	Adds a panel object.
gui:addSlider (args)	Adds a slider object.
gui:addTextField (args)	Adds a textfield object.
gui:addTextFrame (args)	Adds a textframe object.
gui:countChildren ()	Returns the number of children GUI objects this object has.
gui:delete ()	Removes this GUI object from the active GUI hierarchy which will effectively delete it.
gui:getAbsoluteParent ()	Returns the top-most parent of this GUI object.
gui:getAbsoluteX ()	Returns the absolute x location of the GUI object.
gui:getAbsoluteY ()	Returns the absolute y location of the GUI object.
gui:getChild (index)	Gets a child by its index.
gui:getChildIndex ()	Gets the child index of this GUI object.
gui:getClientHeight ()	Returns the height of the inner area of the GUI object.
gui:getClientWidth ()	Returns the width of the inner area of the GUI object.
gui:getFont ()	Gets the font of a GUI object.
gui:getHeight ()	Returns the height of the GUI object.
gui:getIcon ()	Gets the set icon of a GUI object.
gui:getId ()	Gets id of the GUI object.
gui:getPadding ()	Returns the padding of this GUI object.
gui:getParent ()	Returns the parent GUI object of this object.
gui:getText ()	Returns the text of a GUI object.
gui:getTouchPoint ()	Returns the active touch point that is active in this GUI object if there is any and if this object is touch sensitive (like buttons, canvases, ...).
gui:getWidth ()	Returns the width of the GUI object.
gui:getX ()	Returns the local x location of the GUI object relative to its parent.
gui:getY ()	Returns the local y location of the GUI object relative to its parent.
gui:isActive ()	For text fields: returns whether the text field is currently selected for input.
gui:isEnabled ()	Returns whether this GUI object is enabled right now.
gui:isMouseOver ()	Determines whether the mouse pointer is currently over the GUI object.
gui:isValid ()	Determines whether this GUI object is valid.
gui:isVisible ()	Returns whether this GUI object is set to be visible right now.
gui:layout ()	Issues a recalculation of this GUI object's layout and its children.
gui:removeHotkey (key[, mod=nil])	Removes a hotkey from the GUI object.
gui:setActive ()	Marks a text field as active, meaning that it will be focused for user input.
gui:setChildIndex (index)	Sets the child index of this GUI object.
gui:setEnabled (state)	Enables or disables this GUI object.
gui:setFont (font)	Sets the font of a GUI object.
gui:setIcon (icon)	Sets the icon of a GUI object.
gui:setId (id)	Sets the id of the GUI object.
gui:setPadding (left, top, right, bottom)	Sets the padding of this GUI object.
gui:setPosition (x, y)	Sets the position of that GUI object to the given location.
gui:setShowBorder (state)	Sets the visibility of the border and background of a textframe or listbox.
gui:setSize (width, height)	Sets the size of the GUI object.
gui:setText (text)	Sets the text of a GUI object.
gui:setTouchThrough (state)	Sets the though through state of the GUI object.
gui:setVisible (state)	Sets this GUI object to be visible or invisible.

Functions

createDialog (args)

Shows a dialog on the screen. See the GUI Compendium for the parameters that can be provided in the args table.

Parameters:

args table A table that contains various parameters.

Returns:

table

createMenu (args)

Shows a menu with various actions in it. An easy way to allow the user to pick from a set of things. See the GUI Compendium for the parameters that can be provided in the args table.

Parameters:

args table A table that contains the actions.

createRenameDialog (args)

Shows a dialog that allows the user to enter some text. The game uses this dialog for rename operations, search query input and so on. You can use a textfield object instead if it suits your needs. Having a separate dialog prevents you from dealing with the quirks that some of the textfield implementations can have.

Parameters:

args table A table that contains all of the parameters for the dialog creation. Usually all of the values are optional. See the example for available parameters.

Returns:

table

Usage:

GUI.createRenameDialog{
  icon = Icon.OK,                  -- An icon for the dialog
  title = 'Enter something',       -- Title for the dialog
  text = 'Some explanation',       -- A text to explain what the input is about
  value = 'A text',                -- Content of the textfield
  okText = 'Ok',                   -- Text for the apply button, "Rename" by default
  cancelText = 'Cancel',           -- Text for the cancel button, "Cancel" by default
  onOk = function(value)           -- Callback function that will be called when user pressed ok
    Debug.toast('Entered '..value)
  end,
  onCancel = function() end,       -- Callback function that will be called when user cancels input
  filter = function(value)         -- Predicate function that should only return true if the value is "valid input"
    return value:len() > 5
  end
}

createSelectDraftDialog (args)

Shows a dialog that allows the user to select a single or multiple drafts from a list of drafts. This is for example used in the tree planter tool to allow the player to select species to plant.

Parameters:

args table A table that contains all of the parameters for the dialog creation. Usually all of the values are optional. See the example for available parameters.

Returns:

table

Usage:

GUI.createSelectDraftDialog{
  icon = Icon.OK,    -- An icon for the dialog
  title = 'My seleciton',  -- A title for the dialog. Empty by default.
  drafts = { Draft.get('$someid'), ... }, -- A table of availble drafts
  selection = nil,   -- Either a single draft or a table of drafts. nil by default.
  multiple = false,  -- Allows selection of more than one drafts. false by default.
  minSelection = 0,  -- Minimum number of selected items. 0 by default.
  maxSelection = 10, -- Maximum number of selected items. 99999 by default.
  selectableOnly = true,      -- Only show drafts that can actually be "used". true by default.
  onSelect = function(selection) end,  -- Callback for user confirms as selection. The parameter is the selected draft if mulitple is false, otherwise an array of drafts.
  onCancel = function() end,  -- Callback function that will be called when user cancels input
}

get (id)

Finds a GUI object by its id. An id can be assigned to any GUI object to find it using this function. Some game made GUI objects also have an id that you can find using this function.

Parameters:

id string

Returns:

GUI

getRoot ()

Returns the root GUI object. The root GUI object is a panel that streches along the whole screen. All other GUI objects are directly or indirectly children of this object. The padding of this object leaves space for e.g. notches. This means that the inner area of this object represents the safe area where you can place stuff.

Returns:

GUI

Class GUI

This type represents GUI objects.

gui:addButton (args)

Adds a button object. See the GUI Compendium for more information.

Parameters:

args table A table that contains the GUI object creation parameters.

Returns:

GUI

gui:addCanvas (args)

Adds a canvas object. See the GUI Compendium for more information.

Parameters:

args table A table that contains the GUI object creation parameters.

Returns:

GUI

gui:addHotkey (key[, mod=nil])

Adds a hotkey to a GUI object. If the button gets pressed the GUI object's onClick callback function will be called. Usually used for buttons.

Parameters:

key number A keycode as defined in the Keys table.
mod string A modifier key code/name. (default nil)

Usage:

button:addHotkey(Keys.ENTER)

 -- The modifier key can be assigned by a string as modifier names: "ctrl", "shift", "alt".
button:addHotkey(Keys.A, "alt")

 -- Use plus "+" sign to assign multiple modifiers.
button:addHotkey(Keys.C, "ctrl+shift")

gui:addIcon (args)

Adds an icon object. See the GUI Compendium for more information.

Parameters:

args table A table that contains the GUI object creation parameters.

Returns:

GUI

gui:addLabel (args)

Adds a label object. See the GUI Compendium for more information.

Parameters:

args table A table that contains the GUI object creation parameters.

Returns:

GUI

gui:addLayout (args)

Adds a layout object. See the GUI Compendium for more information.

Parameters:

args table A table that contains the GUI object creation parameters.

Returns:

GUI

gui:addListBox (args)

Adds a listbox object. See the GUI Compendium for more information.

Parameters:

args table A table that contains the GUI object creation parameters.

Returns:

GUI

gui:addPanel (args)

Adds a panel object. See the GUI Compendium for more information.

Parameters:

args table A table that contains the GUI object creation parameters.

Returns:

GUI

gui:addSlider (args)

Adds a slider object. See the GUI Compendium for more information.

Parameters:

args table A table that contains the GUI object creation parameters.

Returns:

GUI

gui:addTextField (args)

Adds a textfield object. See the GUI Compendium for more information.

Parameters:

args table A table that contains the GUI object creation parameters.

Returns:

GUI

gui:addTextFrame (args)

Adds a textframe object. See the GUI Compendium for more information.

Parameters:

args table A table that contains the GUI object creation parameters.

Returns:

GUI

gui:countChildren ()

Returns the number of children GUI objects this object has.

Returns:

number

gui:delete ()

Removes this GUI object from the active GUI hierarchy which will effectively delete it.

gui:getAbsoluteParent ()

Returns the top-most parent of this GUI object. This object is not valid anymore if its aboslute parent isn't the root GUI object. If the object has no parent the object itself will be returned.

Returns:

GUI

gui:getAbsoluteX ()

Returns the absolute x location of the GUI object. This matches the x coordinate you would use for drawing or would find in touchpoints.

Returns:

number

gui:getAbsoluteY ()

Returns the absolute y location of the GUI object. This matches the y coordinate you would use for drawing or would find in touchpoints.

Returns:

number

gui:getChild (index)

Gets a child by its index. The index ranges from 1 to :countChildren() of the parent object.

Parameters:

index number The index of a child.

Returns:

GUI

gui:getChildIndex ()

Gets the child index of this GUI object.

Returns:

number

gui:getClientHeight ()

Returns the height of the inner area of the GUI object. The inner height is the height that is available for child objects. That is the height minus the top and bottom padding.

Returns:

number

gui:getClientWidth ()

Returns the width of the inner area of the GUI object. The inner width is the width that is available for child objects. That is the width minus the left and right padding.

Returns:

number

gui:getFont ()

Gets the font of a GUI object. Only text related objects support this function, e.g. labels, buttons, ... Text fields do not support this function.

Returns:

font

gui:getHeight ()

Returns the height of the GUI object.

Returns:

number

gui:getIcon ()

Gets the set icon of a GUI object.

Returns:

int

gui:getId ()

Gets id of the GUI object. An id can be assigned to any GUI object to identify it.

Returns:

string

gui:getPadding ()

Returns the padding of this GUI object. Padding defines the distances between the inner area to the border of this object.

Returns:

number Padding on the left side.
number Padding on the top side.
number Padding on the right side.
number Padding on the bottom side.

Usage:

local left,top,right,bottom = obj:getPadding()

gui:getParent ()

Returns the parent GUI object of this object. Can be nil if this is the root object or if this object is not valid anymore (that means not part of the active GUI hierarchy).

Returns:

GUI

gui:getText ()

Returns the text of a GUI object. Only text related object support this function, e.g. labels, buttons, text fields, ...

Returns:

string

gui:getTouchPoint ()

Returns the active touch point that is active in this GUI object if there is any and if this object is touch sensitive (like buttons, canvases, ...). The values returned are all nil otherwise.

Returns:

number x Current absolute x location of the touch point.
number y Current absolute y location of the touch point.
number firstX Absolute x location of the touch point when it was initiated.
number firstY Absolute y location of the touch point when it was initiated.
number speedX X movement of this touch point since the last update.
number speedY Y movement of this touch point since the last update.
number time The unix time in ms when the touch point was initiated. Can be used for identifying the touch point.

Usage:

```
local x,y = obj:getTouchPoint()
```

local _,_,_,_,_,_,time = obj:getTouchPoint()

gui:getWidth ()

Returns the width of the GUI object.

Returns:

number

gui:getX ()

Returns the local x location of the GUI object relative to its parent.

Returns:

number

gui:getY ()

Returns the local y location of the GUI object relative to its parent.

Returns:

number

gui:isActive ()

For text fields: returns whether the text field is currently selected for input.

New feature:

1.10.08

Returns:

bool

gui:isEnabled ()

Returns whether this GUI object is enabled right now. A disabled object will not be clickable. Disabled buttons will be drawn differently.

Returns:

boolean

gui:isMouseOver ()

Determines whether the mouse pointer is currently over the GUI object. Returns always false if there is no mouse pointer.

Returns:

bool

gui:isValid ()

Determines whether this GUI object is valid. A GUI object is valid if it's part of the current GUI hierarchy.

Returns:

boolean

gui:isVisible ()

Returns whether this GUI object is set to be visible right now.

Returns:

boolean

gui:layout ()

Issues a recalculation of this GUI object's layout and its children. Calling this function should not be necessary since it will usually be called automatically when an object changes.

gui:removeHotkey (key[, mod=nil])

Removes a hotkey from the GUI object.

Parameters:

key number The keycode of a key to remove.
mod string The modifier of a key to remove. (default nil)

Returns:

bool

New feature:

1.10.08

gui:setChildIndex (index)

Sets the child index of this GUI object. By changing the child index of an object you can alter the drawing order and/or listing order between this object and its siblings. The index should be in range 1 to :countChildren() of the parent object.

Parameters:

index number The child index to apply to this object.

gui:setEnabled (state)

Enables or disables this GUI object. A disabled object will not be clickable. Disabled buttons will be drawn differently.

Parameters:

state boolean Whether to enable this object.

gui:setFont (font)

Sets the font of a GUI object. Only text related objects support this function, e.g. labels, buttons, ... Text fields do not support this function.

Parameters:

font font The text to apply to this object.

gui:setIcon (icon)

Sets the icon of a GUI object. Supported GUI objects are dialogs, buttons and icons.

Parameters:

icon int The frame to use as an icon

gui:setId (id)

Sets the id of the GUI object. An id can be assigned to any GUI object to identify it.

Parameters:

id string The id to apply to the GUI object.

gui:setPadding (left, top, right, bottom)

Sets the padding of this GUI object.

Parameters:

left number Padding on the left side.
top number Padding on the top side.
right number Padding on the right side.
bottom number Padding on the bottom side.

gui:setPosition (x, y)

Sets the position of that GUI object to the given location. The location is relative to the inner area of the parent object.

Parameters:

x number X coordinate.
y number Y coordinate.

gui:setShowBorder (state)

Sets the visibility of the border and background of a textframe or listbox.

New feature:

1.10.12

Parameters:

state boolean The visibility state to apply to the border/background.

gui:setSize (width, height)

Sets the size of the GUI object.

Parameters:

width number The width to set.
height number The height to set.

gui:setText (text)

Sets the text of a GUI object. Only text related object support this function, e.g. labels, buttons, text fields, ...

Parameters:

text string The text to apply to this object.

gui:setTouchThrough (state)

Sets the though through state of the GUI object. If this is set to true touch events will not be consumed by the object and therefore affect other GUI objects that are behind it.

Parameters:

state bool True to enable the touch through option.

gui:setVisible (state)

Sets this GUI object to be visible or invisible.

Parameters:

state boolean The visibility state to set.

Lua API

Contents

Modules

Topics

Module GUI

Functions

Class GUI

Functions

Parameters:

Returns:

Parameters:

Parameters:

Returns:

Usage:

Parameters:

Returns:

Usage:

Parameters:

Returns:

Returns:

Class GUI

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Usage:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Returns:

Returns:

Returns:

Returns:

Parameters:

Returns:

Returns:

Returns:

Returns:

Returns:

Returns:

Returns:

Returns:

Returns:

Usage:

Returns:

Returns:

Returns:

Usage:

Returns:

Returns:

Returns:

New feature:

Returns:

Returns:

Returns:

Returns:

Returns:

Parameters:

Returns:

See also:

New feature:

Parameters:

Parameters:

Parameters:

Parameters:

Parameters:

Module `GUI`