LuaGuiElement

class LuaGuiElement - sort
add{type=…, name=…, caption=…, tooltip=…, enabled=…, ignored_by_interaction=…, style=…} → LuaGuiElement Add a child element.
clear() Remove children of this element.
destroy() Remove this element, along with its children.
clear_items() Clears the items in this dropdown or listbox.
get_item(index) → LocalisedString Gets an item at the given index from this dropdown or listbox.
set_item(index, LocalisedString) Sets an item at the given index in this dropdown or listbox.
add_item(LocalisedString, index) Adds an item at the end or at the given index in this dropdown or listbox.
remove_item(index) Removes an item at the given index in this dropdown or listbox.
get_slider_minimum() → double Gets this sliders minimum value.
get_slider_maximum() → double Gets this sliders minimum value.
set_slider_minimum_maximum(minimum, maximum) Sets this sliders minimum and maximum values.
focus() Focuses this GUI element if possible.
scroll_to_top() Scrolls the scroll bar to the top.
scroll_to_bottom() Scrolls the scroll bar to the bottom.
scroll_to_left() Scrolls the scroll bar to the left.
scroll_to_right() Scrolls the scroll bar to the right.
scroll_to_element(element, scroll_mode) Scrolls the scroll bar such that the specified GUI element is visible to the player.
select_all() Select all text in the text box.
select(start, end) Select a range of text in the text box.
index :: uint [R] The unique index of this GUI element.
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 [R] Direction of the layout.
style :: LuaStyle or string [RW] The style of this element.
visible :: boolean [RW] When not visible the GUI element is hidden completely and takes no space in the layout.
text :: string [RW] The text contained in a textfield or text-box.
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] The image to display on this sprite-button or sprite in the default state.
resize_to_sprite :: boolean [RW] Whether should the image widget resize its size according to the sprite in it (true by default)
hovered_sprite :: SpritePath [RW] The image to display on this sprite-button when it is hovered.
clicked_sprite :: SpritePath [RW] The image to display on this sprite-button when it is clicked.
tooltip :: LocalisedString [RW]
horizontal_scroll_policy :: string [RW] Policy of the horizontal scroll bar, possible values are "auto" (default), "never", "always", "auto-and-reserve-space".
vertical_scroll_policy :: string [RW] Policy of the vertical scroll bar, possible values are "auto" (default), "never", "always", "auto-and-reserve-space".
type :: string [R] The type of this GUI element.
children :: array of LuaGuiElement [R] The children elements
items :: array of LocalisedString [RW] The items in this dropdown or listbox.
selected_index :: uint [RW] The selected index for this dropdown or listbox.
number :: double [RW] The number to be shown in the right-bottom corner of the sprite-button, or nil to show nothing.
show_percent_for_small_numbers :: boolean [RW] Related to the number to be shown in the right-bottom corner of the sprite-button.
position :: Position [RW] The position this camera or minimap is focused on if any.
surface_index :: uint [RW] The surface index this camera or minimap is using.
zoom :: double [RW] The zoom this camera or minimap is using.
minimap_player_index :: uint [RW] The player index this minimap is using.
force :: string [RW] The force this minimap is using or nil if no force is set.
elem_type :: string [R] The elem type of this choose-elem-button.
elem_value :: string or SignalID [RW] The elem value of this choose-elem-button or nil if there is no value.
selectable :: boolean [RW] If the contents of this text-box are selectable.
word_wrap :: boolean [RW] If this text-box will word-wrap automatically.
read_only :: boolean [RW] If this text-box is read-only.
enabled :: boolean [RW] If this GUI element is enabled.
ignored_by_interaction :: boolean [RW] If this GUI element is ignored by interaction.
locked :: boolean [RW] If this choose-elem-button can be changed by the player.
draw_vertical_lines :: boolean [RW] If this table should draw vertical grid lines.
draw_horizontal_lines :: boolean [RW] If this table should draw horizontal grid lines.
draw_horizontal_line_after_headers :: boolean [RW] If this table should draw a horizontal grid line after the headers.
column_count :: uint [R] The number of columns in this table.
slider_value :: double [RW] The value of this slider element.
mouse_button_filter :: dictionary stringboolean [RW] The mouse button filters for this button or sprite-button.
entity :: LuaEntity [RW] The entity associated with this entity-preview or nil if no entity is associated.
valid :: boolean [R] Is this object valid?
help() → string All methods, and properties that this object supports.

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, never mind, I don't like your face"
add{type=…, name=…, caption=…, tooltip=…, enabled=…, ignored_by_interaction=…, 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", "progressbar", "table", "textfield", "radiobutton", "sprite", "scroll-pane", "drop-down", "list-box", "camera", "choose-elem-button", "text-box", "slider", "minimap", or "entity-preview".
  • name :: string: Name of the child element.
  • caption :: LocalisedString (optional): The text displayed on the child element. For frames, this is the "heading". For other elements, like buttons or labels, this is the content. Whilst this attribute may be used on all elements, it doesn't make sense for tables and flows as they won't display it.
  • tooltip :: LocalisedString (optional): Tooltip of the child element.
  • enabled :: boolean (optional): Whether the child element is enabled.
  • ignored_by_interaction :: boolean (optional): Whether the child element is ignored by interaction.
  • style :: string (optional): Style of the new element.
  • Other attributes may have to be specified, depending on type
    • button
      • mouse_button_filter :: MouseButtonFlags (optional): Which mouse buttons the button responds to.
    • flow
    • frame
    • table
      • column_count :: uint: Number of columns.
      • draw_vertical_lines :: boolean (optional): If the table should draw vertical grid lines. Defaults to false if not given.
      • draw_horizontal_lines :: boolean (optional): If the table should draw horizontal grid lines. Defaults to false if not given.
      • draw_horizontal_line_after_headers :: boolean (optional): If the table should draw a horizontal grid line after the headers. Defaults to false if not given.
    • textfield
      • text :: string (optional): The initial text contained in the textfield.
    • progressbar
      • value :: double (optional): Initial value of the progressbar, in range [0, 1]. Defaults to 0 if not given.
    • checkbox
      • state :: boolean: Whether the checkbox should be checked by default.
    • radiobutton
      • state :: boolean: Whether the radiobutton should be checked by default.
    • sprite-button
      • sprite :: SpritePath (optional): Path to the image to display on the button.
      • hovered_sprite :: SpritePath (optional): Path to the image to display on the button when it is hovered.
      • clicked_sprite :: SpritePath (optional): Path to the image to display on the button when it is clicked.
      • number :: double (optional): The number shown on the button.
      • show_percent_for_small_numbers :: boolean (optional): Format small numbers as percentages. Defaults to false if not given.
      • mouse_button_filter :: MouseButtonFlags (optional): Which mouse buttons the button responds to.
    • sprite
      • sprite :: SpritePath (optional): Path to the image to display.
    • scroll-pane
      • horizontal_scroll_policy :: string (optional): Policy of the horizontal scroll bar, possible values are "auto" (default), "never", "always", "auto-and-reserve-space".
      • vertical_scroll_policy :: string (optional): Policy of the vertical scroll bar, possible values are "auto" (default), "never", "always", "auto-and-reserve-space".
    • drop-down
      • items :: array of LocalisedString (optional): The initial items in the dropdown.
      • selected_index :: uint (optional): The initial selected index.
    • list-box
      • items :: array of LocalisedString (optional): The initial items in the listbox.
      • 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", "signal", "fluid", or "recipe".
      • item :: string (optional): If type is "item" - the default value for the button.
      • tile :: string (optional): If type is "tile" - the default value for the button.
      • entity :: string (optional): If type is "entity" - the default value for the button.
      • signal :: SignalID (optional): If type is "signal" - the default value for the button.
      • fluid :: string (optional): If type is "fluid" - the default value for the button.
      • recipe :: string (optional): If type is "recipe" - the default value for the button.
    • text-box
      • text :: string (optional): The initial text contained in the text-box.
    • slider
      • minimum_value :: double (optional): The minimum value for the slider
      • maximum_value :: double (optional): The maximum value for the slider
      • value :: double (optional): The initial value for the slider
    • minimap
      • position :: Position (optional): The position the minimap centers on or if not given it will center on the player that owns this element.
      • surface_index :: uint (optional): The surface the camera will render else if not given the players surface is used.
      • chart_player_index :: uint (optional): The player index the map should use else if not set the player that owns this element is used.
      • force :: string (optional): The force this minimap should use else if not given the players force that owns this element is used.
      • zoom :: double (optional): The camera zoom - defaults to 0.75.
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 or listbox.

get_item(index) → LocalisedString

Gets an item at the given index from this dropdown or listbox.

Parameters
index :: uint: The index to get.
set_item(index, LocalisedString)

Sets an item at the given index in this dropdown or listbox.

Parameters
index :: uint: The index
LocalisedString: The item.
add_item(LocalisedString, index)

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

Parameters
LocalisedString: The item.
index :: uint (optional): The index
remove_item(index)

Removes an item at the given index in this dropdown or listbox.

Parameters
index :: uint: The index
get_slider_minimum() → double

Gets this sliders minimum value.

get_slider_maximum() → double

Gets this sliders minimum value.

set_slider_minimum_maximum(minimum, maximum)

Sets this sliders minimum and maximum values.

Parameters
minimum :: double
maximum :: double
Note: The minimum can't be >= the maximum.
focus()

Focuses this GUI element if possible.

scroll_to_top()

Scrolls the scroll bar to the top.

Can only be used if this is scroll-pane or text-box
scroll_to_bottom()

Scrolls the scroll bar to the bottom.

Can only be used if this is scroll-pane or text-box
scroll_to_left()

Scrolls the scroll bar to the left.

Can only be used if this is scroll-pane or text-box
scroll_to_right()

Scrolls the scroll bar to the right.

Can only be used if this is scroll-pane or text-box
scroll_to_element(element, scroll_mode)

Scrolls the scroll bar such that the specified GUI element is visible to the player.

Parameters
element :: LuaGuiElement: The element to scroll to.
scroll_mode :: string (optional): Where the element should be positioned in the scroll-pane. Must be either: "in-view", or "top-third". Defaults to "in-view".
Can only be used if this is scroll-pane
select_all()

Select all text in the text box.

Can only be used if this is textfield or text-box
select(start, end)

Select a range of text in the text box.

Parameters
start :: int: The index of the first character to select.
end :: int: The index of the last character to select.
Example
Select the characters amp from example.
textbox.select(3, 5)
Example
Move the cursor to the start of the text box.
textbox.select(1, 0)
Can only be used if this is textfield or text-box
index :: uint [Read-only]

The unique index of this GUI element.

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

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

Can only be used if this is frame or flow
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.

visible :: boolean [Read-Write]

When not visible the GUI element is hidden completely and takes no space in the layout.

text :: string [Read-Write]

The text contained in a textfield or text-box.

Can only be used if this is 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]

