Gui core

Core Module - Gui - This file is used to require all the different elements of the gui module - each module has an outline here but for more details see their separate files in ./gui - please read the files for more documentation that cant be shown here - please note there is a rework planned but not started

Dependencies

expcore.gui.core
expcore.gui.instances
expcore.gui.elements.buttons
expcore.gui.elements.checkbox
expcore.gui.elements.dropdown
expcore.gui.elements.slider
expcore.gui.elements.text
expcore.gui.elements.elem-button
expcore.gui.elements.progress-bar
expcore.gui.concepts.toolbar
expcore.gui.concepts.left
expcore.gui.concepts.center
expcore.gui.concepts.popups

Center Guis

expcore.gui.core
expcore.gui.prototype
expcore.gui.concepts.toolbar
utils.game
CenterFrames.get_flow(player) Gets the center flow for a player
CenterFrames.clear_flow(player) Clears the center flow for a player
CenterFrames.draw_frame(player, name) Draws the center frame for a player, if already open then will do nothing
CenterFrames.redraw_frame(player, name) Draws the center frame for a player, if already open then will destroy it and redraw
CenterFrames.toggle_frame(player, name[, state]) Toggles if the frame is currently open or not, will open if closed and close if open
CenterFrames.new_frame(permission_name) Creates a new center frame define
CenterFrames._prototype:set_auto_focus([state=true]) Sets the frame to be the current active gui when opened and closes all other frames
CenterFrames._prototype:draw_frame(player) Draws this frame to the player, if already open does nothing (will call on_draw to draw to the frame)
CenterFrames._prototype:redraw_frame(player) Draws this frame to the player, if already open it will remove it and redraw it (will call on_draw to draw to the frame)
CenterFrames._prototype:toggle_frame(player) Toggles if the frame is open, if open it will close it and if closed it will open it
CenterFrames._prototype:event_handler([action=update]) Creates an event handler that will trigger one of its functions, use with Event.add

Left Guis

expcore.gui.core
expcore.gui.prototype
expcore.gui.concepts.toolbar
expcore.gui.elements.buttons
mod-gui
utils.game
utils.event
LeftFrames.get_flow(player) Gets the left frame flow for a player
LeftFrames.get_frame(name, player) Gets one frame from the left flow by its name
LeftFrames.get_open(player) Gets all open frames for a player, if non are open it will remove the close all button
LeftFrames.toggle_frame(name, player[, state]) Toggles the visibility of a left frame, or sets its visibility state
LeftFrames.new_frame(permission_name) Creates a new left frame define
LeftFrames._prototype:set_open_by_default([state=true]) Sets if the frame is visible when a player joins, can also be a function to return a boolean
LeftFrames._prototype:set_direction(direction) Sets the direction of the frame, either vertical or horizontal
LeftFrames._prototype:_internal_draw(player) Creates the gui for the first time, used internally
LeftFrames._prototype:get_frame(player) Gets the frame for this define from the left frame flow
LeftFrames._prototype:is_open(player) Returns if the player currently has this define visible
LeftFrames._prototype:toggle(player) Toggles the visibility of the left frame
LeftFrames._prototype:update(player) Updates the contents of the left frame, first tries update callback, other wise will clear and redraw
LeftFrames._prototype:update_all([update_offline=false]) Updates the frame for all players, see update
LeftFrames._prototype:redraw(player) Redraws the frame by calling on_draw, will always clear the frame
LeftFrames._prototype:redraw_all([update_offline=false]) Redraws the frame for all players, see redraw
LeftFrames._prototype:event_handler([action=update]) Creates an event handler that will trigger one of its functions, use with Event.add

Popups

expcore.gui.core
expcore.gui.prototype
utils.game
utils.event
expcore.gui.elements.progress-bar
expcore.gui.elements.buttons
mod-gui
resources.color_presets
utils.global
PopupFrames.get_flow(player) Gets the left flow that contains the popup frames
PopupFrames.open(define_name, player[, open_time], ...) Opens a popup for the player, can give the amount of time it is open as well as params for the draw function
PopupFrames.close_progress Progress bar which when depleted will close the popup frame
PopupFrames.close_button A button which can be used to close the gui before the timer runs out
PopupFrames.new_popup([name]) Creates a new popup frame define
PopupFrames._prototype:set_default_open_time(amount) Sets the default open time for the popup, will be used if non is provided with open
PopupFrames._prototype:open(player[, open_time], ...) Opens this define for a player, can be given open time and any other params for the draw function

Toolbar

expcore.gui.core
expcore.gui.elements.buttons
expcore.roles
utils.event
utils.game
mod-gui
Toolbar.new_button([name]) Adds a new button to the toolbar
Toolbar.add_button(button) Adds an existing buttton to the toolbar
Toolbar.update(player) Updates the player's toolbar with an new buttons or expected change in auth return

Core

utils.gui
utils.game
new_define(prototype[, debug_name]) Used to create new element defines from a class prototype, please use the own given by the class
get_define(name[, internal]) Gets an element define give the uid, debug name or a copy of the element define
categorize_by_player(element) A categorize function to be used with add_store, each player has their own value
categorize_by_force(element) A categorize function to be used with add_store, each force has its own value
categorize_by_surface(element) A categorize function to be used with add_store, each surface has its own value
draw(name, element) Draws a copy of the element define to the parent element, see draw_to
toggle_enabled(element) Will toggle the enabled state of an element
toggle_visible(element) Will toggle the visiblity of an element
set_padding(element[, up=0][, down=0][, left=0][, right=0]) Sets the padding for a gui element
set_padding_style(style[, up=0][, down=0][, left=0][, right=0]) Sets the padding for a gui style
create_alignment(element[, name][, horizontal_align='right'][, vertical_align='center']) Allows the creation of an alignment flow to place elements into
destroy_if_valid(element) Destroies an element but tests for it being present and valid first
create_scroll_table(element, table_size, maximal_height[, name='scroll']) Creates a scroll area with a table inside, table can be any size
create_header(element, caption[, tooltip][, right_align][, name='header']) Creates a header section with a label and button area

