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.
get (id) Finds a GUI object by its id.
getRoot () Returns the root GUI object.

Class GUI

GUI:addHotkey (key) Adds a hotkey to a GUI 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: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:isEnabled () Returns whether this GUI object is enabled right now.
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) Removes a hotkey from the GUI object.
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: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:setSize (width, height) Sets the size of the GUI object.
GUI:setText (text) Sets the text of a 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 A table that represents the dialog.
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 Returns a dialog table object similar to GUI.createDialog

Usage:

    GUI.showRenameDialog{
      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
    }
    
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:

Returns:

    GUI object
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 object that has no parent

Class GUI

This type represents GUI objects.
GUI:addHotkey (key)
Adds a hotkey to a GUI object. If the button gets pressed the GUI objects onClick callback function will be called. Usually used for buttons.

Parameters:

  • key number A keycode as defined in the Keys table.

Usage:

    button:addHotkey(Keys.ENTER)
GUI:countChildren ()
Returns the number of children GUI objects this object has.

Returns:

    number The number of children.
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 The absolute parent GUI object.
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 The absolute x location of the GUI object.
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 The absolute y location of the GUI object.
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 The GUI object of the given index.
GUI:getChildIndex ()
Gets the child index of this GUI object.

Returns:

    number The child index of this object.
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 The height of the inner area.
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 The width of the inner area.
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 The font that is currently in use by that object.
GUI:getHeight ()
Returns the height of the GUI object.

Returns:

    number The height of the GUI object.
GUI:getId ()
Gets id of the GUI object. An id can be assigned to any GUI object to identify it.

Returns:

    string Returns the id of the GUI object.
GUI:getPadding ()
Returns the padding of this GUI object. Padding defines the distances between the inner area to the border of this object.

Returns:

  1. number Padding on the left side.
  2. number Padding on the top side.
  3. number Padding on the right side.
  4. 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 The parent GUI object.
GUI:getText ()
Returns the text of a GUI object. Only text related object support this function, e.g. labels, buttons, text fields, ...

Returns:

    string The current text of that 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, ...). The values returned are all nil otherwise.

Returns:

  1. number x Current absolute x location of the touch point.
  2. number y Current absolute y location of the touch point.
  3. number firstX Absolute x location of the touch point when it was initiated.
  4. number firstY Absolute y location of the touch point when it was initiated.
  5. number speedX X movement of this touch point since the last update.
  6. number speedY Y movement of this touch point since the last update.
  7. 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 The width of the GUI object.
GUI:getX ()
Returns the local x location of the GUI object relative to its parent.

Returns:

    number The x location of the GUI object.
GUI:getY ()
Returns the local y location of the GUI object relative to its parent.

Returns:

    number The y location of the GUI object.
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 True if this object is enabled.
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 True is this object is part of the active GUI hierarchy.
GUI:isVisible ()
Returns whether this GUI object is set to be visible right now.

Returns:

    boolean Returns true iff this GUI object is set to be visible.
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)
Removes a hotkey from the GUI object.

Parameters:

  • key number The keycode of a key to remove.

Returns:

    bool Returns true iff such a hotkey was actually assigned.
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: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: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:setVisible (state)
Sets this GUI object to be visible or invisible.

Parameters:

  • state boolean The visibility state to set.
generated by LDoc 1.4.3 Last updated 2020-11-25 06:27:19