Gui core

Core Module - Gui

Usage

-- Making the base button concept
local button =
Gui.new_concept('Button')
:new_event('on_click',defines.events.on_gui_click)
:new_property('tooltip')
:new_property('caption',nil,function(properties,value)
    properties.caption = value
    properties.sprite = nil
    properties.type = 'button'
end)
:new_property('sprite',nil,function(properties,value)
    properties.image = value
    properties.caption = nil
    properties.type = 'sprite-button'
end)
:define_draw(function(properties,parent,element)
    -- Note that element might be nil if this is the first draw function
    -- in this case button is a new concept so we know this is the first function and element is nil
    if properties.type == 'button' then
        element = parent.add{
            type = properties.type,
            name = properties.name,
            caption = properties.caption,
            tooltip = properties.tooltip
        }

    else
        element = parent.add{
            type = properties.type,
            name = properties.name,
            sprite = properties.sprite,
            tooltip = properties.tooltip
        }

    end

    -- We must return the element or what we want to be seen as the instance, this is so other draw functions have access to it
    -- for example if our custom button defined a draw function to change the font color to red
    return element
end)

-- Makeing a alternative button based on the first
local custom_button =
button:clone('CustomButton')
:new_event('on_admin_clicked',defines.events.on_gui_click,function(event)
    return event.player.admin -- only raise custom event when an admin clicks the button
end)
:set_caption('Custom Button')
:set_tooltip('Only admins can press this button')
:on_click(function(event)
    if not event.player.admin then
        event.player.print('You must be admin to use this button')
    end
end)
:on_admin_clicked(function(event)
    -- Yes i know this can just be an if else but its an example
    game.print(event.player.name..' pressed my admin button')
end)

-- Drawing a concept
custom_button:draw(game.player.gui.left)

Elements

button	The basic button element
checkbox	The basic checkbox element
dropdown	The basic dropdown element
elem_button	The basic dropdown element
frame	The basic frame element
progress_bar	The basic checkbox element
slider	The basic slider element
text_box	The text box element
text_field	The text field element

Dropdowns

set_dropdown_value(element, value)	Selects the index of a dropdown with this value
get_dropdown_value(element)	Gets the selected item value of a dropdown
add_dropdown_items(element[, start_index], new_items)	Adds the given items into the list of items for this dropdown

Progress Bars

progress_bar:increment(element[, amount=1])	Will increase the progress of a progress bar based on this concept, if the concept has an instance store then element acts as the category, if you have a combined store it will NOT update all instances
progress_bar:decrement(element[, amount=1])	Will decrease the progress of a progress bar based on this concept, if the concept has an instance store then element acts as the category, if you have a combined store it will NOT update all instances
progress_bar:reset(element)	Resets the progress back to 0% for this element, if the concept has an instance store then element acts as the category, if you have a combined store it will NOT update all instances
increment_progress_bar(element[, amount=0.01])	Increment any progress bar by the given percentage
decrement_progress_bar(element[, amount=0.01])	Decrement any progress bar by the given percentage

Concept Control

require_concept(concept)	Loads a concept from the concepts file, used internally
get_concept(name)	Gets the gui concept with this name
Prototype:change_name([new_name=self.name])	Used internally to save concept names to the core gui module
new_concept(name)	Returns a new gui concept with no properties or events
clone_concept(name, new_name)	Make a new concept based on the properties and drawing of another
draw_concept(name, parent)	Used to draw a concept to a parent element

Element Control

get_player_from_element(element)	Gets the player who owns this element
valid(element)	Simple check for if an element is valid
destroy(element)	Destroies and element if it is valid
toggle_enabled(element)	Toggles the enabled state of an element
toggle_visible(element)	Toggles the visible state of an element
set_padding(element[, up=0][, down=0][, left=0][, right=0])	Sets the padding for a gui element

Store Categories

categorize_by_player(element)	A categorize function to be used with add_store, each player has their own category
categorize_by_force(element)	A categorize function to be used with add_store, each force has its own category
categorize_by_surface(element)	A categorize function to be used with add_store, each surface has its own category

Concept Base

