Cleaned core gui files

expcore/gui/core_defines.lua

@@ -1,5 +1,5 @@
 --[[-- Core Module - Gui
-- Used to define new gui elements and gui event handlers
+- Gui defines that are used internally by the gui system
 @module Gui
 ]]
 
@@ -9,7 +9,7 @@ local Event = require 'utils.event' --- @dep utils.event
 --- Core Defines.
 -- @section coreDefines
 
---- Button which toggles the top flow elements, shows inside top flow
+--- Button which toggles the top flow elements, version which shows inside the top flow when top flow is visible
 -- @element hide_top_flow
 local hide_top_flow =
 Gui.element{
@@ -28,7 +28,7 @@ Gui.element{
 end)
 Gui.core_defines.hide_top_flow = hide_top_flow
 
---- Button which toggles the top flow elements, shows inside left flow
+--- Button which toggles the top flow elements, version which shows inside the left flow when top flow is hidden
 -- @element show_top_flow
 local show_top_flow =
 Gui.element{
@@ -47,7 +47,7 @@ Gui.element{
 end)
 Gui.core_defines.show_top_flow = show_top_flow
 
---- Button which hides the elements in the left flow
+--- Button which hides the elements in the left flow, shows inside the left flow when frames are visible
 -- @element hide_left_flow
 local hide_left_flow =
 Gui.element{

expcore/gui/defines.lua

@@ -1,16 +1,19 @@
 --[[-- Core Module - Gui
-- Used to define new gui elements and gui event handlers
+- Common defines that are used by other modules, non of these are used internally
 @module Gui
 ]]
 
 local Gui = require 'expcore.gui.prototype'
 
---[[-- Draw a flow that has custom element alignments, default is right align
+--- Defines.
+-- @section defines
+
+--[[-- Draw a flow used to align its child elements, default is right align
 @element Gui.alignment
-@tparam LuaGuiElement parent the parent element that the alignment flow will be added to
+@tparam LuaGuiElement parent the parent element to which the alignment will be added
+@tparam[opt='alignment'] string name the name of the alignment flow which is added
 @tparam[opt='right'] string horizontal_align the horizontal alignment of the elements in the flow
 @tparam[opt='center'] string vertical_align the vertical alignment of the elements in the flow
-@tparam[opt='alignment'] string name the name of the alignment flow
 @treturn LuaGuiElement the alignment flow that was created
 
 @usage-- Adding a right align flow
@@ -21,13 +24,13 @@ local alignment = Gui.alignment(element,'example_center_top_alignment','center',
 
 ]]
 Gui.alignment =
-Gui.element(function(_,parent,_,_,name)
+Gui.element(function(_,parent,name,_,_)
     return parent.add{
         name = name or 'alignment',
         type = 'flow',
     }
 end)
-:style(function(style,_,horizontal_align,vertical_align,_)
+:style(function(style,_,_,horizontal_align,vertical_align)
     style.padding = {1,2}
     style.vertical_align = vertical_align or 'center'
     style.horizontal_align = horizontal_align or 'right'
@@ -37,18 +40,18 @@ end)
 
 --[[-- Draw a scroll pane that has a table inside of it
 @element Gui.scroll_table
-@tparam LuaGuiElement parent the parent element that the scroll table will be added to
+@tparam LuaGuiElement parent the parent element to which the scroll table will be added
 @tparam number height the maximum height for the scroll pane
 @tparam number column_count the number of columns that the table will have
-@tparam[opt='scroll'] string name the name of the scroll pane that is added, the table is always called 'table'
+@tparam[opt='scroll'] string name the name of the scroll pane that is added, the table is always called "table"
 @treturn LuaGuiElement the table that was created
 
 @usage-- Adding a scroll table with max height of 200 and column count of 3
-local scroll_table = Gui.scroll_table(element,'example_scroll_table',200,3)
+local scroll_table = Gui.scroll_table(element,200,3)
 
 ]]
 Gui.scroll_table =
-Gui.element(function(_,parent,_,column_count,name)
+Gui.element(function(_,parent,height,column_count,name)
     -- Draw the scroll
     local scroll_pane =
     parent.add{
@@ -60,6 +63,12 @@ Gui.element(function(_,parent,_,column_count,name)
         style = 'scroll_pane_under_subheader'
     }
 
+    -- Set the style of the scroll pane
+    local scroll_style = scroll_pane.style
+    scroll_style.padding = {1,3}
+    scroll_style.maximal_height = height
+    scroll_style.horizontally_stretchable = true
+
     -- Draw the table
     local scroll_table =
     scroll_pane.add{
@@ -71,35 +80,27 @@ Gui.element(function(_,parent,_,column_count,name)
     -- Return the scroll table
     return scroll_table
 end)
-:style(function(style,element,height,_,_)
-    -- Change the style of the scroll
-    local scroll_style = element.parent.style
-    scroll_style.padding = {1,3}
-    scroll_style.maximal_height = height
-    scroll_style.horizontally_stretchable = true
+:style{
+    padding = 0,
+    cell_padding = 0,
+    vertical_align = 'center',
+    horizontally_stretchable = true
+}
 
-    -- Change the style of the table
-    style.padding = 0
-    style.cell_padding = 0
-    style.vertical_align = 'center'
-    style.horizontally_stretchable = true
-end)
-
---[[-- Used to add a header to a frame, this has the option for a custom right alignment flow for buttons
+--[[-- Used to add a frame with the header style, has the option for a right alignment flow for buttons
 @element Gui.header
-@tparam LuaGuiElement parent the parent element that the header will be added to
+@tparam LuaGuiElement parent the parent element to which the header will be added
 @tparam ?string|Concepts.LocalizedString caption the caption that will be shown on the header
 @tparam[opt] ?string|Concepts.LocalizedString tooltip the tooltip that will be shown on the header
-@tparam[opt=false] boolean add_alignment when true an alignment flow will be added for buttons
-@tparam[opt='header'] string name the name of the header that is being added, the alignment is always called 'alignment'
+@tparam[opt=false] boolean add_alignment when true an alignment flow will be added to the header
+@tparam[opt='header'] string name the name of the header that is being added, the alignment is always called "alignment"
 @treturn LuaGuiElement either the header or the header alignment if add_alignment is true
 
 @usage-- Adding a custom header with a label
-local header_alignment = Gui.header(
+local header = Gui.header(
     element,
     'Example Caption',
-    'Example Tooltip',
-    true
+    'Example Tooltip'
 )
 
 ]]
@@ -134,21 +135,20 @@ Gui.element(function(_,parent,caption,tooltip,add_alignment,name)
     return add_alignment and Gui.alignment(header) or header
 end)
 
---[[-- Used to add a footer to a frame, this has the option for a custom right alignment flow for buttons
-@element Gui.header
-@tparam LuaGuiElement parent the parent element that the footer will be added to
+--[[-- Used to add a frame with the footer style, has the option for a right alignment flow for buttons
+@element Gui.footer
+@tparam LuaGuiElement parent the parent element to which the footer will be added
 @tparam ?string|Concepts.LocalizedString caption the caption that will be shown on the footer
 @tparam[opt] ?string|Concepts.LocalizedString tooltip the tooltip that will be shown on the footer
-@tparam[opt=false] boolean add_alignment when true an alignment flow will be added for buttons
-@tparam[opt='footer'] string name the name of the footer that is being added, the alignment is always called 'alignment'
+@tparam[opt=false] boolean add_alignment when true an alignment flow will be added to the footer
+@tparam[opt='footer'] string name the name of the footer that is being added, the alignment is always called "alignment"
 @treturn LuaGuiElement either the footer or the footer alignment if add_alignment is true
 
 @usage-- Adding a custom footer with a label
-local header_alignment = Gui.footer(
+local footer = Gui.footer(
     element,
     'Example Caption',
-    'Example Tooltip',
-    true
+    'Example Tooltip'
 )
 
 ]]
@@ -183,10 +183,10 @@ Gui.element(function(_,parent,caption,tooltip,add_alignment,name)
     return add_alignment and Gui.alignment(footer) or footer
 end)
 
---[[-- Used for left frame to add a nice boarder to them and contain them
+--[[-- Used for left frames to give them a nice boarder
 @element Gui.container
-@tparam LuaGuiElement parent the parent element that the container will be added to
-@tparam string name the name that you want to give the outer frame, often just event_trigger for a left frame
+@tparam LuaGuiElement parent the parent element to which the container will be added
+@tparam string name the name that you want to give to the outer frame, often just event_trigger
 @tparam number width the minimal width that the frame will have
 
 @usage-- Adding a container as a base

expcore/gui/helper_functions.lua

@@ -1,5 +1,5 @@
 --[[-- Core Module - Gui
-- Used to define new gui elements and gui event handlers
+- Functions used to help with the use of guis
 @module Gui
 ]]
 
@@ -9,7 +9,7 @@ local Gui = require 'expcore.gui.prototype'
 -- @section helperFunctions
 
 --[[-- Get the player that owns a gui element
-@tparam LuaGuiElement element the element that you want to get the owner of
+@tparam LuaGuiElement element the element to get the owner of
 @treturn LuaPlayer the player that owns this element
 
 @usage-- Geting the owner of an element
@@ -22,8 +22,8 @@ function Gui.get_player_from_element(element)
 end
 
 --[[-- Will toggle the enabled state of an element or set it to the one given
-@tparam LuaGuiElement element the element that you want to toggle the state of
-@tparam[opt] boolean state the state that you want to set
+@tparam LuaGuiElement element the element to toggle/set the enabled state of
+@tparam[opt] boolean state with given will set the state, else state will be toggled
 @treturn boolean the new enabled state that the element has
 
 @usage-- Toggling the the enabled state
@@ -38,8 +38,8 @@ function Gui.toggle_enabled_state(element,state)
 end
 
 --[[-- Will toggle the visible state of an element or set it to the one given
-@tparam LuaGuiElement element the element that you want to toggle the state of
-@tparam[opt] boolean state the state that you want to set
+@tparam LuaGuiElement element the element to toggle/set the visible state of
+@tparam[opt] boolean state with given will set the state, else state will be toggled
 @treturn boolean the new visible state that the element has
 
 @usage-- Toggling the the visible state
@@ -53,11 +53,11 @@ function Gui.toggle_visible_state(element,state)
     return state
 end
 
---[[-- Destory a gui element without causing any errors, likly if the element may have already been removed
+--[[-- Destory a gui element without causing any errors, often because the element was already removed
 @tparam LuaGuiElement element the element that you want to remove
 @treturn boolean true if the element was valid and has been removed
 
-@usage-- Likely use case for element not existing
+@usage-- Remove a child element if it exists
 Gui.destroy_if_valid(element[child_name])
 
 ]]
@@ -67,7 +67,7 @@ function Gui.destroy_if_valid(element)
     return true
 end
 
---[[-- Returns a table to be used as a style on sprite buttons, produces a sqaure button
+--[[-- Returns a table to be used as the style for a sprite buttons, produces a sqaure button
 @tparam number size the size that you want the button to be
 @tparam[opt=-2] number padding the padding that you want on the sprite
 @tparam[opt] table style any extra style settings that you want to have

expcore/gui/left_flow.lua

@@ -11,23 +11,26 @@ local hide_left_flow = Gui.core_defines.hide_left_flow.name
 --- Left Flow.
 -- @section leftFlow
 
---- Contains the uids of the elements that will show on the left flow and the open on join function
+-- Triggered when a user changed the visibility of a left flow element by clicking a button
+Gui.events.on_visibility_changed_by_click = 'on_visibility_changed_by_click'
+
+--- Contains the uids of the elements that will shown on the left flow and their join functions
 -- @table left_elements
 Gui.left_elements = {}
 
---[[-- Gets the flow which contains the elements for the left flow
+--[[-- Gets the flow refered to as the left flow, each player has one left flow
 @function Gui.get_left_flow(player)
-@tparam LuaPlayer player the player that you want to get the flow for
+@tparam LuaPlayer player the player that you want to get the left flow for
 @treturn LuaGuiElement the left element flow
 
-@usage-- Geting your left element flow
+@usage-- Geting your left flow
 local left_flow = Gui.get_left_flow(game.player)
 
 ]]
 Gui.get_left_flow = mod_gui.get_frame_flow
 
---[[-- Adds an element to be drawn to the left flow when a player joins
-@tparam[opt] ?boolean|function open_on_join called during first darw to decide if the element is visible
+--[[-- Sets an element define to be drawn to the left flow when a player joins, includes optional check
+@tparam[opt] ?boolean|function open_on_join called during first darw to decide if the element should be visible
 @treturn table the new element define that is used to register events to this element
 
 @usage-- Adding the example button
@@ -39,7 +42,7 @@ function Gui._prototype_element:add_to_left_flow(open_on_join)
     return self
 end
 
---[[-- Styles the top flow button depending on the state given
+--[[-- Styles a top flow button depending on the state given
 @tparam LuaGuiElement the button element to style
 @tparam boolean state The state the button is in
 
@@ -61,14 +64,15 @@ function Gui.left_toolbar_button_style(button, state)
     button.style.padding = -2
 end
 
---[[-- Button which can be used to toggle a left element, placed on the top flow
+--[[-- Creates a button on the top flow which will toggle the given element define, the define must exist in the left flow
 @tparam string sprite the sprite that you want to use on the button
 @tparam ?string|Concepts.LocalizedString tooltip the tooltip that you want the button to have
-@tparam table element_define the element define that you want to be toggled on the left flow
+@tparam table element_define the element define that you want to have toggled by this button, define must exist on the left flow
 @tparam[opt] function authenticator used to decide if the button should be visible to a player
 
 @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)
+local toolbar_button =
+Gui.left_toolbar_button('entity/inserter', 'Nothing to see here', example_flow_with_button, function(player)
     return player.admin
 end)
 
@@ -108,7 +112,7 @@ function Gui.left_toolbar_button(sprite,tooltip,element_define,authenticator)
     return button
 end
 
---[[-- Draw all the left elements onto the left flow, internal use only
+--[[-- Draw all the left elements onto the left flow, internal use only with on join
 @tparam LuaPlayer player the player that you want to draw the elements for
 
 @usage Draw all the left elements
@@ -156,11 +160,11 @@ function Gui.draw_left_flow(player)
     hide_button.visible = show_hide_button
 end
 
---[[-- Update the visible state of the hide left button, also draw left elements if not present
+--[[-- Update the visible state of the hide button, can be used to check if any frames are visible
 @tparam LuaPlayer player the player to update the left flow for
 @treturn boolean true if any left element is visible
 
-@usage Check if any left elements are visible
+@usage-- Check if any left elements are visible
 local visible = Gui.update_left_flow(player)
 
 ]]
@@ -185,6 +189,7 @@ Gui.hide_left_flow(game.player)
 
 ]]
 function Gui.hide_left_flow(player)
+    local top_flow = Gui.get_top_flow(player)
     local left_flow = Gui.get_left_flow(player)
     local hide_button = left_flow.gui_core_buttons[hide_left_flow]
 
@@ -193,11 +198,8 @@ function Gui.hide_left_flow(player)
     for name,_ in pairs(Gui.left_elements) do
         left_flow[name].visible = false
 
-        -- Get the assosiated element define
+        -- Check if the the element has a toobar button attached
         local element_define = Gui.defines[name]
-        local top_flow = Gui.get_top_flow(player)
-
-        -- Check if the the element has a button attached
         if element_define.toolbar_button then
             -- Check if the topflow contains the button
             local button = top_flow[element_define.toolbar_button]
@@ -217,13 +219,13 @@ function Gui.hide_left_flow(player)
     end
 end
 
---[[-- Get the element define that is in the left flow
-@tparam LuaPlayer player the player that you want tog et the element for
-@tparam table element_define the element that you want to get for the player
-@treturn LuaGuiElement the gui element linked to this define in the left flow
+--[[-- Get the element define that is in the left flow, use in events without an element refrence
+@tparam LuaPlayer player the player that you want to get the element for
+@tparam table element_define the element that you want to get
+@treturn 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)
+local frame = Gui.get_left_element(game.player, example_flow_with_button)
 
 ]]
 function Gui.get_left_element(player,element_define)
@@ -231,17 +233,17 @@ function Gui.get_left_element(player,element_define)
     return left_flow[element_define.name]
 end
 
---[[-- Toggles the visible state of a left element for a player
+--[[-- Toggles the visible state of a left element for a given player, can be used to set the visible state
 @tparam LuaPlayer player the player that you want to toggle the element for
-@tparam table element_define the element that you want to toggle for the player
-@tparam[opt] boolean state if given then the state will be set to this state
+@tparam table element_define the element that you want to toggle
+@tparam[opt] boolean state with given will set the state, else state will be toggled
 @treturn boolean the new visible state of the element
 
 @usage-- Toggle your example button
-Gui.toggle_top_flow(game.player,example_flow_with_button)
+Gui.toggle_top_flow(game.player, example_flow_with_button)
 
-@usage-- Open your example button
-Gui.toggle_top_flow(game.player,example_flow_with_button,true)
+@usage-- Show your example button
+Gui.toggle_top_flow(game.player, example_flow_with_button, true)
 
 ]]
 function Gui.toggle_left_element(player,element_define,state)

expcore/gui/prototype.lua

@@ -1,95 +1,148 @@
 --[[-- Core Module - Gui
-- Used to define new gui elements and gui event handlers
+- Used to simplify gui creation using factory functions called element defines
 @core Gui
 @alias Gui
 
-@usage-- Defining a button that prints the player's name
+@usage-- To draw your element you only need to call the factory function
+-- You are able to pass any other arguments that are used in your custom functions but the first is always the parent element
+local example_button_element = example_button(parent_element)
+
+@usage-- Making a factory function for a button with the caption "Example Button"
+-- This method has all the same features as LuaGuiElement.add
 local example_button =
 Gui.element{
     type = 'button',
     caption = 'Example Button'
 }
-:on_click(function(player,element,event)
-    player.print(player.name)
-end)
 
-@usage-- Defining a button with a custom style
-local example_button =
-Gui.element{
-    type = 'button',
-    caption = 'Example Button'
-}
-:style{
-    height = 25,
-    width = 100
-}
-:on_click(function(player,element,event)
-    player.print(player.name)
-end)
-
-@usage-- Defining a button using a custom function
+@usage-- Making a factory function for a button which is contained within a flow
+-- This method is for when you still want to register event handlers but cant use the table method
 local example_flow_with_button =
-Gui.element(function(event_trigger,parent)
-    -- Add the flow the button is in
+Gui.element(function(event_trigger,parent,...)
+    -- ... shows that all other arguments from the factory call are passed to this function
+    -- Here we are adding a flow which we will then later add a button to
     local flow =
-    parent.add{
+    parent.add{ -- paraent is the element which is passed to the factory function
         name = 'example_flow',
         type = 'flow'
     }
 
-    -- Get the players name
-    local player = game.players[parent.player_index]
-    local player_name = player.name
-
-    -- Add the button
+    -- Now we add the button to the flow that we created earlier
     local element =
     flow.add{
-        name = event_trigger,
+        name = event_trigger, -- event_trigger should be the name of any elements you want to trigger your event handlers
         type = 'button',
-        caption = 'Example Button: '..player_name
+        caption = 'Example Button'
     }
 
-    -- Set the style of the button
-    local style = element.style
-    style.height = 25
-    style.width = 100]
-    style.font_color = player.color
-
-    -- Return the element
+    -- You must return a new element, this is so styles can be applied and returned to the caller
+    -- You may return any of your elements that you added, consider the context in which it will be used for which should be returned
     return element
 end)
-:on_click(function(player,element,event)
-    player.print(player.name)
+
+@usage-- Styles can be added to any element define, simplest way mimics LuaGuiElement.style[key] = value
+local example_button =
+Gui.element{
+    type = 'button',
+    caption = 'Example Button',
+    style = 'forward_button' -- factorio styles can be applied here
+}
+:style{
+    height = 25, -- same as element.style.height = 25
+    width = 100 -- same as element.style.width = 25
+}
+
+@usage-- Styles can also have a custom function when the style is dynamic and depends on other factors
+-- Use this method if your style is dynamic and depends on other factors
+local example_button =
+Gui.element{
+    type = 'button',
+    caption = 'Example Button',
+    style = 'forward_button' -- factorio styles can be applied here
+}
+:style(function(style,element,...)
+    -- style is the current style object for the elemenent
+    -- element is the element that is being changed
+    -- ... shows that all other arguments from the factory call are passed to this function
+    local player = game.players[element.player_index]
+    style.height = 25
+    style.width = 100
+    style.font_color = player.color
 end)
 
-@usage-- Drawing an element
-local exmple_button_element = example_button(parent)
-local example_flow_with_button = example_flow_with_button(parent)
+@usage-- You are able to register event handlers to your elements, these can be factorio events or custom ones
+-- All events are checked to be valid before raising any handlers, this means element.valid = true and player.valid = true
+Gui.element{
+    type = 'button',
+    caption = 'Example Button'
+}
+:on_click(function(player,element,event)
+    -- player is the player who interacted with the element to cause the event
+    -- element is a refrence to the element which caused the event
+    -- event is a raw refrence to the event data if player and element are not enough
+    player.print('Clicked: '..element.name)
+end)
+
+@usage-- Example from core_defines, Gui.core_defines.hide_left_flow, called like: hide_left_flow(parent_element)
+--- Button which hides the elements in the left flow, shows inside the left flow when frames are visible
+-- @element hide_left_flow
+local hide_left_flow =
+Gui.element{
+    type = 'sprite-button',
+    sprite = 'utility/close_black',
+    style = 'tool_button',
+    tooltip = {'expcore-gui.left-button-tooltip'}
+}
+:style{
+    padding = -3,
+    width = 18,
+    height = 20
+}
+:on_click(function(player,_,_)
+    Gui.hide_left_flow(player)
+end)
+
+@usage-- Eample from defines, Gui.alignment, called like: Gui.alignment(parent, name, horizontal_align, vertical_align)
+-- Notice how _ are used to blank arguments that are not needed in that context and how they line up with above
+Gui.alignment =
+Gui.element(function(_,parent,name,_,_)
+    return parent.add{
+        name = name or 'alignment',
+        type = 'flow',
+    }
+end)
+:style(function(style,_,_,horizontal_align,vertical_align)
+    style.padding = {1,2}
+    style.vertical_align = vertical_align or 'center'
+    style.horizontal_align = horizontal_align or 'right'
+    style.vertically_stretchable  = style.vertical_align ~= 'center'
+    style.horizontally_stretchable = style.horizontal_align ~= 'center'
+end)
 
 ]]
 
 local Event = require 'utils.event' --- @dep utils.event
 
 local Gui = {
-    --- The current highest uid that is being used, will not increase during runtime
+    --- The current highest uid that is being used by a define, will not increase during runtime
     -- @field uid
     uid = 0,
-    --- An index of the element deinfes which are used by the core gui system
-    -- @table core_defines
-    core_defines = {},
-    --- Table of all the elements which have been registed with the draw function and event handlers
-    -- @table defines
-    defines = {},
-    --- Table of all custom events that are used by element defines, used to avoid conflicts
+    --- String indexed table used to avoid conflict with custom event names, similar to how defines.events works
     -- @table events
     events = {},
-    --- An index used for debuging to find the file where different elements where registered
+    --- Uid indexed array that stores all the factory functions that were defined, no new values will be added during runtime
+    -- @table defines
+    defines = {},
+    --- An string indexed table of all the defines which are used by the core of the gui system, used for internal refrence
+    -- @table core_defines
+    core_defines = {},
+    --- Used to store the file names where elements were defined, this can be useful to find the uid of an element, mostly for debuging
     -- @table file_paths
     file_paths = {},
-    --- An index used for debuging to show more data on element defines
+    --- Used to store extra infomation about elements as they get defined such as the params used and event handlers registered to them
     -- @table debug_info
     debug_info = {},
-    --- The element prototype which is returned from Gui.element
+    --- The prototype used to store the functions of an element define
     -- @table _prototype_element
     _prototype_element = {},
     --- The prototype metatable applied to new element defines
@@ -108,28 +161,33 @@ Gui._mt_element.__index = Gui._prototype_element
 --- Element Define.
 -- @section elementDefine
 
---[[-- Base function used to define new elements, can be used with a table or with a function
-@tparam ?table|function element_define used to define how the element is draw, using a table is the simplist way of doing this
-@treturn table the new element define that is used to register events to this element
+--[[-- Used to define new elements for your gui, can be used like LuaGuiElement.add or a custom function
+@tparam ?table|function element_define the define information for the gui element, same data as LuaGuiElement.add, or a custom function may be used
+@treturn 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-- Defining an element with a table
+@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'
 }
 
-@usage-- Defining an element with a function
+@usage-- 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,...)
-    -- Add the flow the button is in
+    -- ... 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'
     }
 
-    -- Add the button
+    -- 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,
@@ -137,12 +195,8 @@ Gui.element(function(event_trigger,parent,...)
         caption = 'Example Button'
     }
 
-    -- Set the style of the button
-    local style = element.style
-    style.height = 25
-    style.width = 100
-
-    -- Return the element
+    -- 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)
 
@@ -179,28 +233,34 @@ function Gui.element(element_define)
     return element
 end
 
---[[-- Extension of Gui.element when using the table method, values applied after the element is drawn
-@tparam ?table|function style_define used to define how the style is applied, using a table is the simplist way of doing this
-@treturn table the new element define that is used to register events to this element
+--[[-- 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
+@tparam ?table|function style_define style table where each key and value pair is treated like LuaGuiElement.style[key] = value, a custom function can be used
+@treturn table the element define is returned to allow for event handlers to be registered
 
-@usage-- Setting the height and width of the example button
+@usage-- Using the table method of setting the style
 local example_button =
 Gui.element{
     type = 'button',
-    caption = 'Example Button'
+    caption = 'Example Button',
+    style = 'forward_button' -- factorio styles can be applied here
 }
 :style{
-    height = 25,
-    width = 100
+    height = 25, -- same as element.style.height = 25
+    width = 100 -- same as element.style.width = 25
 }
 
-@usage-- Using a function to set the style
+@usage-- 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'
+    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
@@ -226,12 +286,12 @@ function Gui._prototype_element:style(style_define)
     return self
 end
 
---[[-- Set the handler to be called on a custom event, only one handler can be used
-@tparam string event_name the name of the event you want to handler to be called on
+--[[-- Set the handler which will be called for a custom event, only one handler can be used per event per element
+@tparam string event_name the name of the event you want to handler to be called on, often from Gui.events
 @tparam function handler the handler that you want to be called when the event is raised
 @treturn table the element define so more handleres can be registered
 
-@usage Print the player name when my_custom_event is raised
+@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)
@@ -244,8 +304,8 @@ function Gui._prototype_element:on_custom_event(event_name,handler)
     return self
 end
 
---[[-- Raise the handler which is attached to any event; external use should be limited to custom events
-@tparam table event the event table bassed to the handler, must include fields: name, element
+--[[-- Raise the handler which is attached to an event; external use should be limited to custom events
+@tparam table event the event table passed to the handler, must contain fields: name, element
 @treturn table the element define so more events can be raised
 
 @usage Raising a custom event
@@ -283,7 +343,7 @@ function Gui._prototype_element:raise_custom_event(event)
     return self
 end
 
--- This function is used to register a link between element define events and the events in the factorio api
+-- This function is used to link element define events and the events from the factorio api
 local function event_handler_factory(event_name)
     Event.add(event_name, function(event)
         local element = event.element
@@ -350,11 +410,5 @@ Gui._prototype_element.on_text_changed = event_handler_factory(defines.events.on
 -- @tparam function handler the event handler which will be called
 Gui._prototype_element.on_value_changed = event_handler_factory(defines.events.on_gui_value_changed)
 
---- Custom element events.
--- @section customEvents
-
--- Triggered when a user changed the visibility of a left flow element by clicking a button
-Gui.events.on_visibility_changed_by_click = 'on_visibility_changed_by_click'
-
 -- Module return
 return Gui

expcore/gui/top_flow.lua

@@ -1,5 +1,5 @@
 --[[-- Core Module - Gui
-- Used to define new gui elements and gui event handlers
+- Controls the elements on the top flow
 @module Gui
 ]]
 
@@ -12,7 +12,7 @@ local show_top_flow = Gui.core_defines.show_top_flow.name
 --- Top Flow.
 -- @section topFlow
 
---- Contains the uids of the elements that will show on the top flow and the auth function
+--- Contains the uids of the elements that will shown on the top flow and their auth functions
 -- @table top_elements
 Gui.top_elements = {}
 
@@ -20,29 +20,30 @@ Gui.top_elements = {}
 -- @field Gui.top_flow_button_style
 Gui.top_flow_button_style = mod_gui.button_style
 
---- The style that should be used for buttons on the top flow where the flow it opens is visible
+--- The style that should be used for buttons on the top flow when their flow is visible
 -- @field Gui.top_flow_button_visible_style
 Gui.top_flow_button_visible_style = 'menu_button_continue'
 
---[[-- Gets the flow which contains the elements for the top flow
+--[[-- Gets the flow refered to as the top flow, each player has one top flow
 @function Gui.get_top_flow(player)
 @tparam LuaPlayer player the player that you want to get the flow for
 @treturn LuaGuiElement the top element flow
 
-@usage-- Geting your top element flow
+@usage-- Geting your top flow
 local top_flow = Gui.get_top_flow(game.player)
 
 ]]
 Gui.get_top_flow = mod_gui.get_button_flow
 
---[[-- Adds an element to be drawn to the top flow when a player joins
-@tparam[opt] function authenticator called during toggle or update to decide if the element should be visible
-@treturn table the new element define that is used to register events to this element
+--[[-- Sets an element define to be drawn to the top flow when a player joins, includes optional authenticator
+@tparam[opt] function authenticator called during toggle or update to decide weather the element should be visible
+@treturn table the new element define to allow event handlers to be registered
 
-@usage-- Adding the example button
+@usage-- Adding an element to the top flow on join
 example_button:add_to_top_flow(function(player)
-    -- example button will only show when game time is less than 1 minute
-    return player.online_time < 3600
+    -- 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)
 
 ]]
@@ -51,10 +52,10 @@ function Gui._prototype_element:add_to_top_flow(authenticator)
     return self
 end
 
---[[-- Updates the visible states of all the elements on a players top flow
-@tparam LuaPlayer player the player that you want to update the flow for
+--[[-- Updates the visible state of all the elements on the players top flow, uses authenticator
+@tparam LuaPlayer player the player that you want to update the top flow for
 
-@usage-- Update your flow
+@usage-- Update your top flow
 Gui.update_top_flow(game.player)
 
 ]]
@@ -64,7 +65,7 @@ function Gui.update_top_flow(player)
     local is_visible = hide_button.visible
 
     -- Set the visible state of all elements in the flow
-    for name,authenticator in pairs(Gui.top_elements) do
+    for name, authenticator in pairs(Gui.top_elements) do
         -- Ensure the element exists
         local element = top_flow[name]
         if not element then
@@ -76,9 +77,9 @@ function Gui.update_top_flow(player)
     end
 end
 
---[[-- Toggles the visible states of all the elements on a players top flow
-@tparam LuaPlayer player the player that you want to toggle the flow for
-@tparam[opt] boolean state if given then the state will be set to this state
+--[[-- Toggles the visible state of all the elements on a players top flow, effects all elements
+@tparam LuaPlayer player the player that you want to toggle the top flow for
+@tparam[opt] boolean state if given then the state will be set to this
 @treturn boolean the new visible state of the top flow
 
 @usage-- Toggle your flow