## Gui module

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

### Dependencies

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

### Tables

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

### Fields

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

### Core Defines

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

### Defines

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

### Helper Functions

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

### Left Flow

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

### Element Define

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

### Element Events

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

### Top Flow

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

### Dependencies

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

### Tables

# events

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

# defines

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

# core_defines

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

# file_paths

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

# debug_info

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

# _prototype_element

  The prototype used to store the functions of an element define

# _mt_element

  The prototype metatable applied to new element defines

  Fields:
  - __call

### Fields

# uid

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

  - uid

### Core Defines

# hide_top_flow

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

# show_top_flow

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

# hide_left_flow

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

### Defines

# alignment

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

  Properties / Events:
  - parent : (LuaGuiElement) the parent element to which the alignment will be added
  - name : (string) the name of the alignment flow which is added (default: 'alignment')
  - horizontal_align : (string) the horizontal alignment of the elements in the flow (default: 'right')
  - vertical_align : (string) the vertical alignment of the elements in the flow (default: 'center')
  Usage:

      -- Adding a right align flow
      local alignment = Gui.alignment(element,'example_right_alignment')

      -- Adding a horizontal center and top align flow
      local alignment = Gui.alignment(element,'example_center_top_alignment','center','top')

# scroll_table

  Draw a scroll pane that has a table inside of it

  Properties / Events:
  - parent : (LuaGuiElement) the parent element to which the scroll table will be added
  - height : (number) the maximum height for the scroll pane
  - column_count : (number) the number of columns that the table will have
  - name : (string) the name of the scroll pane that is added, the table is always called "table" (default: 'scroll')
  Usage:

      -- Adding a scroll table with max height of 200 and column count of 3
      local scroll_table = Gui.scroll_table(element,200,3)

# header

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

  Properties / Events:
  - parent : (LuaGuiElement) the parent element to which the header will be added
  - caption : (string or LocalizedString) the caption that will be shown on the header
  - tooltip : (string or LocalizedString) the tooltip that will be shown on the header (optional)
  - add_alignment : (boolean) when true an alignment flow will be added to the header (default: false)
  - name : (string) the name of the header that is being added, the alignment is always called "alignment" (default: 'header')
  Usage:

      -- Adding a custom header with a label
      local header = Gui.header(
          element,
          'Example Caption',
          'Example Tooltip'
      )

# footer

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

  Properties / Events:
  - parent : (LuaGuiElement) the parent element to which the footer will be added
  - caption : (string or LocalizedString) the caption that will be shown on the footer
  - tooltip : (string or LocalizedString) the tooltip that will be shown on the footer (optional)
  - add_alignment : (boolean) when true an alignment flow will be added to the footer (default: false)
  - name : (string) the name of the footer that is being added, the alignment is always called "alignment" (default: 'footer')
  Usage:

      -- Adding a custom footer with a label
      local footer = Gui.footer(
          element,
          'Example Caption',
          'Example Tooltip'
      )

# container

  Used for left frames to give them a nice boarder

  Properties / Events:
  - parent : (LuaGuiElement) the parent element to which the container will be added
  - name : (string) the name that you want to give to the outer frame, often just event_trigger
  - width : (number) the minimal width that the frame will have
  Usage:

      -- Adding a container as a base
      local container = Gui.container(parent,'my_container',200)

# bar

  Used to make a solid white bar in a gui

  Properties / Events:
  - parent : (LuaGuiElement) the parent element to which the bar will be added
  - width : (number) the width of the bar that will be made, if not given bar will strech to fill the parent
  Usage:

      -- Adding a bar to a gui
      local bar = Gui.bar(parent, 100)

# centered_label

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

  Properties / Events:
  - parent : (LuaGuiElement) the parent element to which the label will be added
  - width : (number) the width of the label, must be given in order to center the caption
  - caption : (string or LocalizedString) the caption that will be shown on the label
  - tooltip : (string or LocalizedString) the tooltip that will be shown on the label (optional)
  Usage:

      -- Adding a centered label
      local label = Gui.centered_label(parent, 100, 'This is centered')

# title_label

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

  Properties / Events:
  - parent : (LuaGuiElement) the parent element to which the label will be added
  - width : (number) the width of the first bar, this can be used to position the label
  - caption : (string or LocalizedString) the caption that will be shown on the label
  - tooltip : (string or LocalizedString) the tooltip that will be shown on the label (optional)
  Usage:

      -- Adding a centered label
      local label = Gui.centered_label(parent, 100, 'This is centered')

### Helper Functions

# get_player_from_element(element)

  Get the player that owns a gui element

  Parameters:
  - element : (LuaGuiElement) the element to get the owner of
  Returns:
  - (LuaPlayer) the player that owns this element
  Usage:

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

# toggle_enabled_state(element[, state])

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

  Parameters:
  - element : (LuaGuiElement) the element to toggle/set the enabled state of
  - state : (boolean) with given will set the state, else state will be toggled (optional)
  Returns:
  - (boolean) the new enabled state that the element has
  Usage:

      -- Toggling the the enabled state
      local new_enabled_state = Gui.toggle_enabled_state(element)

