Home

LuaGuiElement

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.

Attributes

index

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

gui

The GUI this element is a child of.

parent

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

name

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

caption

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

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

direction

Direction of this element's layout.

style

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

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

text

The text contained in this textfield or text-box.

children_names

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

Is this checkbox or radiobutton checked?

player_index

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

sprite

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

resize_to_sprite

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

hovered_sprite

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

clicked_sprite

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

tooltip

The text to display when hovering over this element. Writing "" or nil will disable the tooltip.

elem_tooltip

The element tooltip to display when hovering over this element, or nil.

horizontal_scroll_policy

Policy of the horizontal scroll bar.

vertical_scroll_policy

Policy of the vertical scroll bar.

type

The type of this GUI element.

children

The child-elements of this GUI element.

items

The items in this dropdown or listbox.

selected_index

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

quality

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

number

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

show_percent_for_small_numbers

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.

location

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

auto_center

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

badge_text

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

auto_toggle

Whether this button will automatically toggle when clicked.

toggled

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.

game_controller_interaction

How this element should interact with game controllers.

position

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

surface_index

The surface index this camera or minimap is using.

zoom

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

minimap_player_index

The player index this minimap is using.

force

The force this minimap is using, if any.

elem_type

The elem type of this choose-elem-button.

elem_value

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

The "signal" type operates with SignalID.

The "with-quality" types operate with PrototypeWithQuality.

The remaining types use strings.

elem_filters

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.

selectable

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

word_wrap

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

read_only

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

enabled

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

ignored_by_interaction

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

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

draw_vertical_lines

Whether this table should draw vertical grid lines.

draw_horizontal_lines

Whether this table should draw horizontal grid lines.

draw_horizontal_line_after_headers

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

column_count

The number of columns in this table.

vertical_centering

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

slider_value

The value of this slider element.

mouse_button_filter

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

numeric

Whether this textfield is limited to only numeric characters.

allow_decimal

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

allow_negative

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

is_password

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

lose_focus_on_confirm

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

icon_selector

Whether this textfield or text-box was created with an icon selector.

drag_target

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.

selected_tab_index

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

tabs

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

entity

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

anchor

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

tags

The tags associated with this LuaGuiElement.

raise_hover_events

Whether this element will raise on_gui_hover and on_gui_leave.

switch_state

The switch state for this switch.

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

allow_none_state

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

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

left_label_caption

The text shown for the left switch label.

left_label_tooltip

The tooltip shown on the left switch label.

right_label_caption

The text shown for the right switch label.

right_label_tooltip

The tooltip shown on the right switch label.

valid

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

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.

Methods

add

LuaGuiElement.add{ type: GuiElementType, name?: string, caption?: LocalisedString, tooltip?: LocalisedString, elem_tooltip?: ElemID, enabled?: boolean, visible?: boolean, locked?: boolean, ignored_by_interaction?: boolean, style?: string, tags?: Tags, index?: uint32, anchor?: GuiAnchor, game_controller_interaction?: defines.game_controller_interaction, raise_hover_events?: boolean } -> LuaGuiElement

Call As

guiElement.add{ type=type }

Call Convention

Add a new child element to this GuiElement.

Parameters

Returns

clear

LuaGuiElement.clear()

Call As

guiElement.clear()

Call Convention

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

destroy

LuaGuiElement.destroy()

Call As

guiElement.destroy()

Call Convention

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.

get_mod

LuaGuiElement.get_mod() -> string?

Call As

guiElement.get_mod()

Call Convention

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.

Returns

get_index_in_parent

LuaGuiElement.get_index_in_parent() -> uint32

Call As

guiElement.get_index_in_parent()

Call Convention

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.

Returns

swap_children

LuaGuiElement.swap_children(index_1: uint32, index_2: uint32)

Call As

guiElement.swap_children(index_1, index_2)

Call Convention

Swaps the children at the given indices in this element.

Parameters

clear_items

LuaGuiElement.clear_items()

Call As

guiElement.clear_items()

Call Convention

Removes the items in this dropdown or listbox.

get_item

LuaGuiElement.get_item(index: uint32) -> LocalisedString

Call As

guiElement.get_item(index)

Call Convention

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

Parameters

Returns

set_item