Buttons

mod-gui
expcore.gui.core
expcore.gui.prototype
Button.new_button([name]) Creates a new button element define
Button._prototype:set_sprites(sprite[, hovered_sprite][, clicked_sprite]) Adds sprites to a button making it a sprite button
Button._prototype:set_click_filter(filter[, ...]) Adds a click / mouse button filter to the button
Button._prototype:set_key_filter(filter[, ...]) Adds a control key filter to the button

Checkboxs

expcore.gui.core
expcore.gui.prototype
expcore.store
utils.game
Checkbox.new_checkbox([name]) Creates a new checkbox element define
Checkbox.new_radiobutton([name]) Creates a new radiobutton element define, has all functions checkbox has
Checkbox._prototype_radiobutton:add_as_option(option_set, option_name) Adds this radiobutton to be an option in the given option set (only one can be true at a time)
Checkbox._prototype_radiobutton:get_store(category, internal) Gets the stored value of the radiobutton or the option set if present
Checkbox._prototype_radiobutton:set_store(category, value, internal) Sets the stored value of the radiobutton or the option set if present
Checkbox.new_option_set(name, callback, categorize) Registers a new option set that can be linked to radiobuttons (only one can be true at a time)
Checkbox.draw_option_set(name, element) Draws all radiobuttons that are part of an option set at once (Gui.draw will not work)
Checkbox.reset_radiobuttons(element[, exclude][, recursive=false]) Sets all radiobutton in a element to false (unless excluded) and can act recursively

Dropdowns

expcore.gui.core
expcore.gui.prototype
utils.game
Dropdown.new_dropdown([name]) Creates a new dropdown element define
Dropdown.new_list_box([name]) Creates a new list box element define
Dropdown._prototype:new_static_options(options[, ...], the) Adds new static options to the dropdown which will trigger the general callback
Dropdown._prototype:new_dynamic_options(callback) Adds a callback which should return a table of values to be added as options for the dropdown (appended after static options)
Dropdown._prototype:add_option_callback(option, callback) Adds a case specific callback which will only run when that option is selected (general case still triggered)
Dropdown.select_value(element, value) Selects the option from a dropdown or list box given the value rather than key
Dropdown.get_selected_value(element) Returns the currently selected value rather than index

Elem Buttons

expcore.gui.core
expcore.gui.prototype
utils.game
ElemButton.new_elem_button([name]) Creates a new elem button element define
ElemButton._prototype.set_type Sets the type of the elem button, the type is required so this must be called at least once
ElemButton._prototype:set_default(value) Sets the default value for the elem button, this may be a function or a string

Progress Bars

expcore.gui.core
expcore.gui.prototype
utils.global
utils.game
ProgressBar.set_maximum(element, amount) Sets the maximum value that represents the end value of the progress bar
ProgressBar.increment(element[, amount=1]) Increases the value of the progressbar, if a define is given all of its instances have incremented
ProgressBar.decrement(element[, amount=1]) Decreases the value of the progressbar, if a define is given all of its instances have decremented
ProgressBar.new_progressbar([name]) Creates a new progressbar element define
ProgressBar._prototype:set_default_maximum(amount) Sets the maximum value that represents the end value of the progress bar
ProgressBar._prototype:use_count_down([state=true]) Will set the progress bar to start at 1 and trigger when it hits 0
ProgressBar._prototype:increment([amount=1][, category]) Increases the value of the progressbar
ProgressBar._prototype:increment_filtered([amount=1], filter) Increases the value of the progressbar, if the filter condition is met, does not work with store
ProgressBar._prototype:decrement([amount=1][, category]) Decreases the value of the progressbar
ProgressBar._prototype:decrement_filtered([amount=1], filter) Decreases the value of the progressbar, if the filter condition is met, does not work with store
ProgressBar._prototype:add_element(element[, maximum]) Adds an element into the list of instances that will are waiting to complete, does not work with store note use store if you want persistent data, this only stores the elements not the values which they have
ProgressBar._prototype:reset_element(element) Resets an element, or its store, to be back at the start, either 1 or 0
ProgressBar._prototype:event_counter([filter]) Event handler factory that counts up by 1 every time the event triggers, can filter which elements have incremented
ProgressBar._prototype:event_countdown([filter]) Event handler factory that counts down by 1 every time the event triggers, can filter which elements have decremented

Sliders

expcore.gui.core
expcore.gui.prototype
expcore.gui.instances
utils.game
Slider.new_slider([name]) Creates a new slider element define
Slider._prototype:set_range([min][, max]) Sets the range of a slider, if not used will use default values for a slider
Slider._prototype:draw_label(element) Draws a new label and links its value to the value of this slider, if no store then it will only show one value per player
Slider._prototype:enable_auto_draw_label([state=true]) Enables auto draw of the label, the label will share the same parent element as the slider

Text

expcore.gui.core
expcore.gui.prototype
utils.game
Text.new_text_field([name]) Creates a new text field element define
Text.new_text_box([name]) Creates a new text box element define
Text._prototype_box:set_selectable([state=true]) Sets the text box to be selectable
Text._prototype_box:set_word_wrap([state=true]) Sets the text box to have word wrap
Text._prototype_box:set_read_only([state=true]) Sets the text box to be read only

Instances