# toggle_visible_state(element[, state])

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

  Parameters:
  - element : (LuaGuiElement) the element to toggle/set the visible state of
  - state : (boolean) with given will set the state, else state will be toggled (optional)
  Returns:
  - (boolean) the new visible state that the element has
  Usage:

      -- Toggling the the visible state
      local new_visible_state = Gui.toggle_visible_state(element)

# destroy_if_valid(element)

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

  Parameters:
  - element : (LuaGuiElement) the element that you want to remove
  Returns:
  - (boolean) true if the element was valid and has been removed
  Usage:

      -- Remove a child element if it exists
      Gui.destroy_if_valid(element[child_name])

# sprite_style(size[, padding=-2][, style])

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

  Parameters:
  - size : (number) the size that you want the button to be
  - padding : (number) the padding that you want on the sprite (default: -2)
  - style : (table) any extra style settings that you want to have (optional)
  Returns:
  - (table) the style table to be used with element_define:style()
  Usage:

      -- Adding a sprite button with size 20
      local button =
      Gui.element{
          type = 'sprite-button',
          sprite = 'entity/inserter'
      }
      :style(Gui.sprite_style(20))

### Left Flow

# left_elements

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

# get_left_flow(player)

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

  (player)

  Parameters:
  - player : (LuaPlayer) the player that you want to get the left flow for
  Returns:
  - (LuaGuiElement) the left element flow
  Usage:

      -- Geting your left flow
      local left_flow = Gui.get_left_flow(game.player)

# Gui._prototype_element:add_to_left_flow([open_on_join])

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

  Parameters:
  - open_on_join : (boolean or function) called during first darw to decide if the element should be visible (optional)
  Returns:
  - (table) the new element define that is used to register events to this element
  Usage:

      -- Adding the example button
      example_flow_with_button:add_to_left_flow(true)

# left_toolbar_button(sprite, tooltip, element_define[, authenticator])

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

  Parameters:
  - sprite : (string) the sprite that you want to use on the button
  - tooltip : (string or LocalizedString) the tooltip that you want the button to have
  - element_define : (table) the element define that you want to have toggled by this button, define must exist on the left flow
  - authenticator : (function) used to decide if the button should be visible to a player (optional)
  Usage:

      -- Add a button to toggle a left element
      local toolbar_button =
      Gui.left_toolbar_button('entity/inserter', 'Nothing to see here', example_flow_with_button, function(player)
          return player.admin
      end)

# draw_left_flow(player)

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

  Parameters:
  - player : (LuaPlayer) the player that you want to draw the elements for
  Usage:

       Draw all the left elements
      Gui.draw_left_flow(player)

# update_left_flow(player)

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

  Parameters:
  - player : (LuaPlayer) the player to update the left flow for
  Returns:
  - (boolean) true if any left element is visible
  Usage:

      -- Check if any left elements are visible
      local visible = Gui.update_left_flow(player)

# hide_left_flow(player)

  Hides all left elements for a player

  Parameters:
  - player : (LuaPlayer) the player to hide the elements for
  Usage:

      -- Hide your left elements
      Gui.hide_left_flow(game.player)

# get_left_element(player, element_define)

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

  Parameters:
  - player : (LuaPlayer) the player that you want to get the element for
  - element_define : (table) the element that you want to get
  Returns:
  - (LuaGuiElement) the gui element linked to this define for this player
  Usage:

      -- Get your left element
      local frame = Gui.get_left_element(game.player, example_flow_with_button)

# toggle_left_element(player, element_define[, state])

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

  Parameters:
  - player : (LuaPlayer) the player that you want to toggle the element for
  - element_define : (table) the element that you want to toggle
  - state : (boolean) with given will set the state, else state will be toggled (optional)
  Returns:
  - (boolean) the new visible state of the element
  Usage:

      -- Toggle your example button
      Gui.toggle_top_flow(game.player, example_flow_with_button)

      -- Show your example button
      Gui.toggle_top_flow(game.player, example_flow_with_button, true)

### Element Define

