Gui module

Core Module - Gui - Gui defines that are used internally by the gui system

Dependencies

utils.event
mod-gui
utils.event
mod-gui

Tables

events String indexed table used to avoid conflict with custom event names, similar to how defines.events works
defines Uid indexed array that stores all the factory functions that were defined, no new values will be added during runtime
core_defines An string indexed table of all the defines which are used by the core of the gui system, used for internal refrence
file_paths Used to store the file names where elements were defined, this can be useful to find the uid of an element, mostly for debuging
debug_info Used to store extra infomation about elements as they get defined such as the params used and event handlers registered to them
_prototype_element The prototype used to store the functions of an element define
_mt_element The prototype metatable applied to new element defines

Fields

uid The current highest uid that is being used by a define, will not increase during runtime

Core Defines

hide_top_flow Button which toggles the top flow elements, version which shows inside the top flow when top flow is visible
show_top_flow Button which toggles the top flow elements, version which shows inside the left flow when top flow is hidden
hide_left_flow Button which hides the elements in the left flow, shows inside the left flow when frames are visible

Defines

alignment Draw a flow used to align its child elements, default is right align
scroll_table Draw a scroll pane that has a table inside of it
header Used to add a frame with the header style, has the option for a right alignment flow for buttons
footer Used to add a frame with the footer style, has the option for a right alignment flow for buttons
container Used for left frames to give them a nice boarder
bar Used to make a solid white bar in a gui
centered_label Used to make a label which is centered and of a certian size
title_label Used to make a title which has two bars on either side

Helper Functions

get_player_from_element(element) Get the player that owns a gui element
toggle_enabled_state(element[, state]) Will toggle the enabled state of an element or set it to the one given
toggle_visible_state(element[, state]) Will toggle the visible state of an element or set it to the one given
destroy_if_valid(element) Destory a gui element without causing any errors, often because the element was already removed
sprite_style(size[, padding=-2][, style]) Returns a table to be used as the style for a sprite buttons, produces a sqaure button

Left Flow

left_elements Contains the uids of the elements that will shown on the left flow and their join functions
get_left_flow(player) Gets the flow refered to as the left flow, each player has one left flow
Gui._prototype_element:add_to_left_flow([open_on_join]) Sets an element define to be drawn to the left flow when a player joins, includes optional check
left_toolbar_button(sprite, tooltip, element_define[, authenticator]) Creates a button on the top flow which will toggle the given element define, the define must exist in the left flow
draw_left_flow(player) Draw all the left elements onto the left flow, internal use only with on join
update_left_flow(player) Update the visible state of the hide button, can be used to check if any frames are visible
hide_left_flow(player) Hides all left elements for a player
get_left_element(player, element_define) Get the element define that is in the left flow, use in events without an element refrence
toggle_left_element(player, element_define[, state]) Toggles the visible state of a left element for a given player, can be used to set the visible state

Element Define

element(element_define) Used to define new elements for your gui, can be used like LuaGuiElement.add or a custom function
Gui._prototype_element:style(style_define) Used to extent your element define with a style factory, this style will be applied to your element when created, can also be a custom function
Gui._prototype_element:on_custom_event(event_name, handler) Set the handler which will be called for a custom event, only one handler can be used per event per element
Gui._prototype_element:raise_custom_event(event) Raise the handler which is attached to an event; external use should be limited to custom events

Element Events

Gui._prototype_element.on_open Called when the player opens a GUI.
Gui._prototype_element.on_close Called when the player closes the GUI they have open.
Gui._prototype_element.on_click Called when LuaGuiElement is clicked.
Gui._prototype_element.on_confirmed Called when a LuaGuiElement is confirmed, for example by pressing Enter in a textfield.
Gui._prototype_element.on_checked_changed Called when LuaGuiElement checked state is changed (related to checkboxes and radio buttons).
Gui._prototype_element.on_elem_changed Called when LuaGuiElement element value is changed (related to choose element buttons).
Gui._prototype_element.on_location_changed Called when LuaGuiElement element location is changed (related to frames in player.gui.screen).
Gui._prototype_element.on_tab_changed Called when LuaGuiElement selected tab is changed (related to tabbed-panes).
Gui._prototype_element.on_selection_changed Called when LuaGuiElement selection state is changed (related to drop-downs and listboxes).
Gui._prototype_element.on_switch_changed Called when LuaGuiElement switch state is changed (related to switches).
Gui._prototype_element.on_text_changed Called when LuaGuiElement text is changed by the player.
Gui._prototype_element.on_value_changed Called when LuaGuiElement slider value is changed (related to the slider element).