utils.global
Instances.has_categories(name) Returns if a instance group has a categorise function; must be registered
Instances.is_registered(name) Returns if the given name is a registered instance group
Instances.register(name[, categorise]) Registers the name of an instance group to allow for storing element instances
Instances.add_element(name, element) Adds an element to the instance group under the correct category; must be registered
Instances.get_elements_raw(name[, category]) Gets all element instances without first removing any invalid ones; used internally and must be registered
Instances.get_valid_elements(name[, category][, callback]) Gets all valid element instances and has the option of running a callback on those that are valid
Instances.unregistered_add_element(name, category, element) A version of add_element that does not require the group to be registered
Instances.unregistered_get_elements(name, category[, callback]) A version of get_elements that does not require the group to be registered

Prototype

utils.game
expcore.store
expcore.gui.instances
Constructor.event(event_name) Creates a new function to add functions to an event handler
Constructor.extend(new_prototype) Extents a prototype with the base functions of all gui prototypes, no metatables
Constructor.store(sync, callback) Creates a new function which adds a store to a gui define
Constructor.setter(value_type, key[, second_key]) Creates a setter function that checks the type when a value is set
Prototype:uid() Gets the uid for the element define
Prototype.debug_name Sets a debug alias for the define
Prototype.set_caption Sets the caption for the element define
Prototype.set_tooltip Sets the tooltip for the element define
Prototype.set_pre_authenticator Sets an authenticator that blocks the draw function if check fails
Prototype.set_post_authenticator Sets an authenticator that disables the element if check fails
Prototype.on_draw Registers a callback to the on_draw event
Prototype.on_style_update Registers a callback to the on_style_update event
Prototype:set_style(style[, callback]) Sets the style for the element define
Prototype:set_embedded_flow(state) Sets the element to be drawn inside a nameless flow, can be given a name using a function
Prototype:raise_event(event_name, ...) Raises a custom event for this define, any number of params can be given
Prototype:draw_to(element) The main function for defines, when called will draw an instance of this define to the given element what is drawn is based on the data in draw_data which is set using other functions
Prototype:get_store(category) Gets the value in this elements store, category needed if categorize function used
Prototype:set_store(category, value) Sets the value in this elements store, category needed if categorize function used
Prototype:clear_store([category]) Sets the value in this elements store to nil, category needed if categorize function used

Test

expcore.gui
expcore.common
resources.color_presets
utils.event
expcore.store

Dependencies

# expcore.gui.core
# expcore.gui.instances
# expcore.gui.elements.buttons
# expcore.gui.elements.checkbox
# expcore.gui.elements.dropdown
# expcore.gui.elements.slider
# expcore.gui.elements.text
# expcore.gui.elements.elem-button
# expcore.gui.elements.progress-bar
# expcore.gui.concepts.toolbar
# expcore.gui.concepts.left
# expcore.gui.concepts.center
# expcore.gui.concepts.popups

Center Guis

# expcore.gui.core
# expcore.gui.prototype
# expcore.gui.concepts.toolbar
# utils.game
# CenterFrames.get_flow(player)

Gets the center flow for a player

Parameters:
  • player : (LuaPlayer) the player to get the flow for
Returns:
# CenterFrames.clear_flow(player)

Clears the center flow for a player

Parameters:
  • player : (LuaPlayer) the player to clear the flow for
# CenterFrames.draw_frame(player, name)

Draws the center frame for a player, if already open then will do nothing

Parameters:
  • player : (LuaPlayer) the player that will have the frame drawn
  • name : (string) the name of the hui that will drawn
Returns:
# CenterFrames.redraw_frame(player, name)

Draws the center frame for a player, if already open then will destroy it and redraw

Parameters:
  • player : (LuaPlayer) the player that will have the frame drawn
  • name : (string) the name of the hui that will drawn
Returns:
# CenterFrames.toggle_frame(player, name[, state])

Toggles if the frame is currently open or not, will open if closed and close if open

Parameters:
  • player : (LuaPlayer) the player that will have the frame toggled
  • name : (string) the name of the hui that will be toggled
  • state : (boolean) when set will force a state for the frame (optional)
Returns:
  • (boolean) if the frame if no open or closed
# CenterFrames.new_frame(permission_name)

Creates a new center frame define

Parameters:
  • permission_name : (string) the name that can be used with the permission system
Returns:
  • (table) the new center frame define
# CenterFrames._prototype:set_auto_focus([state=true])

Sets the frame to be the current active gui when opened and closes all other frames

Parameters:
  • state : (boolean) when true will auto close other frames and set this frame as player.opened (default: true)
# CenterFrames._prototype:draw_frame(player)

Draws this frame to the player, if already open does nothing (will call on_draw to draw to the frame)

Parameters:
  • player : (LuaPlayer) the player to draw the frame for
Returns:
# CenterFrames._prototype:redraw_frame(player)

Draws this frame to the player, if already open it will remove it and redraw it (will call on_draw to draw to the frame)

Parameters:
  • player : (LuaPlayer) the player to draw the frame for
Returns:
# CenterFrames._prototype:toggle_frame(player)

Toggles if the frame is open, if open it will close it and if closed it will open it

Parameters:
  • player : (LuaPlayer) the player to draw the frame for
Returns:
  • (boolean) with the gui frame is now open
# CenterFrames._prototype:event_handler([action=update])

Creates an event handler that will trigger one of its functions, use with Event.add

Parameters:
  • action : (string) the action to take on this event (default: update)

Left Guis

# expcore.gui.core
# expcore.gui.prototype
# expcore.gui.concepts.toolbar
# expcore.gui.elements.buttons
# mod-gui
# utils.game
# utils.event
# LeftFrames.get_flow(player)

Gets the left frame flow for a player

Parameters:
  • player : (LuaPlayer) the player to get the flow of
Returns:
# LeftFrames.get_frame(name, player)

Gets one frame from the left flow by its name

Parameters:
  • name : (string) the name of the gui frame to get
  • player : (LuaPlayer) the player to get the frame of
Returns:
  • (LuaGuiElement) the frame in the left frame flow with that name
