LuaGuiElement

class LuaGuiElement
add{type=…, name=…, style=…} 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"
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=…}

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