LuaGuiElement - Runtime Docs

ClassLuaGuiElementchanged

An element of a custom GUI. This type is used to represent any kind of a GUI element - labels, buttons and 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 column_count of a textfield) will result in a runtime error.

For information on all supported GUI elements, see GuiElementType.

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.

Examples

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

-- This will add a tabbed-pane and 2 tabs with contents.
local tabbed_pane = game.player.gui.top.add{type="tabbed-pane"}
local tab1 = tabbed_pane.add{type="tab", caption="Tab 1"}
local tab2 = tabbed_pane.add{type="tab", caption="Tab 2"}
local label1 = tabbed_pane.add{type="label", caption="Label 1"}
local label2 = tabbed_pane.add{type="label", caption="Label 2"}
tabbed_pane.add_tab(tab1, label1)
tabbed_pane.add_tab(tab2, label2)

Members

add{type=…, name?=…, caption?=…, tooltip?=…, elem_tooltip?=…, enabled?=…, visible?=…, ignored_by_interaction?=…, style?=…, tags?=…, index?=…, anchor?=…, game_controller_interaction?=…, raise_hover_events?=…}	→ LuaGuiElement	Add a new child element to this GuiElement.
Add a new child element to this GuiElement.
clear()		Remove children of this element. [...]
Remove children of this element. [...]
destroy()		Remove this element, along with its children. [...]
Remove this element, along with its children. [...]
get_mod()	→ string?	The mod that owns this Gui element or `nil` if it's owned by the scenario script. [...]
The mod that owns this Gui element or `nil` if it's owned by the scenario script. [...]
get_index_in_parent()	→ uint	Gets the index that this element has in its parent element. [...]
Gets the index that this element has in its parent element. [...]
swap_children(index_1, index_2)		Swaps the children at the given indices in this element.
Swaps the children at the given indices in this element.
clear_items()		Removes the items in this dropdown or listbox.
Removes the items in this dropdown or listbox.
get_item(index)	→ LocalisedString	Gets the item at the given index from this dropdown or listbox.
Gets the item at the given index from this dropdown or listbox.
set_item(index, string)		Sets the given string at the given index in this dropdown or listbox.
Sets the given string at the given index in this dropdown or listbox.
add_item(string, index?)		Inserts a string at the end or at the given index of this dropdown or listbox.
Inserts a string at the end or at the given index of this dropdown or listbox.
remove_item(index)		Removes the item at the given index from this dropdown or listbox.
Removes the item at the given index from this dropdown or listbox.
get_slider_minimum()	→ double	Gets this sliders minimum value.
Gets this sliders minimum value.
get_slider_maximum()	→ double	Gets this sliders maximum value.
Gets this sliders maximum value.
set_slider_minimum_maximum(minimum, maximum)		Sets this sliders minimum and maximum values. [...]
Sets this sliders minimum and maximum values. [...]
get_slider_value_step()	→ double	Gets the minimum distance this slider can move.
Gets the minimum distance this slider can move.
get_slider_discrete_values()	→ boolean	Returns whether this slider only allows discrete values.
Returns whether this slider only allows discrete values.
set_slider_value_step(value)		Sets the minimum distance this slider can move. [...]
Sets the minimum distance this slider can move. [...]
set_slider_discrete_values(value)		Sets whether this slider only allows discrete values.
Sets whether this slider only allows discrete values.
focus()		Focuses this GUI element if possible.
Focuses this GUI element if possible.
scroll_to_top()		Scrolls this scroll bar to the top.
Scrolls this scroll bar to the top.
scroll_to_bottom()		Scrolls this scroll bar to the bottom.
Scrolls this scroll bar to the bottom.
scroll_to_left()		Scrolls this scroll bar to the left.
Scrolls this scroll bar to the left.
scroll_to_right()		Scrolls this scroll bar to the right.
Scrolls this scroll bar to the right.
scroll_to_element(element, scroll_mode?)		Scrolls this scroll bar such that the specified GUI element is visible to the player.
Scrolls this scroll bar such that the specified GUI element is visible to the player.
select_all()		Selects all the text in this textbox.
Selects all the text in this textbox.
select(start_index, end_index)		Selects a range of text in this textbox.
Selects a range of text in this textbox.
add_tab(tab, content)		Adds the given tab and content widgets to this tabbed pane as a new tab.
Adds the given tab and content widgets to this tabbed pane as a new tab.
remove_tab(tab?) changed		Removes the given tab and its associated content from this tabbed pane. [...]
Removes the given tab and its associated content from this tabbed pane. [...]
force_auto_center()		Forces this frame to re-auto-center. [...]
Forces this frame to re-auto-center. [...]
scroll_to_item(index, scroll_mode?)		Scrolls the scroll bar such that the specified listbox item is visible to the player.
Scrolls the scroll bar such that the specified listbox item is visible to the player.
bring_to_front()		Moves this GUI element to the "front" so it will draw over other elements. [...]
Moves this GUI element to the "front" so it will draw over other elements. [...]
close_dropdown()		Closes the dropdown list if this is a dropdown and it is open.
Closes the dropdown list if this is a dropdown and it is open.
index	:: R uint	The index of this GUI element (unique amongst the GUI elements of a LuaPlayer).
The index of this GUI element (unique amongst the GUI elements of a LuaPlayer).
gui	:: R LuaGui	The GUI this element is a child of.
The GUI this element is a child of.
parent	:: R LuaGuiElement?	The direct parent of this element. [...]
The direct parent of this element. [...]
name	:: RW string	The name of this element. [...]
The name of this element. [...]
caption	:: RW LocalisedString	The text displayed on this element. [...]
The text displayed on this element. [...]
value	:: RW double	How much this progress bar is filled. [...]
How much this progress bar is filled. [...]
direction	:: R GuiDirection	Direction of this element's layout.
Direction of this element's layout.
style	:: RW LuaStyle or string	The style of this element. [...]
The style of this element. [...]
visible	:: RW boolean	Sets whether this GUI element is visible or completely hidden, taking no space in the layout.
Sets whether this GUI element is visible or completely hidden, taking no space in the layout.
text	:: RW string	The text contained in this textfield or text-box.
The text contained in this textfield or text-box.
children_names	:: R array[string]	Names of all the children of this element. [...]
Names of all the children of this element. [...]
state	:: RW boolean	Is this checkbox or radiobutton checked?
Is this checkbox or radiobutton checked?
player_index	:: R uint	Index into LuaGameScript::players specifying the player who owns this element.
Index into LuaGameScript::players specifying the player who owns this element.
sprite	:: RW SpritePath	The sprite to display on this sprite-button or sprite in the default state.
The sprite to display on this sprite-button or sprite in the default state.
resize_to_sprite	:: RW boolean	Whether the sprite widget should resize according to the sprite in it. [...]
Whether the sprite widget should resize according to the sprite in it. [...]
hovered_sprite	:: RW SpritePath	The sprite to display on this sprite-button when it is hovered.
The sprite to display on this sprite-button when it is hovered.
clicked_sprite	:: RW SpritePath	The sprite to display on this sprite-button when it is clicked.
The sprite to display on this sprite-button when it is clicked.
tooltip	:: RW LocalisedString	The text to display when hovering over this element. [...]
The text to display when hovering over this element. [...]
elem_tooltip	:: RW ElemID?	The element tooltip to display when hovering over this element, or `nil`.
The element tooltip to display when hovering over this element, or `nil`.
horizontal_scroll_policy	:: RW ScrollPolicy	Policy of the horizontal scroll bar.
Policy of the horizontal scroll bar.
vertical_scroll_policy	:: RW ScrollPolicy	Policy of the vertical scroll bar.
Policy of the vertical scroll bar.
type	:: R GuiElementType	The type of this GUI element.
The type of this GUI element.
children	:: R array[LuaGuiElement]	The child-elements of this GUI element.
The child-elements of this GUI element.
items	:: RW array[LocalisedString]	The items in this dropdown or listbox.
The items in this dropdown or listbox.
selected_index	:: RW uint	The selected index for this dropdown or listbox. [...]
The selected index for this dropdown or listbox. [...]
number	:: RW double?	The number to be shown in the bottom right corner of this sprite-button, or `nil` to show nothing.
The number to be shown in the bottom right corner of this sprite-button, or `nil` to show nothing.
show_percent_for_small_numbers	:: RW boolean	Related to the number to be shown in the bottom right corner of this sprite-button. [...]
Related to the number to be shown in the bottom right corner of this sprite-button. [...]
location	:: RW GuiLocation?	The location of this widget when stored in LuaGui::screen. [...]
The location of this widget when stored in LuaGui::screen. [...]
auto_center	:: RW boolean	Whether this frame auto-centers on window resize when stored in LuaGui::screen.
Whether this frame auto-centers on window resize when stored in LuaGui::screen.
badge_text	:: RW LocalisedString	The text to display after the normal tab text (designed to work with numbers)
The text to display after the normal tab text (designed to work with numbers)
auto_toggle	:: RW boolean	Whether this button will automatically toggle when clicked.
Whether this button will automatically toggle when clicked.
toggled	:: RW boolean	Whether this button is currently toggled. [...]
Whether this button is currently toggled. [...]
game_controller_interaction	:: RW defines.game_controller_interaction	How this element should interact with game controllers.
How this element should interact with game controllers.
position	:: RW MapPosition	The position this camera or minimap is focused on, if any.
The position this camera or minimap is focused on, if any.
surface_index	:: RW uint	The surface index this camera or minimap is using.
The surface index this camera or minimap is using.
zoom	:: RW double	The zoom this camera or minimap is using. [...]
The zoom this camera or minimap is using. [...]
minimap_player_index	:: RW uint	The player index this minimap is using.
The player index this minimap is using.
force	:: RW string?	The force this minimap is using, if any.
The force this minimap is using, if any.
elem_type	:: R ElemType	The elem type of this choose-elem-button.
The elem type of this choose-elem-button.
elem_value changed	:: RW string or SignalID or table?	The elem value of this choose-elem-button, if any. [...]
The elem value of this choose-elem-button, if any. [...]
elem_filters	:: RW PrototypeFilter?	The elem filters of this choose-elem-button, if any. [...]
The elem filters of this choose-elem-button, if any. [...]
selectable	:: RW boolean	Whether the contents of this text-box are selectable. [...]
Whether the contents of this text-box are selectable. [...]
word_wrap	:: RW boolean	Whether this text-box will word-wrap automatically. [...]
Whether this text-box will word-wrap automatically. [...]
read_only	:: RW boolean	Whether this text-box is read-only. [...]
Whether this text-box is read-only. [...]
enabled	:: RW boolean	Whether this GUI element is enabled. [...]
Whether this GUI element is enabled. [...]
ignored_by_interaction	:: RW boolean	Whether this GUI element is ignored by interaction. [...]
Whether this GUI element is ignored by interaction. [...]
locked	:: RW boolean	Whether this choose-elem-button can be changed by the player.
Whether this choose-elem-button can be changed by the player.
draw_vertical_lines	:: RW boolean	Whether this table should draw vertical grid lines.
Whether this table should draw vertical grid lines.
draw_horizontal_lines	:: RW boolean	Whether this table should draw horizontal grid lines.
Whether this table should draw horizontal grid lines.
draw_horizontal_line_after_headers	:: RW boolean	Whether this table should draw a horizontal grid line below the first table row.
Whether this table should draw a horizontal grid line below the first table row.
column_count	:: R uint	The number of columns in this table.
The number of columns in this table.
vertical_centering	:: RW boolean	Whether the content of this table should be vertically centered. [...]
Whether the content of this table should be vertically centered. [...]
slider_value	:: RW double	The value of this slider element.
The value of this slider element.
mouse_button_filter	:: RW MouseButtonFlags	The mouse button filters for this button or sprite-button.
The mouse button filters for this button or sprite-button.
numeric	:: RW boolean	Whether this textfield is limited to only numeric characters.
Whether this textfield is limited to only numeric characters.
allow_decimal	:: RW boolean	Whether this textfield (when in numeric mode) allows decimal numbers.
Whether this textfield (when in numeric mode) allows decimal numbers.
allow_negative	:: RW boolean	Whether this textfield (when in numeric mode) allows negative numbers.
Whether this textfield (when in numeric mode) allows negative numbers.
is_password	:: RW boolean	Whether this textfield displays as a password field, which renders all characters as `*`.
Whether this textfield displays as a password field, which renders all characters as `*`.
lose_focus_on_confirm	:: RW boolean	Whether this textfield loses focus after defines.events.on_gui_confirmed is fired.
Whether this textfield loses focus after defines.events.on_gui_confirmed is fired.
drag_target	:: RW LuaGuiElement?	The `frame` that is being moved when dragging this GUI element, if any. [...]
The `frame` that is being moved when dragging this GUI element, if any. [...]
selected_tab_index	:: RW uint?	The selected tab index for this tabbed pane, if any.
The selected tab index for this tabbed pane, if any.
tabs	:: R array[TabAndContent]	The tabs and contents being shown in this tabbed-pane.
The tabs and contents being shown in this tabbed-pane.
entity	:: RW LuaEntity?	The entity associated with this entity-preview, camera, minimap, if any.
The entity associated with this entity-preview, camera, minimap, if any.
anchor	:: RW GuiAnchor?	The anchor for this relative widget, if any. [...]
The anchor for this relative widget, if any. [...]
tags	:: RW Tags	The tags associated with this LuaGuiElement.
The tags associated with this LuaGuiElement.
raise_hover_events	:: RW boolean	Whether this element will raise on_gui_hover and on_gui_leave.
Whether this element will raise on_gui_hover and on_gui_leave.
switch_state	:: RW SwitchState	The switch state for this switch. [...]
The switch state for this switch. [...]
allow_none_state	:: RW boolean	Whether the `"none"` state is allowed for this switch. [...]
Whether the `"none"` state is allowed for this switch. [...]
left_label_caption	:: RW LocalisedString	The text shown for the left switch label.
The text shown for the left switch label.
left_label_tooltip	:: RW LocalisedString	The tooltip shown on the left switch label.
The tooltip shown on the left switch label.
right_label_caption	:: RW LocalisedString	The text shown for the right switch label.
The text shown for the right switch label.
right_label_tooltip	:: RW LocalisedString	The tooltip shown on the right switch label.
The tooltip shown on the right switch label.
valid	:: R boolean	Is this object valid? [...]
Is this object valid? [...]
object_name	:: R string	The class name of this object. [...]
The class name of this object. [...]
[] (index)	:: R LuaGuiElement?	The indexing operator. [...]
The indexing operator. [...]

