Gui core

Core Module - Gui - Used to simplify gui creation using factory functions called element defines

Usage

-- To draw your element you only need to call the factory function
-- You are able to pass any other arguments that are used in your custom functions but the first is always the parent element
local example_button_element = example_button(parent_element)

-- Making a factory function for a button with the caption "Example Button"
-- This method has all the same features as LuaGuiElement.add
local example_button =
Gui.element{
    type = 'button',
    caption = 'Example Button'
}

-- Making a factory function for a button which is contained within a flow
-- This method is for when you still want to register event handlers but cant use the table method
local example_flow_with_button =
Gui.element(function(definition, parent, ...)
    -- ... shows that all other arguments from the factory call are passed to this function
    -- Here we are adding a flow which we will then later add a button to
    local flow =
    parent.add{ -- paraent is the element which is passed to the factory function
        name = 'example_flow',
        type = 'flow'
    }

    -- Now we add the button to the flow that we created earlier
    local element = definition:triggers_event(
        flow.add{
            type = 'button',
            caption = 'Example Button'
        }
    )

    -- You must return a new element, this is so styles can be applied and returned to the caller
    -- You may return any of your elements that you added, consider the context in which it will be used for which should be returned
    return element
end)

-- Styles can be added to any element define, simplest way mimics LuaGuiElement.style[key] = value
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
}

-- Styles can also have a custom function when the style is dynamic and depends on other factors
-- 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)

-- You are able to register event handlers to your elements, these can be factorio events or custom ones
-- All events are checked to be valid before raising any handlers, this means element.valid = true and player.valid = true
Gui.element{
    type = 'button',
    caption = 'Example Button'
}
:on_click(function(player, element, event)
    -- player is the player who interacted with the element to cause the event
    -- element is a refrence to the element which caused the event
    -- event is a raw refrence to the event data if player and element are not enough
    player.print('Clicked: '..element.name)
end)

-- Example from core_defines, Gui.core_defines.hide_left_flow, called like: hide_left_flow(parent_element)
--- Button which hides the elements in the left flow, shows inside the left flow when frames are visible
-- @element hide_left_flow
local hide_left_flow =
Gui.element{
    type = 'sprite-button',
    sprite = 'utility/close_black',
    style = 'tool_button',
    tooltip = {'expcore-gui.left-button-tooltip'}
}
:style{
    padding = -3,
    width = 18,
    height = 20
}
:on_click(function(player, _,_)
    Gui.hide_left_flow(player)
end)

-- Eample from defines, Gui.alignment, called like: Gui.alignment(parent, name, horizontal_align, vertical_align)
-- Notice how _ are used to blank arguments that are not needed in that context and how they line up with above
Gui.alignment =
Gui.element(function(_, parent, name, _,_)
    return parent.add{
        name = name or 'alignment',
        type = 'flow',
    }
end)
:style(function(style, _,_, horizontal_align, vertical_align)
    style.padding = {1, 2}
    style.vertical_align = vertical_align or 'center'
    style.horizontal_align = horizontal_align or 'right'
    style.vertically_stretchable  = style.vertical_align ~= 'center'
    style.horizontally_stretchable = style.horizontal_align ~= 'center'
end)

Dependencies

utils.event
mod-gui

Functions

Gui._mt_element.__call(self, parent, ...)	Allows the define to be called to draw the element

Tables

unique_static_name	Used to automatically assign a unique static name to an element
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 reference
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 debugging
debug_info	Used to store extra information 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
Gui._mt_element.__index	Allow access to the element prototype methods

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
get_left_flow_order(_)	Get the order of elements in the left flow, first argument is player but is unused in the default method
inject_left_flow_order(provider)	Inject a custom left flow order provider, this should accept a player and return a list of elements definitions to draw
draw_left_flow(player)	Draw all the left elements onto the left flow, internal use only with on join
reorder_left_flow(player)	Reorder the left flow elements to match that returned by the provider, uses a method equivalent to insert sort
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
left_flow_loaded(player, element_define)	Checks if an element is loaded, used internally when the normal left gui assumptions may not hold
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:static_name([element])	Enforce the fact the element has a static name, this is required for the cases when a function define is used
Gui._prototype_element:triggers_events(element)	Used to link an element to an element define such that any event on the element will call the handlers on the element define -- You should not call this on the element you return from your constructor because this is done automatically
Gui._prototype_element:no_events(element)	Explicitly skip events on the element returned by your definition function
Gui._prototype_element:on_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_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_toggled_style	The style that should be used for buttons on the top flow when their flow is visible
toolbar_button_style(button, state)	Styles a top flow button depending on the state given
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
top_flow_has_visible_elements(player)	Returns true if the top flow has visible elements
get_top_flow_order(_)	Get the order of elements in the top flow, first argument is player but is unused in the default method
inject_top_flow_order(provider)	Inject a custom top flow order provider, this should accept a player and return a list of elements definitions to draw
update_top_flow(player)	Updates the visible state of all the elements on the players top flow, uses authenticator
reorder_top_flow(player)	Reorder the top flow elements to match that returned by the provider, uses a method equivalent to insert sort
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
toggle_toolbar_button(player, element_define[, state])	Toggles the state of a toolbar button for a given player, can be used to set the visual state
toolbar_button(sprite, tooltip[, authenticator])	Creates a button on the top flow with consistent styling
toolbar_toggle_button(sprite, tooltip[, authenticator])	Creates a toggle button on the top flow with consistent styling