The image to display on this sprite-button or sprite in the default state.

resize_to_sprite :: boolean [Read-Write]

Whether should the image widget resize its size according to the sprite in it (true by default)

hovered_sprite :: SpritePath [Read-Write]

The image to display on this sprite-button when it is hovered.

Can only be used if this is sprite-button
clicked_sprite :: SpritePath [Read-Write]

The image to display on this sprite-button when it is clicked.

tooltip :: LocalisedString [Read-Write]

horizontal_scroll_policy :: string [Read-Write]

Policy of the horizontal scroll bar, possible values are "auto" (default), "never", "always", "auto-and-reserve-space".

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

Policy of the vertical scroll bar, possible values are "auto" (default), "never", "always", "auto-and-reserve-space".

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 or listbox.

selected_index :: uint [Read-Write]

The selected index for this dropdown or listbox. 0 if none.

number :: double [Read-Write]

The number to be shown in the right-bottom corner of the sprite-button, or nil to show nothing.

show_percent_for_small_numbers :: boolean [Read-Write]

Related to the number to be shown in the right-bottom corner of the sprite-button. When set to true, numbers that are not 0 and smaller than one are shown as percent rather than the value, so for example 0.5 is shown as 50% instead.

position :: Position [Read-Write]

The position this camera or minimap is focused on if any.