Methods

add{type=…, name?=…, caption?=…, tooltip?=…, elem_tooltip?=…, enabled?=…, visible?=…, ignored_by_interaction?=…, style?=…, tags?=…, index?=…, anchor?=…, game_controller_interaction?=…, raise_hover_events?=…} → LuaGuiElement

Add a new child element to this GuiElement.

Parameters

Table with the following fields:

type	:: GuiElementType	The kind of element to add, which potentially has its own attributes as listed below.
The kind of element to add, which potentially has its own attributes as listed below.
name	:: string?	Name of the child element. It must be unique within the parent element.
Name of the child element. It must be unique within the parent element.
caption	:: LocalisedString?	Text displayed on the child element. For frames, this is their title. 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.
Text displayed on the child element. For frames, this is their title. 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?	Tooltip of the child element.
Tooltip of the child element.
elem_tooltip	:: ElemID?	Elem tooltip of the child element. Will be displayed above `tooltip`.
Elem tooltip of the child element. Will be displayed above `tooltip`.
enabled	:: boolean?	Whether the child element is enabled. Defaults to `true`.
Whether the child element is enabled. Defaults to `true`.
visible	:: boolean?	Whether the child element is visible. Defaults to `true`.
Whether the child element is visible. Defaults to `true`.
ignored_by_interaction	:: boolean?	Whether the child element is ignored by interaction. Defaults to `false`.
Whether the child element is ignored by interaction. Defaults to `false`.
style	:: string?	The name of the style prototype to apply to the new element.
The name of the style prototype to apply to the new element.
tags	:: Tags?	Tags associated with the child element.
Tags associated with the child element.
index	:: uint?	Location in its parent that the child element should slot into. By default, the child will be appended onto the end.
Location in its parent that the child element should slot into. By default, the child will be appended onto the end.
anchor	:: GuiAnchor?	Where to position the child element when in the `relative` element.
Where to position the child element when in the `relative` element.
game_controller_interaction	:: defines.game_controller_interaction?	How the element should interact with game controllers. Defaults to defines.game_controller_interaction.normal.
How the element should interact with game controllers. Defaults to defines.game_controller_interaction.normal.
raise_hover_events	:: boolean?	Whether this element will raise on_gui_hover and on_gui_leave. Defaults to `false`.
Whether this element will raise on_gui_hover and on_gui_leave. Defaults to `false`.

