LuaGuiElement

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:

"button": Clickable elements that fire on_gui_click when clicked.
"sprite-button": A button that displays an image rather than text.
"checkbox": Clickable elements with a cross in the mdidle that can be turned off or on. They also fire on_gui_click when clicked.
"flow": Invisible containers that lay out children either horizontally or vertically. All three root GUI elements (top, left and center; see LuaGui) are flows.
"frame": Grey semi-transparent boxes that contain other elements. They have a caption, and, just like flows, they lay out children either horizontally or vertically.
"label": A piece of text.
"progressbar": Indicate progress by displaying a partially filled bar.
"table": An invisible container that lays out children in a specific number of columns. Column width is given by the largest element contained in that row.
"textfield": Boxes of text the user can type in.
"radiobutton": Identical to checkbox except circular.
"sprite": An element that shows an image.
"scroll-pane": Similar to a flow but includes the ability to show and use scroll bars.
"drop-down": A drop down list of other elements.
"camera": A camera that shows the game at the given position on the given surface.
"choose-elem-button": A button that lets the player pick one of an: item, entity, tile, or signal similar to the filter-select window.
"text-box": A multi-line text box that supports selection and copy-paste.

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", "textfield", "radiobutton", "sprite", "scroll-pane", "camera", "drop-down", or "text-box".
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.
- radiobutton
  - state :: boolean: Whether the radiobutton should be checked by default.
- frame
  - direction :: string: The initial direction of the frame's layout. See LuaGuiElement::direction.
- label
  - caption :: string (optional): Initial text to display on the label.
  - single_line :: boolean (optional): If text should be shown on a single line or wrapped based off the max width of the label.
  - want_ellipsis :: boolean (optional): If text beyond the widget width should be shown as "..." instead of clipped. Can't be used with single_line==false
- 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
- drop-down
  - items :: array of LocalisedString (optional): The initial items in the dropdown.
  - selected_index :: uint (optional): The initial selected index.
- camera
  - position :: Position: The position the camera centers on.
  - surface_index :: uint (optional): The surface the camera will render else if not given the players surface is used.
  - zoom :: double (optional): The camera zoom - defaults to 0.75.
- choose-elem-button
  - elem_type :: string: "item", "tile", "entity", or "signal"
  - item :: string (optional): If type is "item" - the default value for the button
  - entity :: string (optional): If type is "entity" - the default value for the button
  - tile :: string (optional): If type is "tile" - the default value for the button
  - signal :: SignalID (optional): If type is "signal" - the default value for the button

Return value

The added GUI element.

clear()

Remove children of this element. Any LuaGuiElement objects referring to the destroyed elements become invalid after this operation.

Example

game.player.gui.top.clear()

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

clear_items()

Clears the items in this dropdown.

Can only be used if this is drop-down

get_item(index) → LocalisedString

Gets an item at the given index from this dropdown.

Parameters

index :: uint: The index to get.

Can only be used if this is drop-down

set_item(index, LocalisedString)

Sets an item at the given index in this dropdown.

Parameters

index :: uint: The index

LocalisedString: The item.

Can only be used if this is drop-down

add_item(LocalisedString, index)

Adds an item at the end or at the given index in this dropdown.

Parameters

LocalisedString: The item.

index :: uint (optional): The index

Can only be used if this is drop-down

remove_item(index)

Removes an item at the given index in this dropdown.

Parameters

index :: uint: The index

Can only be used if this is drop-down

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 or text-box.

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.

children :: array of LuaGuiElement [Read-only]

The children elements

items :: array of LocalisedString [Read-Write]

The items in this dropdown.

Can only be used if this is drop-down

selected_index :: uint [Read-Write]

The selected index for this dropdown. 0 if none.

single_line :: boolean [Read-Write]

If this label should render its contents on single line or multiple based off the max width of the label.

want_ellipsis :: boolean [Read-Write]

If this label text should render text outside the label area as "...".

position :: Position [Read-Write]

The position this camera is focused on.

Can only be used if this is camera

surface_index :: uint [Read-Write]

The surface index this camera is using.

Can only be used if this is camera

zoom :: double [Read-Write]

The zoom this camera is using.

Can only be used if this is camera

elem_type :: string [Read-only]

The elem type of this choose-elem-button.

Can only be used if this is choose-elem-button

elem_value :: string or SignalID [Read-Write]

The elem value of this choose-elem-button or nil if there is no value.

Note: Types "item", "entity", and "tile" operate with strings. Type "signal" operates with SignalID.

Can only be used if this is choose-elem-button

selectable :: boolean [Read-Write]

If the contents of this text-box are selectable.

Can only be used if this is text-box

word_wrap :: boolean [Read-Write]

If this text-box will word-wrap automatically.

Can only be used if this is text-box

read_only :: boolean [Read-Write]

If this text-box is read-only.

Can only be used if this is text-box

enabled :: boolean [Read-Write]

If this GUI element is enabled.