Prototype:clone(concept_name)	Used to copy all the settings from one concept to another and removing links to the orginal
Prototype:change_name([new_name=self.name])	Used internally to save concept names to the core gui module
Prototype:new_event(event_name[, factorio_event][, event_condition])	Adds a new event trigger to the concept which can be linked to a factorio event
Prototype:on_custom_event(handler)	Adds a custom event handler, replace with the name of the event
Prototype:raise_event(event_name[, event={}][, from_factorio=false])	Raises a custom event, folowing keys included automaticlly: concept, event name, game tick, player from player_index, element if valid
Prototype:new_property(property_name, default[, setter_callback])	Adds a new property to the concept, such as caption, tooltip, or some custom property you want to control
Prototype:set_custom_property(value)	Sets a new value for a property, triggers setter method if provided, replace with property name
Prototype:define_draw(draw_callback)	Used to define how the concept is turned into an ingame element or "instance" as we may refer to them
Prototype:draw(parent_element)	Calls all the draw functions in order to create this concept in game; will also store and sync the instance if stores are used

Concept Instances

Prototype:define_instance_store([category_callback])	Adds an instance store to the concept; when a new instance is made it is stored so you can access it later
Prototype.get_instances([category])	Gets all insatnces in a category, category may be nil to return all
Prototype.add_instance(element[, category])	Adds an instance to this concept, used automatically during concept:draw
Prototype.update_instances([category], update_callback)	Applies an update function to all instances, simialr use to what table.forEach would be

Concept Data

Prototype:define_data_store([category_callback])	Adds a data store to this concept which allows you to store synced/percistent data between instances
Prototype.get_data([category])	Gets the data that is stored for this category
Prototype.set_data([category], value)	Sets the data that is stored for this category
Prototype.clear_data([category])	Clears the data that is stored for this category
Prototype.update_data([category], update_callback)	Updates the data that is stored for this category

Concept Combined Instances

Prototype:define_combined_store([category_callback], sync_callback)	Used to add a both instance and data store which are linked together, new instances are synced to the current value, changing the stored value will change all instances
Prototype.sync_instance(element)	Will sync an instance to match the stored value based on the given sync callback

Tests

run_tests(player[, category])	Runs a set of gui tests to ensure that the system is working

Elements

# button

The basic button element

Properties / Events:

• on_click : fired when the player clicks the button
• on_left_click : fired when the player clicks with the right mouse button
• on_left_click : fired when the player clicks with the right mouse button
• caption : (string or LocalisedString) the message that is shown on the button
• tooltip : (string or LocalisedString) the tooltip that shows when a player hovers over the button
• sprite : (SpritePath) upto three sprites in the order: default, hovered, clicked

Usage:

-- Making a basic button
local basic_button =
Gui.clone_concept('button','basic_button')
:set_caption('Basic Button')
:set_tooltip('Basic button')
:on_click(function(event)
    event.player.print('You pressed basic button!')
end)

-- Making a sprite button
local sprite_button =
Gui.clone_concept('button','sprite_button')
:set_sprite('utility/warning_icon')
:set_tooltip('Sprite button')
:on_click(function(event)
    event.player.print('You pressed sprite button!')
end)

# checkbox

The basic checkbox element

Properties / Events:

• on_state_changed : fired when the state of the element is changed
• caption : (string or LocalisedString) the message that is shown next to the checkbox
• tooltip : (string or LocalisedString) the tooltip that shows when a player hovers over the checkbox
• default : (boolean or function) the default state of this checkbox, or a function which returns the default state
• use_radio : (boolean) setting to true will use radio buttons rather than checkboxs

Usage:

-- Making a basic checkbox
local basic_checkbox =
Gui.clone_concept('checkbox','basic_checkbox')
:set_caption('Basic Checkbox')
:set_tooltip('Basic checkbox')
:on_state_changed(function(event)
    event.player.print('Basic checkbox is now: '..tostring(event.element.state))
end)

# dropdown

The basic dropdown element

Properties / Events:

• on_selection_changed : fired when the selected value is changed
• default : (string, LocalisedString or function) the option which is selected by default, or a function which returns the default
• use_list_box : (boolean) when true a list box will be used rather than a dropdown menu
• static_items : (nil or table) when called with a table the values will be added as items for the dropdown, if called with nil then all items are cleared
• dynamic_items : (function) the given function will be called to return a list of items and optional start index to add items to the dropdown when it is first drawn

Usage:

-- Making a basic dropdown
local static_dropdown =
Gui.clone_concept('dropdown','static_dropdown')
:set_static_items{'Option 1','Option 2','Option 3'}
:on_selection_changed(function(event)
    local value = Gui.get_dropdown_value(event.element)
    event.player.print('Static dropdown is now: '..value)
end)