Other attributes may be specified depending on type:

`button`

mouse_button_filter	:: MouseButtonFlags?	Which mouse buttons the button responds to. Defaults to `"left-and-right"`.
Which mouse buttons the button responds to. Defaults to `"left-and-right"`.
auto_toggle	:: boolean?	Whether the button will automatically toggle when clicked. Defaults to `false`.
Whether the button will automatically toggle when clicked. Defaults to `false`.
toggled	:: boolean?	The initial toggled state of the button. Defaults to `false`.
The initial toggled state of the button. Defaults to `false`.

`flow`

direction	:: GuiDirection?	The initial direction of the flow's layout. Defaults to `"horizontal"`.
The initial direction of the flow's layout. Defaults to `"horizontal"`.

`frame`

direction	:: GuiDirection?	The initial direction of the frame's layout. Defaults to `"horizontal"`.
The initial direction of the frame's layout. Defaults to `"horizontal"`.

`table`

column_count	:: uint	Number of columns. This can't be changed after the table is created.
Number of columns. This can't be changed after the table is created.
draw_vertical_lines	:: boolean?	Whether the table should draw vertical grid lines. Defaults to `false`.
Whether the table should draw vertical grid lines. Defaults to `false`.
draw_horizontal_lines	:: boolean?	Whether the table should draw horizontal grid lines. Defaults to `false`.
Whether the table should draw horizontal grid lines. Defaults to `false`.
draw_horizontal_line_after_headers	:: boolean?	Whether the table should draw a single horizontal grid line after the headers. Defaults to `false`.
Whether the table should draw a single horizontal grid line after the headers. Defaults to `false`.
vertical_centering	:: boolean?	Whether the content of the table should be vertically centered. Defaults to `true`.
Whether the content of the table should be vertically centered. Defaults to `true`.

