LuaGuiElement

class LuaGuiElement
add{type=…, name=…, style=…} → LuaGuiElement Add a child element.
destroy() Remove this element, along with its children.
gui :: LuaGui [R] The GUI this element is a part of.
parent :: LuaGuiElement [R] The direct parent of this element; nil if this is a top-level element.
name :: string [R] The name of this element.
caption :: LocalisedString [RW] The text displayed on the element.
value :: double [RW] How much this progress bar is filled.
direction :: string [RW] Direction of the layout.
style :: LuaStyle or string [RW] The style of this element.
text :: string [RW] The text contained in a textfield.
children_names :: array of string [R] Names of all the children of this element.
state :: boolean [RW] Is this checkbox checked?
player_index :: uint [R] Index into LuaGameScript::players specifying the player who owns this element.
sprite :: SpritePath [RW] Path the the image to display on this sprite-button.
tooltip :: LocalisedString [RW]
vertical_scroll_policy :: string [RW] Allowed values are: "always", "never", or "auto"
horizontal_scroll_policy :: string [RW] Allowed values are: "always", "never", or "auto"
type :: string [R] The type of this GUI element.
valid :: boolean [R] Is this object valid?

An element of the custom GUI. This type is used to represent any kind of a GUI element -- labels as well as buttons as well as frames are all instances of this type. Just like LuaEntity, different kinds of elements support different attributes; attempting to access an attribute on an element that doesn't support it (for instance, trying to access the value of a text field) will result in a run-time error.

The following kinds of GUI elements are supported:

Each GUI element allows access to its children by having them as attributes. Thus, one can use the parent.child syntax to refer to children. Lua also supports the parent["child"] syntax to refer to the same element. This can be used in cases where the child has a name that isn't a valid Lua identifier.

Example
This will add a label called greeting to the top flow. Immediately after, it will change its text to illustrate accessing child elements.
game.player.gui.top.add{type="label", name="greeting", caption="Hi"}
game.player.gui.top.greeting.caption = "Hello there!"
game.player.gui.top["greeting"].caption = "Actually, nevermind, I don't like your face"
add{type=…, name=…, style=…} → LuaGuiElement

Add a child element.

Parameters
Table with the following fields:
  • type :: string: The kind of the element to add. Has to be one of "button", "sprite-button", "checkbox", "flow", "frame", "label", "table", "progressbar", or "textfield".
  • name :: string: Name of the child element.
  • style :: string (optional): Style of the new element.
  • Other attributes may have to be specified, depending on type
    • sprite-button
      • sprite :: SpritePath (optional): Path to the image to display on the button.
    • checkbox
      • state :: boolean: Whether the checkbox should be checked by default.
    • frame
    • label
      • caption :: string (optional): Initial text to display on the label.
    • progressbar
      • size :: uint: Width of the progressbar.
      • value :: double (optional): Initial value of the progressbar, in range [0, 1]. Defaults to 0 if not given.
    • table
      • colspan :: uint: Number of columns
Return value
The added GUI element.
destroy()

Remove this element, along with its children. Any LuaGuiElement objects referring to the destroyed elements become invalid after this operation.

Note: The top-level GUI elements -- LuaGui::top, LuaGui::left, LuaGui::center -- can't be destroyed.
Example
game.player.gui.top.greeting.destroy()
gui :: LuaGui [Read-only]

The GUI this element is a part of.

parent :: LuaGuiElement [Read-only]

The direct parent of this element; nil if this is a top-level element.

name :: string [Read-only]

The name of this element.

Example
game.player.gui.top.greeting.name == "greeting"
caption :: LocalisedString [Read-Write]

The text displayed on the element. For frames, this is the "heading". For other elements, like buttons or labels, this is the content.

Note: Whilst this attribute may be used on all elements without producing an error, it doesn't make sense for tables and flows as they won't display it.
value :: double [Read-Write]

How much this progress bar is filled. It is a value in range [0, 1].

Can only be used if this is progressbar
direction :: string [Read-Write]

Direction of the layout. May be either "horizontal" or "vertical".

Can only be used if this is frame
style :: LuaStyle or string [Read-Write]

The style of this element. When read, this evaluates to a LuaStyle. For writing, it only accepts a string that specifies the textual identifier of the desired style.

text :: string [Read-Write]

The text contained in a textfield.

Can only be used if this is textfield
children_names :: array of string [Read-only]

Names of all the children of this element. These are the identifiers that can be used to access the child as an attribute of this element.

state :: boolean [Read-Write]

Is this checkbox checked?

Can only be used if this is checkbox
player_index :: uint [Read-only]

Index into LuaGameScript::players specifying the player who owns this element.

sprite :: SpritePath [Read-Write]

Path the the image to display on this sprite-button.

Can only be used if this is sprite-button
tooltip :: LocalisedString [Read-Write]

vertical_scroll_policy :: string [Read-Write]

Allowed values are: "always", "never", or "auto"

Can only be used if this is scroll-pane
horizontal_scroll_policy :: string [Read-Write]

Allowed values are: "always", "never", or "auto"

Can only be used if this is scroll-pane
type :: string [Read-only]

The type of this GUI element.