# LeftFrames.get_open(player)

Gets all open frames for a player, if non are open it will remove the close all button

Parameters:
  • player : (LuaPlayer) the player to get the flow of
Returns:
  • (table) contains all the open (and registered) frames for the player
# LeftFrames.toggle_frame(name, player[, state])

Toggles the visibility of a left frame, or sets its visibility state

Parameters:
  • name : (string) the name of the gui frame to toggle
  • player : (LuaPlayer) the player to get the frame of
  • state : (boolean) when given will be the state that the visibility is set to (optional)
Returns:
  • (boolean) the new state of the visibility
# LeftFrames.new_frame(permission_name)

Creates a new left frame define

Parameters:
  • permission_name : (string) the name that can be used with the permission system
Returns:
  • (table) the new left frame define
# LeftFrames._prototype:set_open_by_default([state=true])

Sets if the frame is visible when a player joins, can also be a function to return a boolean

Parameters:
  • state : (boolean or function) the default state of the visibility, can be a function state param - player LuaPlayer - the player that has joined the game state param - define_name string - the define name for the frame state return - boolean - false will hide the frame (default: true)
# LeftFrames._prototype:set_direction(direction)

Sets the direction of the frame, either vertical or horizontal

Parameters:
  • direction : (string) the direction to have the elements be added to the frame
# LeftFrames._prototype:_internal_draw(player)

Creates the gui for the first time, used internally

Parameters:
  • player : (LuaPlayer) the player to draw the frame to
Returns:
# LeftFrames._prototype:get_frame(player)

Gets the frame for this define from the left frame flow

Parameters:
  • player : (LuaPlayer) the player to get the frame of
Returns:
  • (LuaGuiElement) the frame in the left frame flow for this define
# LeftFrames._prototype:is_open(player)

Returns if the player currently has this define visible

Parameters:
  • player : (LuaPlayer) the player to get the frame of
Returns:
  • (boolean) true if it is open/visible
# LeftFrames._prototype:toggle(player)

Toggles the visibility of the left frame

Parameters:
  • player : (LuaPlayer) the player to toggle the frame of
Returns:
  • (boolean) the new state of the visibility
# LeftFrames._prototype:update(player)

Updates the contents of the left frame, first tries update callback, other wise will clear and redraw

Parameters:
  • player : (LuaPlayer) the player to update the frame of
# LeftFrames._prototype:update_all([update_offline=false])

Updates the frame for all players, see update

Parameters:
  • update_offline : (boolean) when true will update the frame for offline players (default: false)
# LeftFrames._prototype:redraw(player)

Redraws the frame by calling on_draw, will always clear the frame

Parameters:
  • player : (LuaPlayer) the player to update the frame of
# LeftFrames._prototype:redraw_all([update_offline=false])

Redraws the frame for all players, see redraw

Parameters:
  • update_offline : (boolean) when true will update the frame for offline players (default: false)
# LeftFrames._prototype:event_handler([action=update])

Creates an event handler that will trigger one of its functions, use with Event.add

Parameters:
  • action : (string) the action to take on this event (default: update)

Popups

# expcore.gui.core
# expcore.gui.prototype
# utils.game
# utils.event
# expcore.gui.elements.progress-bar
# expcore.gui.elements.buttons
# mod-gui
# resources.color_presets
# utils.global
# PopupFrames.get_flow(player)

Gets the left flow that contains the popup frames

Parameters:
  • player : (LuaPlayer) the player to get the flow for
Returns:
# PopupFrames.open(define_name, player[, open_time], ...)

Opens a popup for the player, can give the amount of time it is open as well as params for the draw function

Parameters:
  • define_name : (string) the name of the define that you want to open for the player
  • player : (LuaPlayer) the player to open the popup for
  • open_time : (number) the minimum number of ticks you want the popup open for, 0 means no limit, nil will take default (optional)
  • ... : (any) the other params that you want to pass to your on_draw event
Returns:
  • (LuaGuiElement) the frame that was drawn, the inner gui flow which contains the content
# PopupFrames.close_progress

Progress bar which when depleted will close the popup frame

# PopupFrames.close_button

A button which can be used to close the gui before the timer runs out

# PopupFrames.new_popup([name])

Creates a new popup frame define

Parameters:
  • name : (string) the optional debug name that can be added (optional)
Returns:
  • (table) the new popup frame define
# PopupFrames._prototype:set_default_open_time(amount)

Sets the default open time for the popup, will be used if non is provided with open

Parameters:
  • amount : (number) the number of ticks, by default, the popup will be open for
Returns:
  • (table) the define to allow for chaining
# PopupFrames._prototype:open(player[, open_time], ...)

Opens this define for a player, can be given open time and any other params for the draw function

Parameters:
  • player : (LuaPlayer) the player to open the popup for
  • open_time : (number) the minimum number of ticks you want the popup open for, 0 means no limit, nil will take default (optional)
  • ... : (any) the other params that you want to pass to your on_draw event
Returns:
  • (LuaGuiElement) the frame that was drawn, the inner gui flow which contains the content

Toolbar

# expcore.gui.core
# expcore.gui.elements.buttons
# expcore.roles
# utils.event
# utils.game
# mod-gui
# Toolbar.new_button([name])

Adds a new button to the toolbar

Parameters:
  • name : (string) when given allows an alias to the button for the permission system (optional)
Returns:
  • (table) the button define
# Toolbar.add_button(button)

Adds an existing buttton to the toolbar

Parameters:
  • button : (table) the button define for the button to be added
# Toolbar.update(player)

Updates the player's toolbar with an new buttons or expected change in auth return

Parameters:
  • player : (LuaPlayer) the player to update the toolbar for

Core

# utils.gui
# utils.game
# new_define(prototype[, debug_name])