`textfield`

text	:: string?	The initial text contained in the textfield.
The initial text contained in the textfield.
numeric	:: boolean?	Defaults to `false`.
Defaults to `false`.
allow_decimal	:: boolean?	Defaults to `false`.
Defaults to `false`.
allow_negative	:: boolean?	Defaults to `false`.
Defaults to `false`.
is_password	:: boolean?	Defaults to `false`.
Defaults to `false`.
lose_focus_on_confirm	:: boolean?	Defaults to `false`.
Defaults to `false`.
icon_selector	:: boolean?	Whether to add the rich text icon selector to the text field. This attribute can't be changed after creating the widget. Defaults to `false`.
Whether to add the rich text icon selector to the text field. This attribute can't be changed after creating the widget. Defaults to `false`.

`progressbar`

value	:: double?	The initial value of the progressbar, in the range `[0, 1]`. Defaults to `0`.
The initial value of the progressbar, in the range `[0, 1]`. Defaults to `0`.

`checkbox`

state	:: boolean	The initial checked-state of the checkbox.
The initial checked-state of the checkbox.

`radiobutton`

state	:: boolean	The initial checked-state of the radiobutton.
The initial checked-state of the radiobutton.

`sprite-button`

sprite	:: SpritePath?	Path to the image to display on the button.
Path to the image to display on the button.
hovered_sprite	:: SpritePath?	Path to the image to display on the button when it is hovered.
Path to the image to display on the button when it is hovered.
clicked_sprite	:: SpritePath?	Path to the image to display on the button when it is clicked.
Path to the image to display on the button when it is clicked.
number	:: double?	The number shown on the button.
The number shown on the button.
show_percent_for_small_numbers	:: boolean?	Formats small numbers as percentages. Defaults to `false`.
Formats small numbers as percentages. Defaults to `false`.
mouse_button_filter	:: MouseButtonFlags?	The mouse buttons that the button responds to. Defaults to `"left-and-right"`.
The mouse buttons that the button responds to. Defaults to `"left-and-right"`.
auto_toggle	:: boolean?	Whether the button will automatically toggle when clicked. Defaults to `false`.
Whether the button will automatically toggle when clicked. Defaults to `false`.
toggled	:: boolean?	The initial toggled state of the button. Defaults to `false`.
The initial toggled state of the button. Defaults to `false`.

`sprite`

sprite	:: SpritePath?	Path to the image to display.
Path to the image to display.
resize_to_sprite	:: boolean?	Whether the widget should resize according to the sprite in it. Defaults to `true`.
Whether the widget should resize according to the sprite in it. Defaults to `true`.

`scroll-pane`

horizontal_scroll_policy	:: ScrollPolicy?	Policy of the horizontal scroll bar. Defaults to `"auto"`.
Policy of the horizontal scroll bar. Defaults to `"auto"`.
vertical_scroll_policy	:: ScrollPolicy?	Policy of the vertical scroll bar. Defaults to `"auto"`.
Policy of the vertical scroll bar. Defaults to `"auto"`.

`drop-down`

items	:: array[LocalisedString]?	The initial items in the dropdown.
The initial items in the dropdown.
selected_index	:: uint?	The index of the initially selected item. Defaults to 0.
The index of the initially selected item. Defaults to 0.

`line`