Top Flow

top_elements Contains the uids of the elements that will shown on the top flow and their auth functions
top_flow_button_style The style that should be used for buttons on the top flow
top_flow_button_visible_style The style that should be used for buttons on the top flow when their flow is visible
get_top_flow(player) Gets the flow refered to as the top flow, each player has one top flow
Gui._prototype_element:add_to_top_flow([authenticator]) Sets an element define to be drawn to the top flow when a player joins, includes optional authenticator
update_top_flow(player) Updates the visible state of all the elements on the players top flow, uses authenticator
toggle_top_flow(player[, state]) Toggles the visible state of all the elements on a players top flow, effects all elements
get_top_element(player, element_define) Get the element define that is in the top flow, use in events without an element refrence
toolbar_button(sprite, tooltip[, authenticator]) Creates a button on the top flow with consistent styling
toolbar_button_style(button, state) Styles a top flow button depending on the state given

Dependencies

# utils.event
# mod-gui
# utils.event
# mod-gui

Tables

# events

String indexed table used to avoid conflict with custom event names, similar to how defines.events works

# defines

Uid indexed array that stores all the factory functions that were defined, no new values will be added during runtime

# core_defines

An string indexed table of all the defines which are used by the core of the gui system, used for internal refrence

# file_paths

Used to store the file names where elements were defined, this can be useful to find the uid of an element, mostly for debuging

# debug_info

Used to store extra infomation about elements as they get defined such as the params used and event handlers registered to them

# _prototype_element

The prototype used to store the functions of an element define

# _mt_element

The prototype metatable applied to new element defines

Fields:
  • __call

Fields

# uid

The current highest uid that is being used by a define, will not increase during runtime

  • uid

Core Defines

# hide_top_flow

Button which toggles the top flow elements, version which shows inside the top flow when top flow is visible

# show_top_flow

Button which toggles the top flow elements, version which shows inside the left flow when top flow is hidden

# hide_left_flow

Button which hides the elements in the left flow, shows inside the left flow when frames are visible

Defines

# alignment

Draw a flow used to align its child elements, default is right align

Properties / Events:
  • parent : (LuaGuiElement) the parent element to which the alignment will be added
  • name : (string) the name of the alignment flow which is added (default: 'alignment')
  • horizontal_align : (string) the horizontal alignment of the elements in the flow (default: 'right')
  • vertical_align : (string) the vertical alignment of the elements in the flow (default: 'center')
Usage:
-- Adding a right align flow
local alignment = Gui.alignment(element,'example_right_alignment')
-- Adding a horizontal center and top align flow
local alignment = Gui.alignment(element,'example_center_top_alignment','center','top')
# scroll_table

Draw a scroll pane that has a table inside of it

Properties / Events:
  • parent : (LuaGuiElement) the parent element to which the scroll table will be added
  • height : (number) the maximum height for the scroll pane
  • column_count : (number) the number of columns that the table will have
  • name : (string) the name of the scroll pane that is added, the table is always called "table" (default: 'scroll')
Usage:
-- Adding a scroll table with max height of 200 and column count of 3
local scroll_table = Gui.scroll_table(element,200,3)
# header

Used to add a frame with the header style, has the option for a right alignment flow for buttons