Used to create new element defines from a class prototype, please use the own given by the class

Parameters:
  • prototype : (table) the class prototype that will be used for the element define
  • debug_name : (string) the name that you want to see while debuging (optional)
Returns:
  • (table) the new element define with all functions accessed via __index metamethod
# get_define(name[, internal])

Gets an element define give the uid, debug name or a copy of the element define

Parameters:
  • name : (string or table) the uid, debug name or define for the element define to get
  • internal : (boolean) when true the error trace is one level higher (used internally) (optional)
Returns:
  • (table) the element define that was found or an error
# categorize_by_player(element)

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

Parameters:
  • element : (LuaGuiElement) the element that will be converted to a string
Returns:
  • (string) the player's name who owns this element
# categorize_by_force(element)

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

Parameters:
  • element : (LuaGuiElement) the element that will be converted to a string
Returns:
  • (string) the player's force name who owns this element
# categorize_by_surface(element)

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

Parameters:
  • element : (LuaGuiElement) the element that will be converted to a string
Returns:
  • (string) the player's surface name who owns this element
# draw(name, element)

Draws a copy of the element define to the parent element, see draw_to

Parameters:
  • name : (string or table) the uid, debug name or define for the element define to draw
  • element : (LuaGuiEelement) the parent element that it the define will be drawn to
Returns:
# toggle_enabled(element)

Will toggle the enabled state of an element

Parameters: Returns:
  • (boolean) the new state that the element has
# toggle_visible(element)

Will toggle the visiblity of an element

Parameters: Returns:
  • (boolean) the new state that the element has
# 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) the amount of padding on the top (default: 0)
  • down : (number) the amount of padding on the bottom (default: 0)
  • left : (number) the amount of padding on the left (default: 0)
  • right : (number) the amount of padding on the right (default: 0)
# set_padding_style(style[, up=0][, down=0][, left=0][, right=0])

Sets the padding for a gui style

Parameters:
  • style : (LuaStyle) the element to set the padding for
  • up : (number) the amount of padding on the top (default: 0)
  • down : (number) the amount of padding on the bottom (default: 0)
  • left : (number) the amount of padding on the left (default: 0)
  • right : (number) the amount of padding on the right (default: 0)
# create_alignment(element[, name][, horizontal_align='right'][, vertical_align='center'])

Allows the creation of an alignment flow to place elements into

Parameters:
  • element : (LuaGuiElement) the element to add this alignment into
  • name : (string) the name to use for the alignment (optional)
  • horizontal_align : (string) the horizontal alignment of the elements in this flow (default: 'right')
  • vertical_align : (string) the vertical alignment of the elements in this flow (default: 'center')
Returns:
# destroy_if_valid(element)

Destroies an element but tests for it being present and valid first

Parameters: Returns:
  • (boolean) true if it was destoried
# create_scroll_table(element, table_size, maximal_height[, name='scroll'])

Creates a scroll area with a table inside, table can be any size

Parameters:
  • element : (LuaGuiElement) the element to add this scroll into
  • table_size : (number) the number of columns in the table
  • maximal_height : (number) the max hieght of the scroll
  • name : (string) the name of the scoll element (default: 'scroll')
Returns:
# create_header(element, caption[, tooltip][, right_align][, name='header'])

Creates a header section with a label and button area

Parameters:
  • element : (LuaGuiElement) the element to add this header into
  • caption : (localeString) the caption that is used as the title
  • tooltip : (localeString) the tooltip that is shown on the caption (optional)
  • right_align : (boolean) when true will include the right align area (optional)
  • name : (string) the name of the header area (default: 'header')
Returns:
  • (LuaGuiElement) the header that was made, or the align area if that was created

Buttons

# mod-gui
# expcore.gui.core
# expcore.gui.prototype
# Button.new_button([name])

Creates a new button element define

Parameters:
  • name : (string) the optional debug name that can be added (optional)
Returns:
  • (table) the new button element define
# Button._prototype:set_sprites(sprite[, hovered_sprite][, clicked_sprite])

Adds sprites to a button making it a sprite button

Parameters:
  • sprite : (SpritePath) the sprite path for the default sprite for the button
  • hovered_sprite : (SpritePath) the sprite path for the sprite when the player hovers over the button (optional)
  • clicked_sprite : (SpritePath) the sprite path for the sprite when the player clicks the button (optional)
Returns:
  • (self) returns the button define to allow chaining
# Button._prototype:set_click_filter(filter[, ...])

Adds a click / mouse button filter to the button

Parameters:
  • filter : (table) ?string|table either a of mouse buttons or the first mouse button to filter, with a table true means allowed
  • ... : (table) when filter is not a you can add the mouse buttons one after each other (optional)
Returns:
  • (self) returns the button define to allow chaining
# Button._prototype:set_key_filter(filter[, ...])

Adds a control key filter to the button

Parameters:
  • filter : (table) ?string|table either a of control keys or the first control keys to filter, with a table true means allowed
  • ... : (table) when filter is not a you can add the control keys one after each other (optional)
Returns:
  • (self) returns the button define to allow chaining

Checkboxs

# expcore.gui.core
# expcore.gui.prototype
# expcore.store
# utils.game
# Checkbox.new_checkbox([name])

Creates a new checkbox element define

Parameters:
  • name : (string) the optional debug name that can be added (optional)
Returns:
  • (table) the new checkbox element define
# Checkbox.new_radiobutton([name])

Creates a new radiobutton element define, has all functions checkbox has

Parameters:
  • name : (string) the optional debug name that can be added (optional)
Returns:
  • (table) the new button element define
# Checkbox._prototype_radiobutton:add_as_option(option_set, option_name)

Adds this radiobutton to be an option in the given option set (only one can be true at a time)

Parameters:
  • option_set : (string) the name of the option set to add this element to
  • option_name : (string) the name of this option that will be used to identify it