direction	:: GuiDirection?	The initial direction of the line. Defaults to `"horizontal"`.
The initial direction of the line. Defaults to `"horizontal"`.

`list-box`

items	:: array[LocalisedString]?	The initial items in the listbox.
The initial items in the listbox.
selected_index	:: uint?	The index of the initially selected item. Defaults to 0.
The index of the initially selected item. Defaults to 0.

`camera`

position	:: MapPosition	The position the camera centers on.
The position the camera centers on.
surface_index	:: uint?	The surface that the camera will render. Defaults to the player's current surface.
The surface that the camera will render. Defaults to the player's current surface.
zoom	:: double?	The initial camera zoom. Defaults to `0.75`.
The initial camera zoom. Defaults to `0.75`.

`choose-elem-button`

elem_type	:: ElemType	The type of the button.
The type of the button.
item	:: string?	If type is `"item"` - the default value for the button.
If type is `"item"` - the default value for the button.
tile	:: string?	If type is `"tile"` - the default value for the button.
If type is `"tile"` - the default value for the button.
entity	:: string?	If type is `"entity"` - the default value for the button.
If type is `"entity"` - the default value for the button.
signal	:: SignalID?	If type is `"signal"` - the default value for the button.
If type is `"signal"` - the default value for the button.
fluid	:: string?	If type is `"fluid"` - the default value for the button.
If type is `"fluid"` - the default value for the button.
recipe	:: string?	If type is `"recipe"` - the default value for the button.
If type is `"recipe"` - the default value for the button.
decorative	:: string?	If type is `"decorative"` - the default value for the button.
If type is `"decorative"` - the default value for the button.
item-group	:: string?	If type is `"item-group"` - the default value for the button.
If type is `"item-group"` - the default value for the button.
achievement	:: string?	If type is `"achievement"` - the default value for the button.
If type is `"achievement"` - the default value for the button.
equipment	:: string?	If type is `"equipment"` - the default value for the button.
If type is `"equipment"` - the default value for the button.
technology	:: string?	If type is `"technology"` - the default value for the button.
If type is `"technology"` - the default value for the button.
item-with-quality	:: string?	If type is `"item-with-quality"` - the default value for the button.
If type is `"item-with-quality"` - the default value for the button.
entity-with-quality	:: string?	If type is `"entity-with-quality"` - the default value for the button.
If type is `"entity-with-quality"` - the default value for the button.
recipe-with-quality	:: string?	If type is `"recipe-with-quality"` - the default value for the button.
If type is `"recipe-with-quality"` - the default value for the button.
equipment-with-quality	:: string?	If type is `"equipment-with-quality"` - the default value for the button.
If type is `"equipment-with-quality"` - the default value for the button.
elem_filters	:: PrototypeFilter?	Filters describing what to show in the selection window. The applicable filter depends on the `elem_type`.
Filters describing what to show in the selection window. The applicable filter depends on the `elem_type`.

`text-box`

text	:: string?	The initial text contained in the text-box.
The initial text contained in the text-box.
icon_selector	:: boolean?	Whether to add the rich text icon selector to the text box. This attribute can't be changed after creating the widget. Defaults to `false`.
Whether to add the rich text icon selector to the text box. This attribute can't be changed after creating the widget. Defaults to `false`.

`slider`

minimum_value	:: double?	The minimum value for the slider. Defaults to `0`.
The minimum value for the slider. Defaults to `0`.
maximum_value	:: double?	The maximum value for the slider. Defaults to `30`.
The maximum value for the slider. Defaults to `30`.
value	:: double?	The initial value for the slider. Defaults to `minimum_value`.
The initial value for the slider. Defaults to `minimum_value`.
value_step	:: double?	The minimum value the slider can move. Defaults to `1`.
The minimum value the slider can move. Defaults to `1`.
discrete_values	:: boolean?	Defaults to `true`.
Defaults to `true`.

`minimap`

position	:: MapPosition?	The position the minimap centers on. Defaults to the player's current position.
The position the minimap centers on. Defaults to the player's current position.
surface_index	:: uint?	The surface the camera will render. Defaults to the player's current surface.
The surface the camera will render. Defaults to the player's current surface.
chart_player_index	:: uint?	The player index the map should use. Defaults to the current player.
The player index the map should use. Defaults to the current player.
force	:: string?	The force this minimap should use. Defaults to the player's current force.
The force this minimap should use. Defaults to the player's current force.
zoom	:: double?	The initial camera zoom. Defaults to `0.75`.
The initial camera zoom. Defaults to `0.75`.

`tab`

badge_text	:: LocalisedString?	The text to display after the normal tab text (designed to work with numbers).
The text to display after the normal tab text (designed to work with numbers).

`switch`

switch_state	:: SwitchState?	If set to "none", `allow_none_state` must be `true`. Defaults to `"left"`.
If set to "none", `allow_none_state` must be `true`. Defaults to `"left"`.
allow_none_state	:: boolean?	Whether the switch can be set to a middle state. Defaults to `false`.
Whether the switch can be set to a middle state. Defaults to `false`.
left_label_caption	:: LocalisedString?
left_label_tooltip	:: LocalisedString?
right_label_caption	:: LocalisedString?
right_label_tooltip	:: LocalisedString?

Return values

→ LuaGuiElement

The GUI element that was added.

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.

The top-level GUI elements - LuaGui::top, LuaGui::left, LuaGui::center and LuaGui::screen - can't be destroyed.

Example

game.player.gui.top.greeting.destroy()

get_mod() → string?

The mod that owns this Gui element or nil if it's owned by the scenario script.

