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 middle that can be turned off or on."flow"
: Invisible containers that lay out children either horizontally or vertically. The 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."line"
: A vertical or horizontal line."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."list-box"
: A 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."slider"
: A number picker."minimap"
: A minimap preview similar to the normal player minimap."entity-preview"
: A preview of an entity. The entity has to be set after the GUI element is created."empty-widget"
: A empty widget that just exists. The root GUI element screen
is an empty-widget."tabbed-pane"
: A collection of tabs."tab"
: A tab for use in a tabbed-pane."switch"
: A switch with left, right, and none states. 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.
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"
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)
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. |
get_mod() → string | The mod that owns this Gui element or nil if it's owned by the scenario script. |
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 maximum value. |
set_slider_minimum_maximum(minimum, maximum) | Sets this sliders minimum and maximum values. |
get_slider_value_step() → double | Gets the minimum distance the slider can move. |
get_slider_discrete_slider() → boolean | Gets if the slider only allows being moved to discrete positions. |
get_slider_discrete_values() → boolean | Gets if the slider only allows being having discrete values. |
set_slider_value_step(value) | The minimum distance the slider can move. |
set_slider_discrete_slider(value) | Sets if the slider only allows being moved to discrete positions. |
set_slider_discrete_values(value) | Sets if the slider only allows being having discrete 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. |
add_tab(tab, content) | Adds the given tab and content widgets to this tabbed pane as a new tab. |
remove_tab(tab) | Removes the given tab and what ever it's associated content is from this tabbed pane. |
force_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. |
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 or radiobutton 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. |
location :: GuiLocation [RW] | The location of this widget when stored in LuaGui::screen or nil if not not set or not in LuaGui::screen. |
auto_center :: boolean [RW] | If this frame auto-centers on window resize when stored in LuaGui::screen. |
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. |
vertical_centering :: boolean [RW] | Whether the fields of this table should be vertically centered. |
slider_value :: double [RW] | The value of this slider element. |
mouse_button_filter :: MouseButtonFlags [RW] | The mouse button filters for this button or sprite-button. |
numeric :: boolean [RW] | If this text field only accepts numbers. |
allow_decimal :: boolean [RW] | If this text field (when in numeric mode) allows decimal numbers. |
allow_negative :: boolean [RW] | If this text field (when in numeric mode) allows negative numbers. |
is_password :: boolean [RW] | If this text field displays as a password field (renders all characters as '*'). |
lose_focus_on_confirm :: boolean [RW] | If this text field loses focus after defines.events.on_gui_confirmed is fired. |
clear_and_focus_on_right_click :: boolean [RW] | |
drag_target :: LuaGuiElement [RW] | The frame drag target for this flow, frame, label, table, or empty-widget. |
selected_tab_index :: uint [RW] | The selected tab index or nil if no tab is selected. |
tabs :: array of TabAndContent [R] | The tabs and contents being shown in this tabbed-pane. |
entity :: LuaEntity [RW] | The entity associated with this entity-preview or nil if no entity is associated. |
switch_state :: string [RW] | The switch state (left, none, right) for this switch. |
allow_none_state :: boolean [RW] | If the 'none' state is allowed for this switch. |
left_label_caption :: LocalisedString [RW] | The text shown for the left switch label. |
left_label_tooltip :: LocalisedString [RW] | The text shown for the left switch tooltip. |
right_label_caption :: LocalisedString [RW] | The text shown for the right switch label. |
right_label_tooltip :: LocalisedString [RW] | The text shown for the right switch tooltip. |
operator [] :: LuaGuiElement [R] | The indexing operator. |
valid :: boolean [R] | Is this object valid? |
help() → string | All methods, and properties that this object supports. |
Add a child element.
type
false
if not given.false
if not given.false
if not given.true
if not given.false
if not given.Remove children of this element. Any LuaGuiElement objects referring to the destroyed elements become invalid after this operation.
game.player.gui.top.clear()
Remove this element, along with its children. Any LuaGuiElement objects referring to the destroyed elements become invalid after this operation.
game.player.gui.top.greeting.destroy()
The mod that owns this Gui element or nil
if it's owned by the scenario script.
Clears the items in this dropdown or listbox.
Gets an item at the given index from this dropdown or listbox.
Sets an item at the given index in this dropdown or listbox.
Adds an item at the end or at the given index in this dropdown or listbox.
Removes an item at the given index in this dropdown or listbox.
Gets this sliders minimum value.
Gets this sliders maximum value.
Gets the minimum distance the slider can move.
Gets if the slider only allows being moved to discrete positions.
Gets if the slider only allows being having discrete values.
Sets if the slider only allows being moved to discrete positions.
Sets if the slider only allows being having discrete values.
Focuses this GUI element if possible.
Scrolls the scroll bar to the top.
Scrolls the scroll bar to the bottom.
Scrolls the scroll bar to the left.
Scrolls the scroll bar to the right.
Scrolls the scroll bar such that the specified GUI element is visible to the player.
"in-view"
, or "top-third"
. Defaults to "in-view"
.Select all text in the text box.
Select a range of text in the text box.
amp
from example
.
textbox.select(3, 5)
textbox.select(1, 0)
Adds the given tab and content widgets to this tabbed pane as a new tab.
Removes the given tab and what ever it's associated content is from this tabbed pane.
Forces this frame to re-auto-center. Only works on frames stored directly in LuaGui::screen.
Scrolls the scroll bar such that the specified listbox item is visible to the player.
The unique index of this GUI element.
The GUI this element is a part of.
The direct parent of this element; nil
if this is a top-level element.
The name of this element.
game.player.gui.top.greeting.name == "greeting"
How much this progress bar is filled. It is a value in range [0, 1].
Direction of the layout. May be either "horizontal"
or "vertical"
.
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.
When not visible the GUI element is hidden completely and takes no space in the layout.
The text contained in a textfield or text-box.
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.
Is this checkbox or radiobutton checked?
Index into LuaGameScript::players specifying the player who owns this element.
The image to display on this sprite-button or sprite in the default state.
Whether should the image widget resize its size according to the sprite in it (true by default)
The image to display on this sprite-button when it is hovered.
The image to display on this sprite-button when it is clicked.
Policy of the horizontal scroll bar, possible values are "auto" (default), "never", "always", "auto-and-reserve-space".
Policy of the vertical scroll bar, possible values are "auto" (default), "never", "always", "auto-and-reserve-space".
The type of this GUI element.
The children elements
The items in this dropdown or listbox.
The selected index for this dropdown or listbox. 0 if none.
The number to be shown in the right-bottom corner of the sprite-button, or nil
to show nothing.
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.
The location of this widget when stored in LuaGui::screen or nil
if not not set or not in LuaGui::screen.
If this frame auto-centers on window resize when stored in LuaGui::screen.
The position this camera or minimap is focused on if any.
The surface index this camera or minimap is using.
The zoom this camera or minimap is using.
The player index this minimap is using.
The force this minimap is using or nil
if no force is set.
The elem type of this choose-elem-button.
The elem value of this choose-elem-button or nil
if there is no value.
If the contents of this text-box are selectable.
If this text-box will word-wrap automatically.
If this text-box is read-only.
If this GUI element is enabled.
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.
If this choose-elem-button can be changed by the player.
If this table should draw vertical grid lines.
If this table should draw horizontal grid lines.
If this table should draw a horizontal grid line after the headers.
The number of columns in this table.
Whether the fields of this table should be vertically centered. This true by default and overrides LuaStyle::column_alignments.
The value of this slider element.
The mouse button filters for this button or sprite-button.
If this text field only accepts numbers.
If this text field (when in numeric mode) allows decimal numbers.
If this text field (when in numeric mode) allows negative numbers.
If this text field displays as a password field (renders all characters as '*').
If this text field loses focus after defines.events.on_gui_confirmed is fired.
The frame drag target for this flow, frame, label, table, or empty-widget.
nil
. The selected tab index or nil
if no tab is selected.
The tabs and contents being shown in this tabbed-pane.
Each TabAndContent is a table:
The entity associated with this entity-preview or nil
if no entity is associated.
The switch state (left, none, right) for this switch.
If the 'none' state is allowed for this switch.
The text shown for the left switch tooltip.
The text shown for the right switch tooltip.
The indexing operator. Gets children by name.