Returns:
  • (self) the define to allow chaining
# Checkbox._prototype_radiobutton:get_store(category, internal)

Gets the stored value of the radiobutton or the option set if present

Parameters:
  • category : (string) [opt] the category to get such as player name or force name
  • internal : (boolean) used to prevent stackover flow
Returns:
  • (any) the value that is stored for this define
# Checkbox._prototype_radiobutton:set_store(category, value, internal)

Sets the stored value of the radiobutton or the option set if present

Parameters:
  • category : (string) [opt] the category to get such as player name or force name
  • value : (boolean) the value to set for this define, must be valid for its type ie for checkbox etc
  • internal : (boolean) used to prevent stackover flow
Returns:
  • (boolean) true if the value was set
# Checkbox.new_option_set(name, callback, categorize)

Registers a new option set that can be linked to radiobuttons (only one can be true at a time)

Parameters:
  • name : (string) the name of the option set, must be unique
  • callback : (function) the update callback when the value of the option set changes callback param - value string - the new selected option for this option set callback param - category string - the category that updated if categorize was used
  • categorize : (function) the function used to convert an element into a string
Returns:
  • (string) the name of this option set to be passed to add_as_option
# Checkbox.draw_option_set(name, element)

Draws all radiobuttons that are part of an option set at once (Gui.draw will not work)

Parameters:
  • name : (string) the name of the option set to draw the radiobuttons of
  • element : (LuaGuiElement) the parent element that the radiobuttons will be drawn to
# Checkbox.reset_radiobuttons(element[, exclude][, recursive=false])

Sets all radiobutton in a element to false (unless excluded) and can act recursively

Parameters:
  • element : (LuaGuiElement) the root gui element to start setting radio buttons from
  • exclude : (table) ?string|table the name of the radiobutton to exclude or a of radiobuttons where true will set the state true (optional)
  • recursive : (number or boolean) if true will recur as much as possible, if a will recur that number of times (default: false)
Returns:

Dropdowns

# expcore.gui.core
# expcore.gui.prototype
# utils.game
# Dropdown.new_dropdown([name])

Creates a new dropdown element define

Parameters:
  • name : (string) the optional debug name that can be added (optional)
Returns:
  • (table) the new dropdown element define
# Dropdown.new_list_box([name])

Creates a new list box element define

Parameters:
  • name : (string) the optional debug name that can be added (optional)
Returns:
  • (table) the new list box element define
# Dropdown._prototype:new_static_options(options[, ...], the)

Adds new static options to the dropdown which will trigger the general callback

Parameters:
  • options : (table) ?string|table either a of option strings or the first option string, with a table values are the options
  • ... : (table) when options is not a you can add the options one after each other (optional)
  • the : (self) define to allow chaining
# Dropdown._prototype:new_dynamic_options(callback)

Adds a callback which should return a table of values to be added as options for the dropdown (appended after static options)

Parameters:
  • callback : (function) the function that will run to get the options for the dropdown callback param - player LuaPlayer - the player that the element is being drawn to callback param - element LuaGuiElement - the element that is being drawn callback return - table - the values of this table will be appended to the static options of the dropdown
Returns:
  • (self) the define to allow chaining
# Dropdown._prototype:add_option_callback(option, callback)

Adds a case specific callback which will only run when that option is selected (general case still triggered)

Parameters:
  • option : (string) the name of the option to trigger the callback on; if not already added then will be added as an option
  • callback : (function) the function that will be called when that option is selected callback param - player LuaPlayer - the player who owns the gui element callback param - element LuaGuiElement - the element which is being effected callback param - value string - the new option that has been selected
Returns:
  • (self) the define to allow chaining
# Dropdown.select_value(element, value)

Selects the option from a dropdown or list box given the value rather than key

Parameters:
  • element : (LuaGuiElement) the element that contains the option
  • value : (string) the option to select from the dropdown
Returns:
  • (number) the key where the value was
# Dropdown.get_selected_value(element)

Returns the currently selected value rather than index

Parameters:
  • element : (LuaGuiElement) the gui element that you want to get the value of
Returns:
  • (string) the value that is currently selected

Elem Buttons

# expcore.gui.core
# expcore.gui.prototype
# utils.game
# ElemButton.new_elem_button([name])

Creates a new elem button element define

Parameters:
  • name : (string) the optional debug name that can be added (optional)
Returns:
  • (table) the new elem button element define
# ElemButton._prototype.set_type

Sets the type of the elem button, the type is required so this must be called at least once

  • type : (string) the type that this elem button is see factorio api
# ElemButton._prototype:set_default(value)

Sets the default value for the elem button, this may be a function or a string

Parameters:
  • value : (string or function) string a will be a static default and a function will be called when drawn to get the default
Returns:
  • (the) element define to allow for chaining

Progress Bars

# expcore.gui.core
# expcore.gui.prototype
# utils.global
# utils.game
# ProgressBar.set_maximum(element, amount)

Sets the maximum value that represents the end value of the progress bar

Parameters:
  • element : (LuaGuiElement or string) either a gui element or a registered define
  • amount : (number) the amount to have set as the maximum
# ProgressBar.increment(element[, amount=1])

Increases the value of the progressbar, if a define is given all of its instances have incremented

Parameters:
  • element : (LuaGuiElement or string) either a gui element or a registered define
  • amount : (number) the amount to increase the progressbar by (default: 1)
# ProgressBar.decrement(element[, amount=1])

Decreases the value of the progressbar, if a define is given all of its instances have decremented

Parameters:
  • element : (LuaGuiElement or string) either a gui element or a registered define
  • amount : (number) the amount to decrease the progressbar by (default: 1)
# ProgressBar.new_progressbar([name])

Creates a new progressbar element define

