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. |
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. |
entity :: LuaEntity [RW] | The entity associated with this entity-preview or nil if no entity is associated. |
operator [] :: LuaGuiElement [R] | The indexing operator. |
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:
"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. All three root
GUI elements (top
, left
and center
; see LuaGui) are flows."frame"
: Grey semi-transparent boxes that contain other elements. They have a caption, and, just
like flows, they lay out children either horizontally or vertically."label"
: A piece of text."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. 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"
Add a child element.
"button"
, "sprite-button"
,
"checkbox"
, "flow"
, "frame"
, "label"
, "progressbar"
, "table"
, "textfield"
,
"radiobutton"
, "sprite"
, "scroll-pane"
, "drop-down"
, "line"
, "list-box"
, "camera"
,
"choose-elem-button"
, "text-box"
, "slider"
, "minimap"
, or "entity-preview"
.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()
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 minimum value.
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)
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"
The text displayed on the element. For frames, this is the "heading". For other elements, like buttons or labels, this is the content.
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 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 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 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.
The entity associated with this entity-preview or nil
if no entity is associated.
The indexing operator. Gets children by name.