Properties / Events:
  • parent : (LuaGuiElement) the parent element to which the header will be added
  • caption : (string or LocalizedString) the caption that will be shown on the header
  • tooltip : (string or LocalizedString) the tooltip that will be shown on the header (optional)
  • add_alignment : (boolean) when true an alignment flow will be added to the header (default: false)
  • name : (string) the name of the header that is being added, the alignment is always called "alignment" (default: 'header')
Usage:
-- Adding a custom header with a label
local header = Gui.header(
    element,
    'Example Caption',
    'Example Tooltip'
)
# footer

Used to add a frame with the footer style, has the option for a right alignment flow for buttons

Properties / Events:
  • parent : (LuaGuiElement) the parent element to which the footer will be added
  • caption : (string or LocalizedString) the caption that will be shown on the footer
  • tooltip : (string or LocalizedString) the tooltip that will be shown on the footer (optional)
  • add_alignment : (boolean) when true an alignment flow will be added to the footer (default: false)
  • name : (string) the name of the footer that is being added, the alignment is always called "alignment" (default: 'footer')
Usage:
-- Adding a custom footer with a label
local footer = Gui.footer(
    element,
    'Example Caption',
    'Example Tooltip'
)
# container

Used for left frames to give them a nice boarder

Properties / Events:
  • parent : (LuaGuiElement) the parent element to which the container will be added
  • name : (string) the name that you want to give to the outer frame, often just event_trigger
  • width : (number) the minimal width that the frame will have
Usage:
-- Adding a container as a base
local container = Gui.container(parent,'my_container',200)
# bar

Used to make a solid white bar in a gui

Properties / Events:
  • parent : (LuaGuiElement) the parent element to which the bar will be added
  • width : (number) the width of the bar that will be made, if not given bar will strech to fill the parent
Usage:
-- Adding a bar to a gui
local bar = Gui.bar(parent, 100)
# centered_label

Used to make a label which is centered and of a certian size

Properties / Events:
  • parent : (LuaGuiElement) the parent element to which the label will be added
  • width : (number) the width of the label, must be given in order to center the caption
  • caption : (string or LocalizedString) the caption that will be shown on the label
  • tooltip : (string or LocalizedString) the tooltip that will be shown on the label (optional)
Usage:
-- Adding a centered label
local label = Gui.centered_label(parent, 100, 'This is centered')
# title_label

Used to make a title which has two bars on either side

Properties / Events:
  • parent : (LuaGuiElement) the parent element to which the label will be added
  • width : (number) the width of the first bar, this can be used to position the label
  • caption : (string or LocalizedString) the caption that will be shown on the label
  • tooltip : (string or LocalizedString) the tooltip that will be shown on the label (optional)
Usage:
-- Adding a centered label
local label = Gui.centered_label(parent, 100, 'This is centered')

Helper Functions

# get_player_from_element(element)

Get the player that owns a gui element

Parameters: Returns:
  • (LuaPlayer) the player that owns this element
Usage:
-- Geting the owner of an element
local player = Gui.get_player_from_element(element)
# toggle_enabled_state(element[, state])

Will toggle the enabled state of an element or set it to the one given

Parameters:
  • element : (LuaGuiElement) the element to toggle/set the enabled state of
  • state : (boolean) with given will set the state, else state will be toggled (optional)
Returns:
  • (boolean) the new enabled state that the element has
Usage:
-- Toggling the the enabled state
local new_enabled_state = Gui.toggle_enabled_state(element)
# toggle_visible_state(element[, state])

Will toggle the visible state of an element or set it to the one given

Parameters:
  • element : (LuaGuiElement) the element to toggle/set the visible state of
  • state : (boolean) with given will set the state, else state will be toggled (optional)
Returns:
  • (boolean) the new visible state that the element has
Usage:
-- Toggling the the visible state
local new_visible_state = Gui.toggle_visible_state(element)
# destroy_if_valid(element)

Destory a gui element without causing any errors, often because the element was already removed

Parameters: Returns:
  • (boolean) true if the element was valid and has been removed
Usage:
-- Remove a child element if it exists
Gui.destroy_if_valid(element[child_name])
# sprite_style(size[, padding=-2][, style])

