From 64c318da984d34704f226667ce45096a84242ebb Mon Sep 17 00:00:00 2001 From: Cooldude2606 Date: Sun, 19 May 2019 20:45:34 +0100 Subject: [PATCH] Added comments --- expcore/Gui/instances.lua | 116 +++++++++++++++++++++++++++++++++++++- expcore/Gui/slider.lua | 3 +- 2 files changed, 115 insertions(+), 4 deletions(-) diff --git a/expcore/Gui/instances.lua b/expcore/Gui/instances.lua index 72532a4b..c1abecd0 100644 --- a/expcore/Gui/instances.lua +++ b/expcore/Gui/instances.lua @@ -1,4 +1,80 @@ --- This file is a breakout from core which forcues on instance management of defines +--[[ +>>>> Using registered instance groups + The main use of this module is to register a group of elements refered here as "instances of an element define" in which + is meant that you define the name of a group of drawn elements that are really just multiple versions of a single element. + For example this might be that you have one label in multiple places (either for one player or many) and you want to update + the caption of all of them at once; this is where this module comes it. + + First you must register the way that the intances are stored and under what name, using Instances.register you will give the + name of the collective group of instances followed by an optional categorise function which allows varients to be stored under one + name (like one for each force or player) + + -- categorise works in the same way as store categorise + -- so the function will worl here but no value is stored only gui elements + Instances.register('score',Gui.force_store) + + Then when you draw the new element to a gui you will want to add the element to the group: + + Instances.add_element('score',new_element) + + Then when you want to get the instances you have two options; Instances.get_elements or Instances.apply_to_elements when you want loop + over the elements it is more efficient to use apply_to_elements: + + Instances.get_elements('score','player') -- returns all elements that were added with the 'player' category + Instances.apply_to_elements('score','player',function(element) -- runs the function on every valid element + element.caption = 0 + end) + + Note that if you dont give a categorise function then you dont need to give a category when getting the elements. + +>>>> Using unregistered instance groups + When using a registered group and the functions that go with them it is much simpler to use and more importantly includes error checking + for valid instance group names; the down side is that the group must be registered which can only be done during startup and not during runtime. + To counter this there are two functions simlair to those above in order to add and get instances but may lead to errors not being noticed due to + the error interal error checking being skiped to allow it to work. + + The main difference between the two groups of functions is that the category must always be present even if is nil; example below shows how a + instance group would work when registered vs unregistered: + + -- Registered with category + Instances.register('score',Gui.force_store) -- force_store will return the force name of an element + Instances.add_element('score',new_element) -- the new element is added to the category based on in force + Instances.apply_to_elements('score','player',function(element) + element.caption = '0' + end) -- gets all instances from the player force and sets the caption to 0 + + -- Unregistered with category + Instances.unregistered_add_element('score','player',new_element) -- adds the new element to the player category + Instances.unregistered_apply_to_elements('score','player',function(element) + element.caption = '0' + end) -- gets all instances from the player force and sets the caption to 0 + + -- Registered without category; note that category can just be igroned + Instances.register('score') -- all instances will be under one group with no categories + Instances.add_element('score',new_element) -- adds the new element to the instance list + Instances.apply_to_elements('score',function(element) + element.caption = '0' + end) -- gets all instances and sets the element caption to 0 + + -- Unregistered without category; note that category must be given as nil + Instances.unregistered_add_element('score',nil,new_element) -- adds the new element to a single group with no categories + Instances.unregistered_apply_to_elements('score',nil,function(element) + element.caption = '0' + end) -- gets all instances and sets the element caption to 0 + +>>>> Functions + Instances.has_categories(name) --- Returns if a instnace group has a categorise function; must be registerd + 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 +]] local Global = require 'utils.global' local Instances = { @@ -9,14 +85,26 @@ Global.register(Instances.data,function(tbl) Instances.data = tbl end) +--- Returns if a instnace group has a categorise function; must be registerd +-- @tparam name string the name of the instance group +-- @treturn boolean true if there is a categorise function function Instances.has_categories(name) return type(Instances.categorise[name]) == 'function' end +--- Returns if the given name is a registered instance group +-- @tparam name string the name of the instance group you are testing +-- @treturn boolean true if the name is registered function Instances.is_registered(name) return Instances.categorise[name] ~= nil end +--- Registers the name of an instance group to allow for storing element instances +-- @tparam name string the name of the instance group; must to unique +-- @tparam[opt] 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 +-- @treturn string the name that was added so it can be used as a varible function Instances.register(name,categorise) if _LIFECYCLE ~= _STAGE.control then return error('Can only be called during the control stage', 2) @@ -34,6 +122,9 @@ function Instances.register(name,categorise) return name end +--- Adds an element to the instance group under the correct category; must be registered +-- @tparam name string the name of the instance group to add the element to +-- @tparam element LuaGuiElement the element to add the the instance group function Instances.add_element(name,element) if not Instances.categorise[name] then return error('Inavlid name for instance group: '..name,2) @@ -48,6 +139,10 @@ function Instances.add_element(name,element) end end +--- Gets all element instances without first removing any invalid ones; used internally and must be registered +-- @tparam name string the name of the instance group to get the instances of +-- @tparam[opt] category string the category to get the instance from, not needed when no categorise function +-- @treturn table the table of element instances of which some may be invalid function Instances.get_elements_raw(name,category) if not Instances.categorise[name] then return error('Inavlid name for instance group: '..name,2) @@ -60,6 +155,12 @@ function Instances.get_elements_raw(name,category) end end +--- Gets all valid element instances and has the option of running a callback on those that are valid +-- @tparam name string the name of the instance group to get the instances of +-- @tparam[opt] category string the category to get the instances of, not needed when no categorise function +-- @tparan[opt] callback function when given the callback will be ran on all valid elements +-- callback param - element LuaGuiElement - the current valid element +-- @treturn table the table of element instances with all invalid ones removed function Instances.get_valid_elements(name,category,callback) if not Instances.categorise[name] then return error('Inavlid name for instance group: '..name,2) @@ -83,10 +184,13 @@ end Instances.get_elements = Instances.get_valid_elements Instances.apply_to_elements = Instances.get_valid_elements -function Instances.unregistered_add_element(name,categorise,element) +--- A version of add_element that does not require the group to be registered +-- @tparam name string the name of the instance group to add the element to +-- @tparam category ?string|nil the category to add the element to, can be nil but must still be given +-- @tparam element LuaGuiElement the element to add to the instance group +function Instances.unregistered_add_element(name,category,element) if not Instances.data[name] then Instances.data[name] = {} end - if type(categorise) == 'function' then - local category = categorise(element) + if category then if not Instances.data[name][category] then Instances.data[name][category] = {} end table.insert(Instances.data[name][category],element) else @@ -94,6 +198,12 @@ function Instances.unregistered_add_element(name,categorise,element) end end +--- A version of get_elements that does not require the group to be registered +-- @tparam name string the name of the instance group to get the instances of +-- @tparam category ?string|nil the category to get the instances of, can be nil but must still be given +-- @tparam[opt] callback function when given will be called on all valid instances +-- callback param - element LuaGuiElement - the current valid element +-- @treturn table the table of element instances with all invalid ones removed function Instances.unregistered_get_elements(name,category,callback) local elements = Instances.data[name] if category then diff --git a/expcore/Gui/slider.lua b/expcore/Gui/slider.lua index eb1ba17a..08895d44 100644 --- a/expcore/Gui/slider.lua +++ b/expcore/Gui/slider.lua @@ -153,8 +153,9 @@ function Slider._prototype:draw_label(element) } local categorise = self.categorise or Gui.player_store + local category = categorise(new_element) - Instances.unregistered_add_element(name,categorise,new_element) + Instances.unregistered_add_element(name,category,new_element) return new_element end