This has a not-super-expensive, but non-free cost to get.

get_index_in_parent() → uint

Gets the index that this element has in its parent element.

This iterates through the children of the parent of this element, meaning this has a non-free cost to get, but is faster than doing the equivalent in Lua.

swap_children(index_1, index_2)

Swaps the children at the given indices in this element.

Parameters

index_1	:: uint	The index of the first child.
The index of the first child.
index_2	:: uint	The index of the second child.
The index of the second child.

clear_items()

Removes the items in this dropdown or listbox.

Can only be used if this is drop-down or list-box

get_item(index) → LocalisedString

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

Parameters

index	:: uint	The index to get
The index to get

Can only be used if this is drop-down or list-box

set_item(index, string)

Sets the given string at the given index in this dropdown or listbox.

Parameters

index	:: uint	The index whose text to replace.
The index whose text to replace.
string	:: LocalisedString	The text to set at the given index.
The text to set at the given index.

Can only be used if this is drop-down or list-box

add_item(string, index?)

Inserts a string at the end or at the given index of this dropdown or listbox.

Parameters

string	:: LocalisedString	The text to insert.
The text to insert.
index	:: uint?	The index at which to insert the item.
The index at which to insert the item.

Can only be used if this is drop-down or list-box

remove_item(index)

Removes the item at the given index from this dropdown or listbox.

Parameters

index	:: uint	The index
The index

Can only be used if this is drop-down or list-box

get_slider_minimum() → double

Gets this sliders minimum value.

get_slider_maximum() → double

Gets this sliders maximum value.

set_slider_minimum_maximum(minimum, maximum)

Sets this sliders minimum and maximum values. The minimum can't be >= the maximum.

Parameters

minimum	:: double
maximum	:: double

get_slider_value_step() → double

Gets the minimum distance this slider can move.

get_slider_discrete_values() → boolean

Returns whether this slider only allows discrete values.

set_slider_value_step(value)

Sets the minimum distance this slider can move. The minimum distance can't be > (max - min).

Parameters

value

:: double

set_slider_discrete_values(value)

Sets whether this slider only allows discrete values.

Parameters

value

:: boolean

focus()

Focuses this GUI element if possible.

scroll_to_top()

Scrolls this scroll bar to the top.

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

scroll_to_bottom()

Scrolls this scroll bar to the bottom.

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

scroll_to_left()

Scrolls this scroll bar to the left.

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

scroll_to_right()

Scrolls this scroll bar to the right.

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

scroll_to_element(element, scroll_mode?)

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

Parameters

element	:: LuaGuiElement	The element to scroll to.
The element to scroll to.
scroll_mode	:: `"in-view"` or `"top-third"`?	Where the element should be positioned in the scroll-pane. Defaults to `"in-view"`.
Where the element should be positioned in the scroll-pane. Defaults to `"in-view"`.

Can only be used if this is scroll-pane

select_all()

Selects all the text in this textbox.

Can only be used if this is textfield or text-box

select(start_index, end_index)

Selects a range of text in this textbox.

Parameters

start_index	:: int	The index of the first character to select
The index of the first character to select
end_index	:: int	The index of the last character to select
The index of the last character to select

Can only be used if this is textfield or text-box

Examples

-- Select the characters "amp" from "example":
textbox.select(3, 5)

-- Move the cursor to the start of the text box:
textbox.select(1, 0)

add_tab(tab, content)

Adds the given tab and content widgets to this tabbed pane as a new tab.

Parameters

tab	:: LuaGuiElement	The tab to add, must be a GUI element of type "tab".
The tab to add, must be a GUI element of type "tab".
content	:: LuaGuiElement	The content to show when this tab is selected. Can be any type of GUI element.
The content to show when this tab is selected. Can be any type of GUI element.

Can only be used if this is tabbed-pane

remove_tab(tab?) changed

Removes the given tab and its associated content from this tabbed pane.

Removing a tab does not destroy the tab or the tab contents. It just removes them from the view. When removing tabs, LuaGuiElement::selected_tab_index needs to be manually updated.

Parameters

tab	:: LuaGuiElement?	The tab to remove or `nil` to remove all tabs.
The tab to remove or `nil` to remove all tabs.

Can only be used if this is tabbed-pane

force_auto_center()

Forces this frame to re-auto-center. Only works on frames stored directly in LuaGui::screen.

Raised events

on_gui_location_changed future_tick

Can only be used if this is frame

scroll_to_item(index, scroll_mode?)

Scrolls the scroll bar such that the specified listbox item is visible to the player.

Parameters

index	:: int	The item index to scroll to.
The item index to scroll to.
scroll_mode	:: `"in-view"` or `"top-third"`?	Where the item should be positioned in the list-box. Defaults to `"in-view"`.
Where the item should be positioned in the list-box. Defaults to `"in-view"`.

Can only be used if this is list-box

bring_to_front()

Moves this GUI element to the "front" so it will draw over other elements.

Only works for elements in LuaGui::screen.

close_dropdown()

Closes the dropdown list if this is a dropdown and it is open.

Attributes

index :: Read uint

The index of this GUI element (unique amongst the GUI elements of a LuaPlayer).

gui :: Read LuaGui

The GUI this element is a child of.

parent :: Read LuaGuiElement ?

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

name :: Read|Write string

The name of this element. "" if no name was set.

Example

game.player.gui.top.greeting.name == "greeting"

caption :: Read|Write LocalisedString

The text displayed on this 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 without producing an error, it doesn't make sense for tables and flows as they won't display it.

value :: Read|Write double

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

Can only be used if this is progressbar