Returns a table to be used as the style for a sprite buttons, produces a sqaure button

Parameters:
  • size : (number) the size that you want the button to be
  • padding : (number) the padding that you want on the sprite (default: -2)
  • style : (table) any extra style settings that you want to have (optional)
Returns:
  • (table) the style table to be used with element_define:style()
Usage:
-- Adding a sprite button with size 20
local button =
Gui.element{
    type = 'sprite-button',
    sprite = 'entity/inserter'
}
:style(Gui.sprite_style(20))

Left Flow

# left_elements

Contains the uids of the elements that will shown on the left flow and their join functions

# get_left_flow(player)

Gets the flow refered to as the left flow, each player has one left flow

(player)

Parameters:
  • player : (LuaPlayer) the player that you want to get the left flow for
Returns: Usage:
-- Geting your left flow
local left_flow = Gui.get_left_flow(game.player)
# Gui._prototype_element:add_to_left_flow([open_on_join])

Sets an element define to be drawn to the left flow when a player joins, includes optional check

Parameters:
  • open_on_join : (boolean or function) called during first darw to decide if the element should be visible (optional)
Returns:
  • (table) the new element define that is used to register events to this element
Usage:
-- Adding the example button
example_flow_with_button:add_to_left_flow(true)
# left_toolbar_button(sprite, tooltip, element_define[, authenticator])

Creates a button on the top flow which will toggle the given element define, the define must exist in the left flow

Parameters:
  • sprite : (string) the sprite that you want to use on the button
  • tooltip : (string or LocalizedString) the tooltip that you want the button to have
  • element_define : (table) the element define that you want to have toggled by this button, define must exist on the left flow
  • authenticator : (function) used to decide if the button should be visible to a player (optional)
Usage:
-- Add a button to toggle a left element
local toolbar_button =
Gui.left_toolbar_button('entity/inserter', 'Nothing to see here', example_flow_with_button, function(player)
    return player.admin
end)
# draw_left_flow(player)

Draw all the left elements onto the left flow, internal use only with on join

Parameters:
  • player : (LuaPlayer) the player that you want to draw the elements for
Usage:
 Draw all the left elements
Gui.draw_left_flow(player)
# update_left_flow(player)

Update the visible state of the hide button, can be used to check if any frames are visible

Parameters:
  • player : (LuaPlayer) the player to update the left flow for
Returns:
  • (boolean) true if any left element is visible
Usage:
-- Check if any left elements are visible
local visible = Gui.update_left_flow(player)
# hide_left_flow(player)

Hides all left elements for a player

Parameters:
  • player : (LuaPlayer) the player to hide the elements for
Usage:
-- Hide your left elements
Gui.hide_left_flow(game.player)
# get_left_element(player, element_define)

Get the element define that is in the left flow, use in events without an element refrence

Parameters:
  • player : (LuaPlayer) the player that you want to get the element for
  • element_define : (table) the element that you want to get
Returns:
  • (LuaGuiElement) the gui element linked to this define for this player
Usage:
-- Get your left element
local frame = Gui.get_left_element(game.player, example_flow_with_button)
# toggle_left_element(player, element_define[, state])

Toggles the visible state of a left element for a given player, can be used to set the visible state

Parameters:
  • player : (LuaPlayer) the player that you want to toggle the element for
  • element_define : (table) the element that you want to toggle
  • state : (boolean) with given will set the state, else state will be toggled (optional)
Returns:
  • (boolean) the new visible state of the element
Usage:
-- Toggle your example button
Gui.toggle_top_flow(game.player, example_flow_with_button)
-- Show your example button
Gui.toggle_top_flow(game.player, example_flow_with_button, true)

Element Define

# element(element_define)

Used to define new elements for your gui, can be used like LuaGuiElement.add or a custom function

Parameters:
  • element_define : (table or function) the define information for the gui element, same data as LuaGuiElement.add, or a custom function may be used
Returns:
  • (table) the new element define, this can be considered a factory for the element which can be called to draw the element to any other element
