## 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:
  - (LuaGuiElement) the center flow
# 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:
  - (LuaGuiElement) the new frame that was made
# 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:
  - (LuaGuiElement) the new frame that was made
# 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:
  - (LuaGuiElement) the new frame that was drawn
# 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:
  - (LuaGuiElement) the new frame that was drawn
# 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:
  - (LuaGuiElement) the left frame flow for the player
# 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:
  - (LuaGuiElement) the frame that was made
# 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:
  - (LuaGuiElement) 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

  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:
  - (LuaGuiElement) the new element that was created
# toggle_enabled(element)

  Will toggle the enabled state of an element

  Parameters:
  - element : (LuaGuiElement) the gui element to toggle
  Returns:
  - (boolean) the new state that the element has
# toggle_visible(element)

  Will toggle the visiblity of an element

  Parameters:
  - element : (LuaGuiElement) the gui element to toggle
  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:
  - (LuaGuiElement) the new flow that was created
# destroy_if_valid(element)

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

  Parameters:
  - element : (LuaGuiElement) the element to be destroied
  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:
  - (LuaGuiElement) the table that was made
# 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:
  - (boolean) true if successful

### 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:
  - (function) the event handler
# 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:
  - (function) the event handler

### 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:
  - (LuaGuiElement) the new element that was drawn
# 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