direction :: Read GuiDirection

Direction of this element's layout.

Can only be used if this is frame or flow or line

style :: Read|Write LuaStyle or string

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

visible :: Read|Write boolean

Sets whether this GUI element is visible or completely hidden, taking no space in the layout.

text :: Read|Write string

The text contained in this textfield or text-box.

Can only be used if this is textfield or text-box

children_names :: Read array[string]

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 :: Read|Write boolean

Is this checkbox or radiobutton checked?

Can only be used if this is checkbox or radiobutton

player_index :: Read uint

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

sprite :: Read|Write SpritePath

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

Can only be used if this is sprite-button or sprite

resize_to_sprite :: Read|Write boolean

Whether the sprite widget should resize according to the sprite in it. Defaults to true.

Can only be used if this is sprite

hovered_sprite :: Read|Write SpritePath

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

Can only be used if this is sprite-button

clicked_sprite :: Read|Write SpritePath

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

Can only be used if this is sprite-button

horizontal_scroll_policy :: Read|Write ScrollPolicy

Policy of the horizontal scroll bar.

Can only be used if this is scroll-pane

vertical_scroll_policy :: Read|Write ScrollPolicy

Policy of the vertical scroll bar.

Can only be used if this is scroll-pane

type :: Read GuiElementType

The type of this GUI element.

children :: Read array[LuaGuiElement]

The child-elements of this GUI element.

items :: Read|Write array[LocalisedString]

The items in this dropdown or listbox.

Can only be used if this is drop-down or list-box

selected_index :: Read|Write uint

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

Can only be used if this is drop-down or list-box

number :: Read|Write double ?

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

Can only be used if this is sprite-button

show_percent_for_small_numbers :: Read|Write boolean

Related to the number to be shown in the bottom right corner of this sprite-button. When set to true, numbers that are non-zero and smaller than one are shown as a percentage rather than the value. For example, 0.5 will be shown as 50% instead.

Can only be used if this is sprite-button

location :: Read|Write GuiLocation ?

The location of this widget when stored in LuaGui::screen. nil if not set or not in LuaGui::screen.

auto_center :: Read|Write boolean

Whether this frame auto-centers on window resize when stored in LuaGui::screen.

Can only be used if this is frame

badge_text :: Read|Write LocalisedString

The text to display after the normal tab text (designed to work with numbers)

Can only be used if this is tab

auto_toggle :: Read|Write boolean

Whether this button will automatically toggle when clicked.

Can only be used if this is button or sprite-button

toggled :: Read|Write boolean

Whether this button is currently toggled. When a button is toggled, it will use the selected_graphical_set and selected_font_color defined in its style.

Can only be used if this is button or sprite-button

game_controller_interaction :: Read|Write defines.game_controller_interaction

How this element should interact with game controllers.

position :: Read|Write MapPosition

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

Can only be used if this is camera or minimap

surface_index :: Read|Write uint

The surface index this camera or minimap is using.

Can only be used if this is camera or minimap

zoom :: Read|Write double

The zoom this camera or minimap is using. This value must be positive.

Can only be used if this is camera or minimap

minimap_player_index :: Read|Write uint

The player index this minimap is using.

Can only be used if this is minimap

force :: Read|Write string ?

The force this minimap is using, if any.

Can only be used if this is minimap

elem_type :: Read ElemType

The elem type of this choose-elem-button.

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

elem_value :: Read|Write string or SignalID or table ?changed

The elem value of this choose-elem-button, if any.

The "signal" type operates with SignalID.

The "with-quality" types operate with "name" and optional "quality"

The remaining types use strings.

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

elem_filters :: Read|Write PrototypeFilter ?

The elem filters of this choose-elem-button, if any. The compatible type of filter is determined by elem_type.

Writing to this field does not change or clear the currently selected element.

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

Examples

-- This will configure a choose-elem-button of type "entity" to only show items of type "furnace".
button.elem_filters = {{filter = "type", type = "furnace"}}

-- Then, there are some types of filters that work on a specific kind of attribute. The following will configure a
--   choose-elem-button of type "entity" to only show entities that have their "hidden" flags set.
button.elem_filters = {{filter = "hidden"}}

-- Lastly, these filters can be combined at will, taking care to specify how they should be combined (either "and" or "or").
--   The following will filter for any entities that are "furnaces" and that are not "hidden".
button.elem_filters = {{filter = "type", type = "furnace"}, {filter = "hidden", invert = true, mode = "and"}}

selectable :: Read|Write boolean

Whether the contents of this text-box are selectable. Defaults to true.

Can only be used if this is text-box

word_wrap :: Read|Write boolean

Whether this text-box will word-wrap automatically. Defaults to false.

Can only be used if this is text-box

read_only :: Read|Write boolean

Whether this text-box is read-only. Defaults to false.

Can only be used if this is text-box

enabled :: Read|Write boolean

Whether this GUI element is enabled. Disabled GUI elements don't trigger events when clicked.

ignored_by_interaction :: Read|Write boolean

Whether this GUI element is ignored by interaction. This makes clicks on this element 'go through' to the GUI element or even the game surface below it.

locked :: Read|Write boolean

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

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

draw_vertical_lines :: Read|Write boolean

Whether this table should draw vertical grid lines.

Can only be used if this is table

draw_horizontal_lines :: Read|Write boolean

Whether this table should draw horizontal grid lines.

Can only be used if this is table

draw_horizontal_line_after_headers :: Read|Write boolean

Whether this table should draw a horizontal grid line below the first table row.

Can only be used if this is table

column_count :: Read uint

The number of columns in this table.