-- Making a dropdown with dynamic items, example is name of online players
local dynamic_dropdown =
Gui.clone_concept('dropdown','dynamic_dropdown')
:set_dynamic_items(function(element)
    local items = {}
    for _,player in pairs(game.connected_players) do
        items[#items+1] = player.name
    end
    return items
end)
:on_selection_changed(function(event)
    local value = Gui.get_dropdown_value(event.element)
    event.player.print('Dynamic dropdown is now: '..value)
end)

# elem_button

The basic dropdown element

Properties / Events:

• on_selection_changed : fired when the selected value is changed
• default : (string, SignalID or function) the option which is selected by default, or a function which returns the default
• elem_type : (string) the type of elem selection that this is, default is item selection

Usage:

-- Making a basic elem button
local basic_elem_button =
Gui.clone_concept('elem_button','basic_elembutton')
:on_selection_changed(function(event)
    event.player.print('Basic elem button is now: '..event.element.elem_value)
end)

# frame

The basic frame element

Properties / Events:

• title : (string or LocalisedString) the title that will show in the frame
• direction : (string) the direction that children will be added

Usage:

-- Making a basic frame, contains a label with hello world
local basic_frame =
Gui.clone_concept('dropdown','basic_frame')
:set_title('Basic Frame')
:define_draw(function(properties,parent,element)
    element.add{
        type = 'label',
        caption = 'Hello, World!'
    }
end)

# progress_bar

The basic checkbox element

Properties / Events:

• on_completion : fired when increment reaches the maxium value set by set_maximum
• tooltip : (string or LocalisedString) the tooltip that will show for this element
• maximum : (number) the maxium amount an instance can be increased, default 100
• delay_completion : (boolean) when true the progress will be completed untill after the maximum rather than at the maximum
• inverted : (boolean) although this will NOT effect how you use the functions it will make the element start full and reduce as you call increase, note issues with 0 detections

Usage:

-- Making a basic progress bar, will increase when pressed then will reset when full
local basic_progress_bar =
Gui.clone_concept('progress_bar','basic_progress_bar')
:set_tooltip('Basic progress bar')
:set_maximum(5)
:new_event('on_click',defines.events.on_gui_click)
:on_click(function(event)
    event.concept:increment(event.element)
end)
:set_delay_completion(true)
:on_completion(function(event)
    event.concept:reset(event.element)
end)

# slider

The basic slider element

Properties / Events:

• on_value_changed : fired when the value of the slider is changed
• value_step : (number) the minimum amount by which the value of the slider can be changed
• default : (number or function) the default value of the slider or a function which returns the default value
• discrete_slider : (boolean) makes this slider a discrete slider, this means that the slider button will stop at the same interval as the values do
• range : (number or function) accepts two params the minimum and the maximum for this slider, or a single function to return both

Usage:

-- Making a basic slider
local basic_slider =
Gui.clone_concept('slider','basic_slider')
:set_range(1,10)
:on_value_changed(function(event)
    event.player.print('Basic slider is now: '..event.element.slider_value)
end)

-- Making a discrete_slider
local discrete_slider =
Gui.clone_concept('slider','discrete_slider')
:set_range(1,10)
:set_value_step(1)
:set_discrete_slider(true)
:on_value_changed(function(event)
    event.player.print('Interval slider is now: '..event.element.slider_value)
end)

# text_box

The text box element

Properties / Events:

• on_text_changed : fired when the text within the text box is changed
• tooltip : (string or LocalisedString) the tooltip that shows when a player hovers over the text box
• default : (string or function) the default text that will appear in the text box, or a function that returns it
• clear_on_rmb : (boolean) if the text box will be cleared and forcused on a right click
• is_selectable : (boolean) when true the text inside the box can be selected
• has_word_wrap : (boolean) when true the text will wrap onto the next line if it reachs the end
• is_read_only : (boolean) when true the text inside the box can not be edited by the player

Usage:

-- Making a text box
local basic_text_box =
Gui.clone_concept('text_box','basic_text_box')
:set_default('I am the text that will show in the text box')

-- Making a text box which can be edited
local editible_text_box =
Gui.clone_concept('text_box','editible_text_box')
:set_is_read_only(false)
:set_default('I am the text that will show in the text box')
:on_confirmation(function(event)
    event.player.print('Editible text box is now: '..event.element.text)
end)

# text_field

The text field element

Properties / Events:

• on_text_changed : fired when the text within the text field is changed
• on_confirmation : fired when the player presses enter with the text field forcused
• tooltip : (string or LocalisedString) the tooltip that shows when a player hovers over the text field
• default : (string or function) the default text that will appear in the text field, or a function that returns it
• clear_on_rmb : (boolean) if the text field will be cleared and forcused on a right click
• lose_forcus : (boolean) if the text field will lose forcus after the confirmation event
• is_number : (boolean) if this text field contains a number value, can be ignored if is_decimal or is_negitive is used
• is_decimal : (boolean) if this text field contains a decimal value
• is_negative : (boolean) if this text field contains a negative value
• is_password : (boolean) if this text field contains a password value

Usage:

-- Making a text field
local basic_text_field =
Gui.clone_concept('text_field','basic_text_field')
:on_confirmation(function(event)
    event.player.print('Basic text field is now: '..event.element.text)
end)

-- Making a text field which will clear on right click and un forcus on confirmation
local better_text_field =
Gui.clone_concept('text_field','better_text_field')
:set_clear_on_rmb(true)
:set_lose_forcus(true)
:on_confirmation(function(event)
    event.player.print('Better text field is now: '..event.element.text)
end)

-- Making a decimal input
local decimal_text_field =
Gui.clone_concept('text_field','decimal_text_field')
:set_is_decimal(true)
:on_confirmation(function(event)
    event.player.print('Decimal text field is now: '..event.element.text)
end)

Dropdowns

# set_dropdown_value(element, value)

Selects the index of a dropdown with this value

Parameters:

• element : (LuaGuiElement) the dropdown that you want to set the selection for
• value : (string or LocalisedString) the value that you want selected

Returns:

• (boolean) if an item with this value was found

Usage:

-- Selecting the item with the value 'foo'
Gui.set_dropdown_value(element,'foo')

# get_dropdown_value(element)

Gets the selected item value of a dropdown

Parameters:

• element : (LuaGuiElement) the dropdown that you want the selected value of

Returns:

• (string or LocalisedString) the value that is currently selected

Usage:

-- Getting the selected value
local selected_value = Gui.get_dropdown_value(element)

# add_dropdown_items(element[, start_index], new_items)

Adds the given items into the list of items for this dropdown

Parameters:

• element : (LuaGuiElement) the dropdown that you want to add the items to
• start_index : (number) the index at which the items will be added, if not given appened to the end (optional)
• new_items : (table) the list of new items that you want to add

Returns:

• (table) the list of items that the element now has

Usage:

-- Add the items 'foo' and 'bar' to the end
Gui.add_dropdown_items(element,{'foo','bar'})

-- Add the items 'foo' and 'bar' to the start
Gui.add_dropdown_items(element,1,{'foo','bar'})

Progress Bars

# progress_bar:increment(element[, amount=1])

Will increase the progress of a progress bar based on this concept, if the concept has an instance store then element acts as the category, if you have a combined store it will NOT update all instances

Parameters:

• element : (LuaGuiElement or string) either the element that is changed or the category that is being changed (only if an instance store is defined)
• amount : (number) the amount that will bar will increase, note that this amount must be less than the max (default: 1)

Returns:

• (number or nil) the new value of the element, use this to sync a data store, if the return is nil then either a instance store was used or the new value may have changed

Usage:

-- Incrementing progress bar with no instance store
local new_value = progress_bar:increment(element)

-- Incrementing progress bar with an instance store
progress_bar:increment(category)

# progress_bar:decrement(element[, amount=1])

Will decrease the progress of a progress bar based on this concept, if the concept has an instance store then element acts as the category, if you have a combined store it will NOT update all instances

Parameters:

• element : (LuaGuiElement or string) either the element that is changed or the category that is being changed (only if an instance store is defined)
• amount : (number) the amount that will bar will decrease, note that this amount must be less than the max (default: 1)

Returns:

• (number) the new value of the element, use this to sync a data store, if the return is nil then either a instance store was used or the new value may have changed

Usage:

-- Decrementing progress bar with no instance store
local new_value = progress_bar:decrement(element)

-- Decrementing progress bar with an instance store
progress_bar:decrement(category)

# progress_bar:reset(element)

Resets the progress back to 0% for this element, if the concept has an instance store then element acts as the category, if you have a combined store it will NOT update all instances

Parameters:

• element : (LuaGuiElement or string) either the element that is changed or the category that is being changed (only if an instance store is defined)

Returns:

• (number or nil) the new value of the element, use this to sync a data store, if the return is nil then either a instance store was used or the new value may have changed

Usage:

-- Reseting a progress bar with no instance store
local new_value = progress_bar:reset(element)

-- Reseting a progress bar with an instance store
progress_bar:reset(category)

# increment_progress_bar(element[, amount=0.01])

Increment any progress bar by the given percentage

Parameters:

• element : (LuaGuiElement) the progress bar that you want to update
• amount : (number) the percentage that you want to increment the progress bar by (default: 0.01)

Returns:

• (boolean) true if the bar is now full

Usage:

-- Increment any progress bar by 10%
Gui.increment_progress_bar(element,0.1)

# decrement_progress_bar(element[, amount=0.01])

Decrement any progress bar by the given percentage

Parameters:

• element : (LuaGuiElement) the progress bar that you want to update
• amount : (number) the percentage that you want to decrement the progress bar by (default: 0.01)

Returns:

• (boolean) true if the bar is now empty

Usage:

-- Decrement any progress bar by 10%
Gui.decrement_progress_bar(element,0.1)

Concept Control

# require_concept(concept)

Loads a concept from the concepts file, used internally

Parameters:

• concept : (string) the name of the concept to require

Usage:

-- Load a base concept
Gui.require_concept('frame')

# get_concept(name)

Gets the gui concept with this name

Parameters:

• name : (string) the name of the concept that you want to get

Usage:

-- Getting a gui concept
local button = Gui.get_concept('Button')

# Prototype:change_name([new_name=self.name])

Used internally to save concept names to the core gui module

Parameters:

• new_name : (string) the new name of the concept (default: self.name)

Usage:

-- Internal Saving
-- this is never needed to be done, internal use only!
local button = Gui.get_concept('Button')
button:change_name('Not Button')

# new_concept(name)

Returns a new gui concept with no properties or events

Parameters:

• name : (string) the name that you want this concept to have

Usage:

-- Making a new concept, see module usage
local button = Gui.new_concept('Button')

# clone_concept(name, new_name)

Make a new concept based on the properties and drawing of another

Parameters:

• name : (string) the name of the concept that you want as the base
• new_name : (string) the name that you want the new concept to have

Usage:

-- Making a new concept from another, see module usage
local custom_button = Gui.clone_concept('Button','CustomButton')

# draw_concept(name, parent)

Used to draw a concept to a parent element

Parameters:

• name : (string) the name of the concept that you want to draw
• parent : (LuaGuiElement) the element that will act as a parent for the new element

Returns:

• (LuaGuiElement) the element that was created

Usage:

-- Drawing a new element
Gui.draw_concept('Button',element)

Element Control

# get_player_from_element(element)

Gets the player who owns this element

Parameters:

• element : (LuaGuiElement) the element that you want to get the player of

Returns:

• (LuaPlayer) the player who owns this element

Usage:

-- Getting the player of an element
local player = Gui.get_player_from_element(element)

# valid(element)

Simple check for if an element is valid

Parameters:

• element : (LuaGuiElement) the element that you want to check is valid

Returns:

• (boolean) true if the element is valid

Usage:

-- Return if not valid
if not Gui.valid(element) then return end

# destroy(element)

Destroies and element if it is valid

Parameters:

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

Returns:

• (boolean) true if the element was valid and was destoried

Usage:

-- Destoring an element
Gui.destroy(element)

# toggle_enabled(element)

Toggles the enabled state of an element

Parameters:

• element : (LuaGuiElement) the element that you want to toggle the enabled state of

Returns:

• (boolean) the new enabled state of the element

Usage:

-- Toggle the enabled state of an element
Gui.toggle_enabled(element)

# toggle_visible(element)

Toggles the visible state of an element

Parameters:

• element : (LuaGuiElement) the element that you want to toggle the visible state of

Returns:

• (boolean) the new visible state of the element

Usage:

-- Toggle the visible state of an element
Gui.toggle_visible(element)

# set_padding(element[, up=0][, down=0][, left=0][, right=0])

Sets the padding for a gui element

Parameters:

• element : (LuaGuiElement) the element to set the padding for
• up : (number or boolean) the amount of padding on the top, true leaves unchanged (default: 0)
• down : (number or boolean) the amount of padding on the bottom, true leaves unchanged (default: 0)
• left : (number or boolean) the amount of padding on the left, true leaves unchanged (default: 0)
• right : (number or boolean) the amount of padding on the right, true leaves unchanged (default: 0)

Usage:

-- Remove all padding of an element
Gui.set_padding(element)

-- Remove side padding but keep vertical padding
Gui.set_padding(element,true,true)

-- Remove all padding but set right to 2
Gui.set_padding(element,false,false,false,2)

Store Categories

# categorize_by_player(element)

A categorize function to be used with add_store, each player has their own category

Parameters:

• element : (LuaGuiElement) the element that will be converted to a string

Returns:

• (string) the player's name who owns this element

Usage:

-- Storing data on a per player basis, can be used with instances
Gui.get_concept('CustomButton')
:define_data_store(Gui.categorize_by_player)

# categorize_by_force(element)

A categorize function to be used with add_store, each force has its own category

Parameters:

• element : (LuaGuiElement) the element that will be converted to a string

Returns:

• (string) the player's force name who owns this element

Usage:

-- Storing data on a per force basis, can be used with instances
Gui.get_concept('CustomButton')
:define_data_store(Gui.categorize_by_force)

# categorize_by_surface(element)

A categorize function to be used with add_store, each surface has its own category

Parameters:

• element : (LuaGuiElement) the element that will be converted to a string

Returns:

• (string) the player's surface name who owns this element

Usage:

-- Storing data on a per surface basis, can be used with instances
Gui.get_concept('CustomButton')
:define_data_store(Gui.categorize_by_surface)

Concept Base

# Prototype:clone(concept_name)

Used to copy all the settings from one concept to another and removing links to the orginal

Parameters:

• concept_name : (string) the name of the new concept; must be unique

Returns:

• (GuiConcept) the base for building a custom gui

Usage:

-- Clones the base Button concept to make a alternative button
local custom_button =
Gui.get_concept('Button'):clone('CustomButton')

# Prototype:change_name([new_name=self.name])

Used internally to save concept names to the core gui module

Parameters:

• new_name : (string) the new name of the concept (default: self.name)

Usage:

-- Internal Saving
-- this is never needed to be done, internal use only!
local button = Gui.get_concept('Button')
button:change_name('Not Button')

# Prototype:new_event(event_name[, factorio_event][, event_condition])

Adds a new event trigger to the concept which can be linked to a factorio event

Parameters:

• event_name : (string) the name of the event to add, must be unique, recomented to start with "on_"
• factorio_event : (defines.events) when given will fire the custom event when the factorio event is raised (optional)
• event_condition : (function) used to filter when a factorio event triggers the custom event; if the event contains a reference to an element then names are automatically filtered (optional)

Returns:

• (GuiConcept) to allow chaining of functions

Usage:

-- Adds an on_admin_clicked event to fire when ever an admin clicks the button
local custom_button =
Gui.get_concept('Button'):clone('CustomButton')
:new_event('on_admin_clicked',defines.events.on_gui_click,function(event)
    return event.player.admin -- only raise custom event when an admin clicks the button
end)

# Prototype:on_custom_event(handler)

Adds a custom event handler, replace with the name of the event

Parameters:

• handler : (function) the function which will recive the event

Returns:

• (GuiConcept) to allow chaining of functions

Usage:

-- When an admin clicks the button a message is printed
local custom_button =
Gui.get_concept('CustomButton')
:on_admin_clicked(function(event)
    game.print(event.player.name..' pressed my admin button')
end)

# Prototype:raise_event(event_name[, event={}][, from_factorio=false])

Raises a custom event, folowing keys included automaticlly: concept, event name, game tick, player from player_index, element if valid

Parameters:

• event_name : (string) the name of the event that you want to raise
• event : (table) table containg data you want to send with the event, some keys already included (default: {})
• from_factorio : (boolean) internal use, if the raise came from the factorio event handler (default: false)

Usage:

-- Raising the custom event on_admin_clicked
local custom_button =
Gui.get_concept('CustomButton')

-- Note that this is an example and would not work due it expecting a valid element for event.element
-- this will however work fine if you can provide all expected keys, or its not linked to any factorio event
custom_button:raise_event('on_admin_clicked',{
    player_index = game.player.index
})

# Prototype:new_property(property_name, default[, setter_callback])

Adds a new property to the concept, such as caption, tooltip, or some custom property you want to control

Parameters:

• property_name : (string) the name of the new property, must be unique
• default : (any) the default value for this property, although not strictly required is is strongly recomented
• setter_callback : (function) this function is called when set is called, if not provided then key in concept.properties is updated to new value (optional)

Returns:

• (GuiConcept) to allow chaining of functions

Usage:

-- Adding caption, sprite, and tooltip to the base button concept
local button =
Gui.get_concept('Button')
:new_property('tooltip')
:new_property('caption',nil,function(properties,value)
    properties.caption = value
    properties.sprite = nil
    properties.type = 'button'
end)
:new_property('sprite',nil,function(properties,value)
    properties.image = value
    properties.caption = nil
    properties.type = 'sprite-button'
end)

# Prototype:set_custom_property(value)

Sets a new value for a property, triggers setter method if provided, replace with property name

Parameters:

• value : (any) the value that you want to set for this property

Returns:

• (GuiConcept) to allow chaining of functions

Usage:

-- Setting the caption on the base button concept after a cloning
local custom_button =
Gui.get_concept('Button')
:set_caption('Default Button')

-- In our examples CustomButton is cloned from Button, this means the caption property already exists
-- note that what ever values that properties have at the time of cloning are also copied
local custom_button =
Gui.get_concept('CustomButton')
:set_caption('Custom Button')

# Prototype:define_draw(draw_callback)

Used to define how the concept is turned into an ingame element or "instance" as we may refer to them

Parameters:

• draw_callback : (function) the function that will be called to draw/update the instance; this function must return the instance or the new acting instance

Returns:

• (GuiConcept) to allow chaining of functions

Usage:

-- Adding the draw define for the base button concept, we then return the element
local button =
Gui.get_concept('Button')
:define_draw(function(properties,parent,element)
    -- Note that element might be nil if this is the first draw function
    -- for this example we assume button was cloned from Prototype and so has no other draw functions defined
    -- this means that there is no element yet and what we return will be the first time the element is returned
    -- although not shown here you also can recive any extra arguments here from the call to draw
    if properties.type == 'button' then
        element = parent.draw{
            type = properties.type,
            name = properties.name,
            caption = properties.caption,
            tooltip = properties.tooltip
        }

    else
        element = parent.draw{
            type = properties.type,
            name = properties.name,
            sprite = properties.sprite,
            tooltip = properties.tooltip
        }

    end

    -- We must return the element or what we want to be seen as the instance, this is so other draw functions have access to it
    -- for example if our custom button defined a draw function to change the font color to red
    return element
end)

# Prototype:draw(parent_element)

Calls all the draw functions in order to create this concept in game; will also store and sync the instance if stores are used

Parameters:

• parent_element : (LuaGuiElement) the element that the concept will use as a base

Returns:

• (LuaGuiElement) the element that was created and then passed though and returned by the draw functions

Usage:

-- Drawing the custom button concept
local custom_button =
Gui.get_concept('CustomButton')

-- Note that the draw function from button was cloned, so unless we want to alter the base button we dont need a new draw define
custom_button:draw(game.player.gui.left)

Concept Instances

# Prototype:define_instance_store([category_callback])

Adds an instance store to the concept; when a new instance is made it is stored so you can access it later

Parameters:

• category_callback : (function) when given will act as a way to turn an element into a string to act as a key; keys returned can over lap (optional)

Returns:

• (GuiConcept) to allow chaining of functions

Usage:

-- Allowing storing instances of the custom button; stored by the players index
-- Note even thou this is a copy of Button; if Button had an instance store it would not be cloned over
local custom_button =
Gui.get_concept('CustomButton')
:define_instance_store(function(element)
    return element.player_index -- The instances are stored based on player id
end)

# Prototype.get_instances([category])

Gets all insatnces in a category, category may be nil to return all

Parameters:

• category : (string or LuaGuiElement) the category to get, can only be nil if categories are not used (optional)

Returns:

• (table) a table which contains all the instances

Usage:

-- Getting all the instances of the player with index 1
local custom_button =
Gui.get_concept('CustomButton')

custom_button.get_instances(1) -- player index 1

# Prototype.add_instance(element[, category])

Adds an instance to this concept, used automatically during concept:draw

Parameters:

• element : (LuaGuiElement) the element that will be added as an instance
• category : (string) the category to add this element under, if nil the category callback is used to assign one (optional)

Usage:

-- Adding an element as a instance for this concept, mostly for internal use
local custom_button =
Gui.get_concept('CustomButton')

custom_button.add_instance(element) -- normally not needed due to use in concept:draw

# Prototype.update_instances([category], update_callback)

Applies an update function to all instances, simialr use to what table.forEach would be

Parameters:

• category : (string or LuaGuiElement) the category to get, can only be nil if categories are not used (optional)
• update_callback : (function) the function which is called on each instance, recives other args passed to update_instances

Usage:

-- Changing the font color of all instances for player 1
local custom_button =
Gui.get_concept('CustomButton')

custom_button.update_instances(1,function(element)
    element.style.font_color = {r=1,g=0,b=0}
end)

Concept Data

# Prototype:define_data_store([category_callback])

Adds a data store to this concept which allows you to store synced/percistent data between instances

Parameters:

• category_callback : (function) when given will act as a way to turn an element into a string to act as a key; keys returned can over lap (optional)

Returns:

• (GuiConcept) to allow chaining of functions

Usage:

-- Adding a way to store data for this concept; each player has their own store
-- Note even thou this is a copy of Button; if Button had an data store it would not be cloned over
local custom_button =
Gui.get_concept('CustomButton')
:define_data_store(function(element)
    return element.player_index -- The data is stored based on player id
end)

# Prototype.get_data([category])

Gets the data that is stored for this category

Parameters:

• category : (string or LuaGuiElement) the category to get, can only be nil if categories are not used (optional)

Returns:

• (any) the data that you had stored in this location

Usage:

-- Getting the stored data for player 1
local custom_button =
Gui.get_concept('CustomButton')

custom_button.get_data(1) -- player index 1

# Prototype.set_data([category], value)

Sets the data that is stored for this category

Parameters:

• category : (string or LuaGuiElement) the category to set, can only be nil if categories are not used (optional)
• value : (any) the data that you want to stored in this location

Usage:

-- Setting the data for player 1 to a table with two keys
local custom_button =
Gui.get_concept('CustomButton')

-- A table is used to show correct way to use a table with self.update_data
-- but a table is not required and can be any data, however upvalues may cause desyncs
custom_button.set_data(1,{
    clicks = 0,
    required_clicks = 100
}) -- player index 1

# Prototype.clear_data([category])

Clears the data that is stored for this category

Parameters:

• category : (string or LuaGuiElement) the category to clear, can only be nil if categories are not used (optional)

Usage:

-- Clearing the data for player 1
local custom_button =
Gui.get_concept('CustomButton')

custom_button.clear_data(1) -- player index 1

# Prototype.update_data([category], update_callback)

Updates the data that is stored for this category

Parameters:

• category : (string or LuaGuiElement) the category to clear, can only be nil if categories are not used (optional)
• update_callback : (function) the function which is called to update the data

Usage:

-- Updating the clicks key in the concept data for player 1
local custom_button =
Gui.get_concept('CustomButton')

custom_button.update_data(1,function(tbl)
    tbl.clicks = tbl.clicks + 1 -- here we are incrementing the clicks by 1
end) -- player index 1

-- Updating a value when a table is not used, alterative to get set
-- so for this example assume that we did custom_button.set_data(1,0)
custom_button.update_data(1,function(value)
    return value + 1 -- here we are incrementing the value by 1, we may only be tracking clicks
end) -- player index 1

Concept Combined Instances

# Prototype:define_combined_store([category_callback], sync_callback)

Used to add a both instance and data store which are linked together, new instances are synced to the current value, changing the stored value will change all instances

Parameters:

• category_callback : (function) when given will act as a way to turn an element into a string to act as a key; keys returned can over lap (optional)
• sync_callback : (function) the function which is called to update an instance to match the store, this is called on all instances when concept.set_data or update_data is used

Returns:

• (GuiConcept) to allow chaining of functions

Usage:

-- Adding a check box which is a "global setting" synced between all players
local custom_button =
Gui.get_concept('checkbox'):clone('my_checkbox')
:set_caption('My Checkbox')
:set_tooltip('Clicking this check box will change it for everyone')
:on_state_changed(function(event)
    local element = event.element
    event.concept.set_data(element,element.state) -- Update the stored data to trigger an update of all other instances
end)
:define_combined_store(function(element,state) -- We could add a category function here if we wanted to
    element.state = state or false -- Note that the value passed may be nil if there is no stored value and no default set
end)

# Prototype.sync_instance(element)

Will sync an instance to match the stored value based on the given sync callback

Parameters:

• element : (LuaGuiElement) the element that you want to have update

Usage:

-- Setting the caption of this element to be the same as the stored value
local custom_button =
Gui.get_concept('CustomButton')

-- Used internally when first draw and automatically when the store updates
custom_button.sync_instance(element)

Tests

# run_tests(player[, category])

Runs a set of gui tests to ensure that the system is working

Parameters:

• player : (LuaPlayer) the player that the guis are made for and who recives the results
• category : (string) when given only tests in this category are ran (optional)

Usage:

-- Run all gui tests
Gui.run_tests(game.player)