surface_index :: uint [Read-Write]

The surface index this camera or minimap is using.

zoom :: double [Read-Write]

The zoom this camera or minimap is using.

minimap_player_index :: uint [Read-Write]

The player index this minimap is using.

Can only be used if this is minimap
force :: string [Read-Write]

The force this minimap is using or nil if no force is set.

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.

ignored_by_interaction :: boolean [Read-Write]

If this GUI element is ignored by interaction. This means, that for example, label on a button can't steal the focus or click events of the button.

locked :: boolean [Read-Write]

If this choose-elem-button can be changed by the player.

Can only be used if this is choose-elem-button
draw_vertical_lines :: boolean [Read-Write]

If this table should draw vertical grid lines.

Can only be used if this is table
draw_horizontal_lines :: boolean [Read-Write]

If this table should draw horizontal grid lines.

Can only be used if this is table
draw_horizontal_line_after_headers :: boolean [Read-Write]

If this table should draw a horizontal grid line after the headers.

Can only be used if this is table
column_count :: uint [Read-only]

The number of columns in this table.

Can only be used if this is table
slider_value :: double [Read-Write]

The value of this slider element.

Can only be used if this is slider
mouse_button_filter :: dictionary stringboolean [Read-Write]

The mouse button filters for this button or sprite-button.

The possible filters are:

  • "left-and-right"
  • "left"
  • "right"
  • "middle"
  • "button-4"
  • "button-5"
  • "button-6"
  • "button-7"
  • "button-8"
  • "button-9"

entity :: LuaEntity [Read-Write]

The entity associated with this entity-preview or nil if no entity is associated.

Can only be used if this is entity-preview