# element(element_define)

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

  Parameters:
  - element_define : (table or function) the define information for the gui element, same data as LuaGuiElement.add, or a custom function may be used
  Returns:
  - (table) the new element define, this can be considered a factory for the element which can be called to draw the element to any other element
  Usage:

      -- Using element defines like LuaGuiElement.add
      -- This returns a factory function to draw a button with the caption "Example Button"
      local example_button =
      Gui.element{
          type = 'button',
          caption = 'Example Button'
      }

      -- Using element defines with a custom factory function
      -- This method can be used if you still want to be able register event handlers but it is too complex to be compatible with LuaGuiElement.add
      local example_flow_with_button =
      Gui.element(function(event_trigger,parent,...)
          -- ... shows that all other arguments from the factory call are passed to this function
          -- parent is the element which was passed to the factory function where you should add your new element
          -- here we are adding a flow which we will then later add a button to
          local flow =
          parent.add{
              name = 'example_flow',
              type = 'flow'
          }

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

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

# Gui._prototype_element:style(style_define)

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

  Parameters:
  - style_define : (table or function) style table where each key and value pair is treated like LuaGuiElement.style[key] = value, a custom function can be used
  Returns:
  - (table) the element define is returned to allow for event handlers to be registered
  Usage:

      -- Using the table method of setting the style
      local example_button =
      Gui.element{
          type = 'button',
          caption = 'Example Button',
          style = 'forward_button' -- factorio styles can be applied here
      }
      :style{
          height = 25, -- same as element.style.height = 25
          width = 100 -- same as element.style.width = 25
      }

      -- Using the function method to set the style
      -- Use this method if your style is dynamic and depends on other factors
      local example_button =
      Gui.element{
          type = 'button',
          caption = 'Example Button',
          style = 'forward_button' -- factorio styles can be applied here
      }
      :style(function(style,element,...)
          -- style is the current style object for the elemenent
          -- element is the element that is being changed
          -- ... shows that all other arguments from the factory call are passed to this function
          local player = game.players[element.player_index]
          style.height = 25
          style.width = 100
          style.font_color = player.color
      end)

# Gui._prototype_element:on_custom_event(event_name, handler)

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

  Parameters:
  - event_name : (string) the name of the event you want to handler to be called on, often from Gui.events
  - handler : (function) the handler that you want to be called when the event is raised
  Returns:
  - (table) the element define so more handleres can be registered
  Usage:

      -- Register a handler to "my_custom_event" for this element
      element_deinfe:on_custom_event('my_custom_event', function(event)
          event.player.print(player.name)
      end)

# Gui._prototype_element:raise_custom_event(event)

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

  Parameters:
  - event : (table) the event table passed to the handler, must contain fields: name, element
  Returns:
  - (table) the element define so more events can be raised
  Usage:

       Raising a custom event
      element_define:raise_custom_event{
          name = 'my_custom_event',
          element = element
      }

### Element Events

# Gui._prototype_element.on_open

  Called when the player opens a GUI.

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

  Called when the player closes the GUI they have open.

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

  Called when LuaGuiElement is clicked.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  Called when LuaGuiElement text is changed by the player.

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

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

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

### Top Flow

# top_elements

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

# top_flow_button_style

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

# top_flow_button_visible_style

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

# get_top_flow(player)

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

  (player)

  Parameters:
  - player : (LuaPlayer) the player that you want to get the flow for
  Returns:
  - (LuaGuiElement) the top element flow
  Usage:

      -- Geting your top flow
      local top_flow = Gui.get_top_flow(game.player)

# Gui._prototype_element:add_to_top_flow([authenticator])

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

  Parameters:
  - authenticator : (function) called during toggle or update to decide weather the element should be visible (optional)
  Returns:
  - (table) the new element define to allow event handlers to be registered
  Usage:

      -- Adding an element to the top flow on join
      example_button:add_to_top_flow(function(player)
          -- example button will only be shown if the player is an admin
          -- note button will not update its state when player.admin is changed Gui.update_top_flow must be called for this
          return player.admin
      end)

# update_top_flow(player)

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

  Parameters:
  - player : (LuaPlayer) the player that you want to update the top flow for
  Usage:

      -- Update your top flow
      Gui.update_top_flow(game.player)

# toggle_top_flow(player[, state])

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

  Parameters:
  - player : (LuaPlayer) the player that you want to toggle the top flow for
  - state : (boolean) if given then the state will be set to this (optional)
  Returns:
  - (boolean) the new visible state of the top flow
  Usage:

      -- Toggle your flow
      Gui.toggle_top_flow(game.player)

      -- Open your top flow
      Gui.toggle_top_flow(game.player,true)

# get_top_element(player, element_define)

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

  Parameters:
  - player : (LuaPlayer) the player that you want to get the element for
  - element_define : (table) the element that you want to get
  Returns:
  - (LuaGuiElement) the gui element linked to this define for this player
  Usage:

      -- Get your top element
      local button = Gui.get_top_element(game.player, example_button)

# toolbar_button(sprite, tooltip[, authenticator])

  Creates a button on the top flow with consistent styling

  Parameters:
  - sprite : (string) the sprite that you want to use on the button
  - tooltip : (string or LocalizedString) the tooltip that you want the button to have
  - authenticator : (function) used to decide if the button should be visible to a player (optional)
  Usage:

      -- Add a button to the toolbar
      local toolbar_button =
      Gui.left_toolbar_button('entity/inserter', 'Nothing to see here', function(player)
          return player.admin
      end)

# toolbar_button_style(button, state)

  Styles a top flow button depending on the state given

  Parameters:
  - button : (LuaGuiElement) the button element to style
  - state : (boolean) The state the button is in
  Usage:

      -- Sets the button to the visible style
      Gui.toolbar_button_style(button, true)

      -- Sets the button to the hidden style
      Gui.toolbar_button_style(button, false)