Usage:
-- Using element defines like LuaGuiElement.add
-- This returns a factory function to draw a button with the caption "Example Button"
local example_button =
Gui.element{
    type = 'button',
    caption = 'Example Button'
}
-- Using element defines with a custom factory function
-- This method can be used if you still want to be able register event handlers but it is too complex to be compatible with LuaGuiElement.add
local example_flow_with_button =
Gui.element(function(event_trigger,parent,...)
    -- ... shows that all other arguments from the factory call are passed to this function
    -- parent is the element which was passed to the factory function where you should add your new element
    -- here we are adding a flow which we will then later add a button to
    local flow =
    parent.add{
        name = 'example_flow',
        type = 'flow'
    }

    -- event_trigger should be the name of any elements you want to trigger your event handlers, such as on_click or on_state_changed
    -- now we add the button to the flow that we created earlier
    local element =
    flow.add{
        name = event_trigger,
        type = 'button',
        caption = 'Example Button'
    }

    -- you must return your new element, this is so styles can be applied and returned to the caller
    -- you may return any of your elements that you add, consider the context in which it will be used for what should be returned
    return element
end)
# Gui._prototype_element:style(style_define)

Used to extent your element define with a style factory, this style will be applied to your element when created, can also be a custom function

Parameters:
  • style_define : (table or function) style table where each key and value pair is treated like LuaGuiElement.style[key] = value, a custom function can be used
Returns:
  • (table) the element define is returned to allow for event handlers to be registered
Usage:
-- Using the table method of setting the style
local example_button =
Gui.element{
    type = 'button',
    caption = 'Example Button',
    style = 'forward_button' -- factorio styles can be applied here
}
:style{
    height = 25, -- same as element.style.height = 25
    width = 100 -- same as element.style.width = 25
}
-- Using the function method to set the style
-- Use this method if your style is dynamic and depends on other factors
local example_button =
Gui.element{
    type = 'button',
    caption = 'Example Button',
    style = 'forward_button' -- factorio styles can be applied here
}
:style(function(style,element,...)
    -- style is the current style object for the elemenent
    -- element is the element that is being changed
    -- ... shows that all other arguments from the factory call are passed to this function
    local player = game.players[element.player_index]
    style.height = 25
    style.width = 100
    style.font_color = player.color
end)
# Gui._prototype_element:on_custom_event(event_name, handler)

Set the handler which will be called for a custom event, only one handler can be used per event per element

Parameters:
  • event_name : (string) the name of the event you want to handler to be called on, often from Gui.events
  • handler : (function) the handler that you want to be called when the event is raised
Returns:
  • (table) the element define so more handleres can be registered
Usage:
-- Register a handler to "my_custom_event" for this element
element_deinfe:on_custom_event('my_custom_event', function(event)
    event.player.print(player.name)
end)
# Gui._prototype_element:raise_custom_event(event)

Raise the handler which is attached to an event; external use should be limited to custom events

Parameters:
  • event : (table) the event table passed to the handler, must contain fields: name, element
Returns:
  • (table) the element define so more events can be raised
Usage:
 Raising a custom event
element_define:raise_custom_event{
    name = 'my_custom_event',
    element = element
}

Element Events

# Gui._prototype_element.on_open

Called when the player opens a GUI.

  • handler : (function) the event handler which will be called
# Gui._prototype_element.on_close

Called when the player closes the GUI they have open.

  • handler : (function) the event handler which will be called
# Gui._prototype_element.on_click

Called when LuaGuiElement is clicked.

  • handler : (function) the event handler which will be called
# Gui._prototype_element.on_confirmed

Called when a LuaGuiElement is confirmed, for example by pressing Enter in a textfield.

  • handler : (function) the event handler which will be called
# Gui._prototype_element.on_checked_changed

Called when LuaGuiElement checked state is changed (related to checkboxes and radio buttons).

  • handler : (function) the event handler which will be called
# Gui._prototype_element.on_elem_changed