LuaGuiElement.set_item(index: uint32, string: LocalisedString)

Call As

guiElement.set_item(index, string)

Call Convention

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

Parameters

add_item

LuaGuiElement.add_item(string: LocalisedString, index?: uint32)

Call As

guiElement.add_item(string, index)

Call Convention

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

Parameters

remove_item

LuaGuiElement.remove_item(index: uint32)

Call As

guiElement.remove_item(index)

Call Convention

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

Parameters

get_slider_minimum

LuaGuiElement.get_slider_minimum() -> double

Call As

guiElement.get_slider_minimum()

Call Convention

Gets this sliders minimum value.

Returns

get_slider_maximum

LuaGuiElement.get_slider_maximum() -> double

Call As

guiElement.get_slider_maximum()

Call Convention

Gets this sliders maximum value.

Returns

set_slider_minimum_maximum

LuaGuiElement.set_slider_minimum_maximum(minimum: double, maximum: double)

Call As

guiElement.set_slider_minimum_maximum(minimum, maximum)

Call Convention

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

Parameters

get_slider_value_step

LuaGuiElement.get_slider_value_step() -> double

Call As

guiElement.get_slider_value_step()

Call Convention

Gets the minimum distance this slider can move.

Returns

get_slider_discrete_values

LuaGuiElement.get_slider_discrete_values() -> boolean

Call As

guiElement.get_slider_discrete_values()

Call Convention

Returns whether this slider only allows discrete values.

Returns

set_slider_value_step

LuaGuiElement.set_slider_value_step(value: double)

Call As

guiElement.set_slider_value_step(value)

Call Convention

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

Parameters

set_slider_discrete_values

LuaGuiElement.set_slider_discrete_values(value: boolean)

Call As

guiElement.set_slider_discrete_values(true)

Call Convention

Sets whether this slider only allows discrete values.

Parameters

focus

LuaGuiElement.focus()

Call As

guiElement.focus()

Call Convention

Focuses this GUI element if possible.

scroll_to_top

LuaGuiElement.scroll_to_top()

Call As

guiElement.scroll_to_top()

Call Convention

Scrolls this scroll bar to the top.

scroll_to_bottom

LuaGuiElement.scroll_to_bottom()

Call As

guiElement.scroll_to_bottom()

Call Convention

Scrolls this scroll bar to the bottom.

scroll_to_left

LuaGuiElement.scroll_to_left()

Call As

guiElement.scroll_to_left()

Call Convention

Scrolls this scroll bar to the left.

scroll_to_right

LuaGuiElement.scroll_to_right()

Call As

guiElement.scroll_to_right()

Call Convention

Scrolls this scroll bar to the right.

scroll_to_element

LuaGuiElement.scroll_to_element(element: LuaGuiElement, scroll_mode?: "in-view" | "top-third")

Call As

guiElement.scroll_to_element(element, scroll_mode)

Call Convention

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

Parameters

select_all

LuaGuiElement.select_all()

Call As

guiElement.select_all()

Call Convention

Selects all the text in this textbox.

select

LuaGuiElement.select(start_index: int32, end_index: int32)

Call As

guiElement.select(start_index, end_index)

Call Convention

Selects a range of text in this textbox.

Parameters

add_tab

LuaGuiElement.add_tab(tab: LuaGuiElement, content: LuaGuiElement)

Call As

guiElement.add_tab(tab, content)

Call Convention

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

Parameters

remove_tab

LuaGuiElement.remove_tab(tab?: LuaGuiElement)

Call As

guiElement.remove_tab()

Call Convention

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.

Parameters

force_auto_center

LuaGuiElement.force_auto_center()

Call As

guiElement.force_auto_center()

Call Convention

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

scroll_to_item

LuaGuiElement.scroll_to_item(index: int32, scroll_mode?: "in-view" | "top-third")

Call As

guiElement.scroll_to_item(index, scroll_mode)

Call Convention

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

Parameters

bring_to_front

LuaGuiElement.bring_to_front()

Call As

guiElement.bring_to_front()

Call Convention

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

Only works for elements in LuaGui::screen.

close_dropdown

LuaGuiElement.close_dropdown()

Call As

guiElement.close_dropdown()

Call Convention

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