Can only be used if this is table

vertical_centering :: Read|Write boolean

Whether the content of this table should be vertically centered. Overrides LuaStyle::column_alignments. Defaults to true.

Can only be used if this is table

slider_value :: Read|Write double

The value of this slider element.

Can only be used if this is slider

mouse_button_filter :: Read|Write MouseButtonFlags

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

Can only be used if this is button or sprite-button

numeric :: Read|Write boolean

Whether this textfield is limited to only numeric characters.

Can only be used if this is textfield

allow_decimal :: Read|Write boolean

Whether this textfield (when in numeric mode) allows decimal numbers.

Can only be used if this is textfield

allow_negative :: Read|Write boolean

Whether this textfield (when in numeric mode) allows negative numbers.

Can only be used if this is textfield

is_password :: Read|Write boolean

Whether this textfield displays as a password field, which renders all characters as *.

Can only be used if this is textfield

lose_focus_on_confirm :: Read|Write boolean

Whether this textfield loses focus after defines.events.on_gui_confirmed is fired.

Can only be used if this is textfield

drag_target :: Read|Write LuaGuiElement ?

The frame that is being moved when dragging this GUI element, if any. This element needs to be a child of the drag_target at some level.

Only top-level elements in LuaGui::screen can be drag_targets.

Can only be used if this is flow or frame or label or table or empty-widget

Example

-- This creates a frame that contains a dragging handle which can move the frame.
local frame = player.gui.screen.add{type="frame", direction="vertical"}
local dragger = frame.add{type="empty-widget", style="draggable_space"}
dragger.style.size = {128, 24}
dragger.drag_target = frame

selected_tab_index :: Read|Write uint ?

The selected tab index for this tabbed pane, if any.

Can only be used if this is tabbed-pane

tabs :: Read array[TabAndContent]

The tabs and contents being shown in this tabbed-pane.

Can only be used if this is tabbed-pane

entity :: Read|Write LuaEntity ?

The entity associated with this entity-preview, camera, minimap, if any.

Can only be used if this is entity-preview or camera or minimap

anchor :: Read|Write GuiAnchor ?

The anchor for this relative widget, if any. Setting nil clears the anchor.

tags :: Read|Write Tags

The tags associated with this LuaGuiElement.

raise_hover_events :: Read|Write boolean

Whether this element will raise on_gui_hover and on_gui_leave.

switch_state :: Read|Write SwitchState

The switch state for this switch.

If LuaGuiElement::allow_none_state is false this can't be set to "none".

Can only be used if this is switch

allow_none_state :: Read|Write boolean

Whether the "none" state is allowed for this switch.

This can't be set to false if the current switch_state is 'none'.

Can only be used if this is switch

left_label_caption :: Read|Write LocalisedString

The text shown for the left switch label.

Can only be used if this is switch

right_label_caption :: Read|Write LocalisedString

The text shown for the right switch label.

Can only be used if this is switch

valid :: Read boolean

Is this object valid? This Lua object holds a reference to an object within the game engine. It is possible that the game-engine object is removed whilst a mod still holds the corresponding Lua object. If that happens, the object becomes invalid, i.e. this attribute will be false. Mods are advised to check for object validity if any change to the game state might have occurred between the creation of the Lua object and its access.

object_name :: Read string

The class name of this object. Available even when valid is false. For LuaStruct objects it may also be suffixed with a dotted path to a member of the struct.

Operators

[] (index)

The indexing operator. Gets children by name.

Factorio Runtime DocsVersion 2.0.19

ClassLuaGuiElementchanged

Examples

Members

Methods

add{type=…, name?=…, caption?=…, tooltip?=…, elem_tooltip?=…, enabled?=…, visible?=…, ignored_by_interaction?=…, style?=…, tags?=…, index?=…, anchor?=…, game_controller_interaction?=…, raise_hover_events?=…} → LuaGuiElement

Parameters

button

flow

frame

table

textfield

progressbar

checkbox

radiobutton

sprite-button

sprite

scroll-pane

drop-down

line

list-box

camera

choose-elem-button

text-box

slider

minimap

tab

switch

Return values

clear()

Example

destroy()

Example

get_mod() → string?

get_index_in_parent() → uint

swap_children(index_1, index_2)

Parameters

clear_items()

get_item(index) → LocalisedString

Parameters

set_item(index, string)

Parameters

add_item(string, index?)

Parameters

remove_item(index)

Parameters

get_slider_minimum() → double

get_slider_maximum() → double

set_slider_minimum_maximum(minimum, maximum)

Parameters

get_slider_value_step() → double

get_slider_discrete_values() → boolean

set_slider_value_step(value)

Parameters

set_slider_discrete_values(value)

Parameters

focus()

scroll_to_top()

scroll_to_bottom()

scroll_to_left()

scroll_to_right()

scroll_to_element(element, scroll_mode?)

Parameters

select_all()

select(start_index, end_index)

Parameters

Examples

add_tab(tab, content)

Parameters

remove_tab(tab?) changed

Parameters

force_auto_center()

Raised events

scroll_to_item(index, scroll_mode?)

Parameters

bring_to_front()

close_dropdown()

Attributes

index :: Read uint

gui :: Read LuaGui

Factorio Runtime Docs Version 2.0.19

`button`

`flow`

`frame`

`table`

`textfield`

`progressbar`

`checkbox`

`radiobutton`

`sprite-button`

`sprite`

`scroll-pane`

`drop-down`

`line`

`list-box`

`camera`

`choose-elem-button`

`text-box`

`slider`

`minimap`

`tab`

`switch`