Called when LuaGuiElement element value is changed (related to choose element buttons).

  • handler : (function) the event handler which will be called
# Gui._prototype_element.on_location_changed

Called when LuaGuiElement element location is changed (related to frames in player.gui.screen).

  • handler : (function) the event handler which will be called
# Gui._prototype_element.on_tab_changed

Called when LuaGuiElement selected tab is changed (related to tabbed-panes).

  • handler : (function) the event handler which will be called
# Gui._prototype_element.on_selection_changed

Called when LuaGuiElement selection state is changed (related to drop-downs and listboxes).

  • handler : (function) the event handler which will be called
# Gui._prototype_element.on_switch_changed

Called when LuaGuiElement switch state is changed (related to switches).

  • handler : (function) the event handler which will be called
# Gui._prototype_element.on_text_changed

Called when LuaGuiElement text is changed by the player.

  • handler : (function) the event handler which will be called
# Gui._prototype_element.on_value_changed

Called when LuaGuiElement slider value is changed (related to the slider element).

  • handler : (function) the event handler which will be called

Top Flow

# top_elements

Contains the uids of the elements that will shown on the top flow and their auth functions

# top_flow_button_style

The style that should be used for buttons on the top flow

# top_flow_button_visible_style

The style that should be used for buttons on the top flow when their flow is visible

# get_top_flow(player)

Gets the flow refered to as the top flow, each player has one top flow

(player)

Parameters:
  • player : (LuaPlayer) the player that you want to get the flow for
Returns: Usage:
-- Geting your top flow
local top_flow = Gui.get_top_flow(game.player)
# Gui._prototype_element:add_to_top_flow([authenticator])

Sets an element define to be drawn to the top flow when a player joins, includes optional authenticator

Parameters:
  • authenticator : (function) called during toggle or update to decide weather the element should be visible (optional)
Returns:
  • (table) the new element define to allow event handlers to be registered
Usage:
-- Adding an element to the top flow on join
example_button:add_to_top_flow(function(player)
    -- example button will only be shown if the player is an admin
    -- note button will not update its state when player.admin is changed Gui.update_top_flow must be called for this
    return player.admin
end)
# update_top_flow(player)

Updates the visible state of all the elements on the players top flow, uses authenticator

Parameters:
  • player : (LuaPlayer) the player that you want to update the top flow for
Usage:
-- Update your top flow
Gui.update_top_flow(game.player)
# toggle_top_flow(player[, state])

Toggles the visible state of all the elements on a players top flow, effects all elements

Parameters:
  • player : (LuaPlayer) the player that you want to toggle the top flow for
  • state : (boolean) if given then the state will be set to this (optional)
Returns:
  • (boolean) the new visible state of the top flow
Usage:
-- Toggle your flow
Gui.toggle_top_flow(game.player)
-- Open your top flow
Gui.toggle_top_flow(game.player,true)
# get_top_element(player, element_define)

Get the element define that is in the top flow, use in events without an element refrence

Parameters:
  • player : (LuaPlayer) the player that you want to get the element for
  • element_define : (table) the element that you want to get
Returns:
  • (LuaGuiElement) the gui element linked to this define for this player
Usage:
-- Get your top element
local button = Gui.get_top_element(game.player, example_button)
# toolbar_button(sprite, tooltip[, authenticator])

Creates a button on the top flow with consistent styling

Parameters:
  • sprite : (string) the sprite that you want to use on the button
  • tooltip : (string or LocalizedString) the tooltip that you want the button to have
  • authenticator : (function) used to decide if the button should be visible to a player (optional)
Usage:
-- Add a button to the toolbar
local toolbar_button =
Gui.left_toolbar_button('entity/inserter', 'Nothing to see here', function(player)
    return player.admin
end)
# toolbar_button_style(button, state)

Styles a top flow button depending on the state given

Parameters: Usage:
-- Sets the button to the visible style
Gui.toolbar_button_style(button, true)
-- Sets the button to the hidden style
Gui.toolbar_button_style(button, false)