Parameters:
  • name : (string) the optional debug name that can be added (optional)
Returns:
  • (table) the new progressbar element define
# ProgressBar._prototype:set_default_maximum(amount)

Sets the maximum value that represents the end value of the progress bar

Parameters:
  • amount : (number) the amount to have set as the maximum
Returns:
  • (table) the define to allow chaining
# ProgressBar._prototype:use_count_down([state=true])

Will set the progress bar to start at 1 and trigger when it hits 0

Parameters:
  • state : (boolean) when true the bar will start filled, to be used with decrease (default: true)
Returns:
  • (table) the define to allow chaining
# ProgressBar._prototype:increment([amount=1][, category])

Increases the value of the progressbar

Parameters:
  • amount : (number) the amount to increase the progressbar by (default: 1)
  • category : (string) the category that is used with a store (optional)
# ProgressBar._prototype:increment_filtered([amount=1], filter)

Increases the value of the progressbar, if the filter condition is met, does not work with store

Parameters:
  • amount : (number) the amount to increase the progressbar by (default: 1)
  • filter : (function) the filter to be used
# ProgressBar._prototype:decrement([amount=1][, category])

Decreases the value of the progressbar

Parameters:
  • amount : (number) the amount to decrease the progressbar by (default: 1)
  • category : (string) the category that is used with a store (optional)
# ProgressBar._prototype:decrement_filtered([amount=1], filter)

Decreases the value of the progressbar, if the filter condition is met, does not work with store

Parameters:
  • amount : (number) the amount to decrease the progressbar by (default: 1)
  • filter : (function) the filter to be used
# ProgressBar._prototype:add_element(element[, maximum])

Adds an element into the list of instances that will are waiting to complete, does not work with store note use store if you want persistent data, this only stores the elements not the values which they have

Parameters:
  • element : (LuaGuiElement) the element that you want to add into the waiting to complete list
  • maximum : (number) the maximum for this element if not given the default for this define is used (optional)
# ProgressBar._prototype:reset_element(element)

Resets an element, or its store, to be back at the start, either 1 or 0

Parameters:
  • element : (LuaGuiElement) the element that you want to reset the progress of
# ProgressBar._prototype:event_counter([filter])

Event handler factory that counts up by 1 every time the event triggers, can filter which elements have incremented

Parameters:
  • filter : (function) when given will use filtered increment (optional)
Returns:
# ProgressBar._prototype:event_countdown([filter])

Event handler factory that counts down by 1 every time the event triggers, can filter which elements have decremented

Parameters:
  • filter : (function) when given will use filtered decrement (optional)
Returns:

Sliders

# expcore.gui.core
# expcore.gui.prototype
# expcore.gui.instances
# utils.game
# Slider.new_slider([name])

Creates a new slider element define

Parameters:
  • name : (string) the optional debug name that can be added (optional)
Returns:
  • (table) the new slider element define
# Slider._prototype:set_range([min][, max])

Sets the range of a slider, if not used will use default values for a slider

Parameters:
  • min : (number) the minimum value that the slider can take (optional)
  • max : (number) the maximum value that the slider can take (optional)
Returns:
  • (self) the define to allow chaining
# Slider._prototype:draw_label(element)

Draws a new label and links its value to the value of this slider, if no store then it will only show one value per player

Parameters:
  • element : (LuaGuiElement) the parent element that the label will be drawn to
Returns:
  • (LuaGuiElement) the new label element so that styles can be applied
# Slider._prototype:enable_auto_draw_label([state=true])

Enables auto draw of the label, the label will share the same parent element as the slider

Parameters:
  • state : (boolean) when false will disable the auto draw of the label (default: true)
Returns:
  • (self) the define to allow chaining

Text

# expcore.gui.core
# expcore.gui.prototype
# utils.game
# Text.new_text_field([name])

Creates a new text field element define

Parameters:
  • name : (string) the optional debug name that can be added (optional)
Returns:
  • (table) the new text field element define
# Text.new_text_box([name])

Creates a new text box element define

Parameters:
  • name : (string) the optional debug name that can be added (optional)
Returns:
  • (table) the new text box element define
# Text._prototype_box:set_selectable([state=true])

Sets the text box to be selectable

Parameters:
  • state : (boolean) when false will set the state to false (default: true)
Returns:
  • (self) table the define to allow for chaining
# Text._prototype_box:set_word_wrap([state=true])

Sets the text box to have word wrap

Parameters:
  • state : (boolean) when false will set the state to false (default: true)
Returns:
  • (self) table the define to allow for chaining
# Text._prototype_box:set_read_only([state=true])

Sets the text box to be read only

Parameters:
  • state : (boolean) when false will set the state to false (default: true)
Returns:
  • (self) table the define to allow for chaining

Instances

# utils.global
# Instances.has_categories(name)

Returns if a instance group has a categorise function; must be registered

Parameters:
  • name : (string) the name of the instance group
Returns:
  • (boolean) true if there is a categorise function
# Instances.is_registered(name)

Returns if the given name is a registered instance group

Parameters:
  • name : (string) the name of the instance group you are testing
Returns:
  • (boolean) true if the name is registered
# Instances.register(name[, categorise])

Registers the name of an instance group to allow for storing element instances

Parameters:
  • name : (string) the name of the instance group; must to unique
  • categorise : (function) function used to turn the element into a string categorise param - element LuaGuiElement - the gui element to be turned into a string categorise return - string - the category that the element will be added to like the player's name or force's name (optional)
Returns:
  • (string) the name that was added so it can be used as a variable
# Instances.add_element(name, element)

Adds an element to the instance group under the correct category; must be registered

Parameters:
  • name : (string) the name of the instance group to add the element to
  • element : (LuaGuiElement) the element to add the the instance group
# Instances.get_elements_raw(name[, category])

Gets all element instances without first removing any invalid ones; used internally and must be registered