Dependencies

# utils.event

# mod-gui

Functions

# Gui._mt_element.__call(self, parent, ...)

Allows the define to be called to draw the element

Parameters:

• self
• parent
• ...

Tables

# unique_static_name

Used to automatically assign a unique static name to an element

# 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 reference

# 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 debugging

# debug_info

Used to store extra information 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

# Gui._mt_element.__index

Allow access to the element prototype methods

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:

• element : (LuaGuiElement) the element to get the owner of

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:

• element : (LuaGuiElement) the element that you want to remove

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:

• (LuaGuiElement) the left element flow

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)

# get_left_flow_order(_)

Get the order of elements in the left flow, first argument is player but is unused in the default method

Parameters:

• _

# inject_left_flow_order(provider)

Inject a custom left flow order provider, this should accept a player and return a list of elements definitions to draw

Parameters:

• provider

# 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)

# reorder_left_flow(player)

Reorder the left flow elements to match that returned by the provider, uses a method equivalent to insert sort

Parameters:

• 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)

# left_flow_loaded(player, element_define)

Checks if an element is loaded, used internally when the normal left gui assumptions may not hold

Parameters:

• player
• element_define

# 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:static_name([element])

Enforce the fact the element has a static name, this is required for the cases when a function define is used

Parameters:

• element : (string) The element that will trigger calls to the event handlers (optional)

Returns:

• (table) the element define is returned to allow for event handlers to be registered

# Gui._prototype_element:triggers_events(element)

Used to link an element to an element define such that any event on the element will call the handlers on the element define -- You should not call this on the element you return from your constructor because this is done automatically

Parameters:

• element : (LuaGuiElement) The element that will trigger calls to the event handlers

Returns:

• (LuaGuiElement) The element passed as the argument to allow for cleaner returns

# Gui._prototype_element:no_events(element)

Explicitly skip events on the element returned by your definition function

Parameters:

• element

# Gui._prototype_element:on_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_event('my_custom_event', function(event)
    event.player.print(player.name)
end)

# Gui._prototype_element:raise_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_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

Usage:

 element_define:on_open(function(event)
  event.player.print(table.inspect(event))
end)

# Gui._prototype_element.on_close

Called when the player closes the GUI they have open.

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

Usage:

 element_define:on_close(function(event)
  event.player.print(table.inspect(event))
end)

# Gui._prototype_element.on_click

Called when LuaGuiElement is clicked.

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

Usage:

 element_define:on_click(function(event)
  event.player.print(table.inspect(event))
end)

# 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

Usage:

 element_define:on_confirmed(function(event)
  event.player.print(table.inspect(event))
end)

# 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

Usage:

 element_define:on_checked_changed(function(event)
  event.player.print(table.inspect(event))
end)

# 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

Usage:

 element_define:on_elem_changed(function(event)
  event.player.print(table.inspect(event))
end)

# 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

Usage:

 element_define:on_location_changed(function(event)
  event.player.print(table.inspect(event))
end)

# 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

Usage:

 element_define:on_tab_changed(function(event)
  event.player.print(table.inspect(event))
end)

# 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

Usage:

 element_define:on_selection_changed(function(event)
  event.player.print(table.inspect(event))
end)

# 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

Usage:

 element_define:on_switch_changed(function(event)
  event.player.print(table.inspect(event))
end)

# Gui._prototype_element.on_text_changed

Called when LuaGuiElement text is changed by the player.

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

Usage:

 element_define:on_text_changed(function(event)
  event.player.print(table.inspect(event))
end)

# 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

Usage:

 element_define:on_value_changed(function(event)
  event.player.print(table.inspect(event))
end)

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_toggled_style

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

# toolbar_button_style(button, state)

Styles a top flow button depending on the state given

Parameters:

• button : (LuaGuiElement) the button element to style
• state : (boolean) The state the button is in

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)

# 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:

• (LuaGuiElement) the top element flow

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)

# top_flow_has_visible_elements(player)

Returns true if the top flow has visible elements

Parameters:

• player

# get_top_flow_order(_)

Get the order of elements in the top flow, first argument is player but is unused in the default method

Parameters:

• _

# inject_top_flow_order(provider)

Inject a custom top flow order provider, this should accept a player and return a list of elements definitions to draw

Parameters:

• provider

# 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)

# reorder_top_flow(player)

Reorder the top flow elements to match that returned by the provider, uses a method equivalent to insert sort

Parameters:

• 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)

# toggle_toolbar_button(player, element_define[, state])

Toggles the state of a toolbar button for a given player, can be used to set the visual 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_toolbar_button(game.player, toolbar_button)

-- Show your example button
Gui.toggle_toolbar_button(game.player, toolbar_button, true)

# 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_toggle_button(sprite, tooltip[, authenticator])

Creates a toggle 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.toolbar_toggle_button('entity/inserter', 'Nothing to see here', function(player)
    return player.admin
end)
:on_event(Gui.events.on_toolbar_button_toggled, function(player, element, event)
    game.print(table.inspect(event))
end)