Parameters:
  • name : (string) the name of the instance group to get the instances of
  • category : (string) the category to get the instance from, not needed when no categorise function (optional)
Returns:
  • (table) the table of element instances of which some may be invalid
# Instances.get_valid_elements(name[, category][, callback])

Gets all valid element instances and has the option of running a callback on those that are valid

Parameters:
  • name : (string) the name of the instance group to get the instances of
  • category : (string) the category to get the instances of, not needed when no categorise function (optional)
  • callback : (function) when given the callback will be ran on all valid elements callback param - element LuaGuiElement - the current valid element (optional)
Returns:
  • (table) the table of element instances with all invalid ones removed
# Instances.unregistered_add_element(name, category, element)

A version of add_element that does not require the group to be registered

Parameters:
  • name : (string) the name of the instance group to add the element to
  • category : (string or nil) the category to add the element to, can be nil but must still be given
  • element : (LuaGuiElement) the element to add to the instance group
# Instances.unregistered_get_elements(name, category[, callback])

A version of get_elements that does not require the group to be registered

Parameters:
  • name : (string) the name of the instance group to get the instances of
  • category : (string or nil) the category to get the instances of, can be nil but must still be given
  • callback : (function) when given will be called on all valid instances callback param - element LuaGuiElement - the current valid element (optional)
Returns:
  • (table) the table of element instances with all invalid ones removed

Prototype

# utils.game
# expcore.store
# expcore.gui.instances
# Constructor.event(event_name)

Creates a new function to add functions to an event handler

Parameters:
  • event_name : (string) the name of the event that callbacks will be added to
Returns:
  • (function) the function used to register handlers
# Constructor.extend(new_prototype)

Extents a prototype with the base functions of all gui prototypes, no metatables

Parameters:
  • new_prototype : (table) the prototype that you want to add the functions to
Returns:
  • (table) the same prototype but with the new functions added
# Constructor.store(sync, callback)

Creates a new function which adds a store to a gui define

Parameters:
  • sync : (boolean) if the function should create a synced store
  • callback : (function) the function called when needing to update the value of an element
Returns:
  • (function) the function that will add a store for this define
# Constructor.setter(value_type, key[, second_key])

Creates a setter function that checks the type when a value is set

Parameters:
  • value_type : (string) the type that the value should be when it is set
  • key : (string) the key of the define that will be set
  • second_key : (string) allows for setting of a key in a sub table (optional)
Returns:
  • (function) the function that will check the type and set the value
# Prototype:uid()

Gets the uid for the element define

Returns:
  • (string) the uid of this element define
# Prototype.debug_name

Sets a debug alias for the define

  • name : (string) the debug name for the element define that can be used to get this element define
# Prototype.set_caption

Sets the caption for the element define

  • caption : (string) the caption that will be drawn with the element
# Prototype.set_tooltip

Sets the tooltip for the element define

  • tooltip : (string) the tooltip that will be displayed for this element when drawn
# Prototype.set_pre_authenticator

Sets an authenticator that blocks the draw function if check fails

  • callback : (function) the function that will be ran to test if the element should be drawn or not callback param - LuaPlayer player - the player that the element is being drawn to callback param - string define_name - the name of the define that is being drawn callback return - boolean - false will stop the element from being drawn
# Prototype.set_post_authenticator

Sets an authenticator that disables the element if check fails

  • callback : (function) the function that will be ran to test if the element should be enabled or not callback param - LuaPlayer player - the player that the element is being drawn to callback param - string define_name - the name of the define that is being drawn callback return - boolean - false will disable the element
# Prototype.on_draw

Registers a callback to the on_draw event

  • callback : (function) callback param - LuaPlayer player - the player that the element was drawn to callback param - LuaGuiElement element - the element that was drawn callback param - any ... - any other params passed by the draw_to function
# Prototype.on_style_update

Registers a callback to the on_style_update event

  • callback : (function) callback param - LuaStyle style - the style that was changed and/or needs changing
# Prototype:set_style(style[, callback])

Sets the style for the element define

Parameters:
  • style : (string) the style that will be used for this element when drawn
  • callback : (function) function is called when element is drawn to alter its style (optional)
Returns:
  • (self) the element define to allow chaining
# Prototype:set_embedded_flow(state)

Sets the element to be drawn inside a nameless flow, can be given a name using a function

Parameters:
  • state : (boolean or function) when true a padless flow is created to contain the element
Returns:
  • (self) the element define to allow chaining
# Prototype:raise_event(event_name, ...)

Raises a custom event for this define, any number of params can be given

Parameters:
  • event_name : (string) the name of the event that you want to raise
  • ... : (any) any params that you want to pass to the event
Returns:
  • (number) the number of handlers that were registered
# Prototype:draw_to(element)

The main function for defines, when called will draw an instance of this define to the given element what is drawn is based on the data in draw_data which is set using other functions

Parameters:
  • element : (LuaGuiElement) the element that the define will draw a instance of its self onto
Returns:
# Prototype:get_store(category)

Gets the value in this elements store, category needed if categorize function used

Parameters:
  • category : (string) [opt] the category to get such as player name or force name
Returns:
  • (any) the value that is stored for this define
# Prototype:set_store(category, value)

Sets the value in this elements store, category needed if categorize function used

Parameters:
  • category : (string) [opt] the category to get such as player name or force name
  • value : (any) the value to set for this define, must be valid for its type ie for checkbox etc
Returns:
  • (boolean) true if the value was set
# Prototype:clear_store([category])

Sets the value in this elements store to nil, category needed if categorize function used

Parameters:
  • category : (string) the category to get such as player name or force name (optional)
Returns:
  • (boolean) true if the value was set

Test

# expcore.gui
# expcore.common
# resources.color_presets
# utils.event
# expcore.store