Convert readme and science info

exp_gui/module/control.lua

@@ -19,7 +19,7 @@ end)
 --- @class ExpGui
 local ExpGui = {
     element = ExpElement.create,
-    property_from_args = ExpElement.property_from_args,
+    property_from_arg = ExpElement.property_from_arg,
     property_from_name = ExpElement.property_from_name,
     top_elements = {}, --- @type table<ExpElement, ExpGui.VisibleCallback | boolean>
     left_elements = {}, --- @type table<ExpElement, ExpGui.VisibleCallback | boolean>

exp_gui/module/elements.lua

@@ -0,0 +1,189 @@
+--- @class ExpGui
+local ExpGui = require("modules/exp_gui")
+
+--- @class ExpGui.elements
+local elements = {}
+ExpGui.elements = elements
+
+--- A flow which aligns its content as specified
+elements.aligned_flow = ExpGui.element("aligned_flow")
+    :draw{
+        type = "flow",
+        name = ExpGui.property_from_arg("name"),
+    }
+    :style(function(def, element, parent, opts)
+        opts = opts or {}
+        return {
+            padding = { 1, 2 },
+            vertical_align = opts.vertical_align or "center",
+            horizontal_align = opts.horizontal_align or "right",
+            vertically_stretchable = opts.vertical_align and opts.vertical_align ~= "center",
+            horizontally_stretchable = opts.horizontal_align and opts.horizontal_align ~= "center",
+        }
+    end)
+
+--- A solid horizontal white bar element
+elements.bar = ExpGui.element("bar")
+    :draw{
+        type = "progressbar",
+        value = 1,
+    }
+    :style(function(def, element, parent, width)
+        local style = element.style
+        style.color = { r = 255, g = 255, b = 255 }
+        style.height = 4
+        if width then
+            style.width = width
+        else
+            style.horizontally_stretchable = true
+        end
+    end)
+
+--- A label which is centered
+elements.centered_label = ExpGui.element("centered_label")
+    :draw{
+        type = "label",
+        caption = ExpGui.property_from_arg(2),
+        tooltip = ExpGui.property_from_arg(3),
+    }
+    :style{
+        horizontal_align = "center",
+        single_line = false,
+        width = ExpGui.property_from_arg(1),
+    }
+
+--- A label which has two white bars on either side of it
+elements.title_label = ExpGui.element("title_label")
+    :draw(function(def, parent, width, caption, tooltip)
+        local flow =
+            parent.add{
+                type = "flow"
+            }
+            
+        flow.style.vertical_align = "center"
+        elements.bar(flow, width)
+
+        local label =
+            flow.add{
+                type = "label",
+                style = "frame_title",
+                caption = caption,
+                tooltip = tooltip,
+            }
+
+        elements.bar(flow)
+
+        return label
+    end)
+
+--- A fixed size vertical scroll pane
+elements.scroll_pane = ExpGui.element("scroll_pane")
+    :draw{
+        type = "scroll-pane",
+        name = ExpGui.property_from_arg(2),
+        direction = "vertical",
+        horizontal_scroll_policy = "never",
+        vertical_scroll_policy = "auto",
+        style = "scroll_pane_under_subheader",
+    }
+    :style{
+        padding = { 1, 3 },
+        maximal_height = ExpGui.property_from_arg(1),
+        horizontally_stretchable = true,
+    }
+
+--- A fixed size vertical scroll pane containing a table
+elements.scroll_table = ExpGui.element("scroll_table")
+    :draw(function(def, parent, height, column_count, scroll_name)
+        local scroll_pane = elements.scroll_pane(parent, height, scroll_name)
+
+        return scroll_pane.add{
+            type = "table",
+            name = "table",
+            column_count = column_count,
+        }
+    end)
+    :style{
+        padding = 0,
+        cell_padding = 0,
+        vertical_align = "center",
+        horizontally_stretchable = true,
+    }
+
+--- A container frame
+elements.container = ExpGui.element("container")
+    :draw(function(def, parent, width, container_name)
+        local container =
+            parent.add{
+                type = "frame",
+                name = container_name,
+            }
+
+        local style = container.style
+        style.horizontally_stretchable = false
+        style.minimal_width = width
+        style.padding = 2
+
+        return container.add{
+            type = "frame",
+            name = "frame",
+            direction = "vertical",
+            style = "inside_shallow_frame_packed",
+        }
+    end)
+    :style{
+        vertically_stretchable = false,
+    }
+
+--- A frame within a container
+elements.subframe_base = ExpGui.element("container_subframe")
+    :draw{
+        type = "frame",
+        name = ExpGui.property_from_arg(2),
+        style = ExpGui.property_from_arg(1),
+    }
+    :style{
+        padding = { 2, 4 },
+        use_header_filler = false,
+        horizontally_stretchable = true,
+    }
+
+--- A header frame within a container
+elements.header = ExpGui.element("container_header")
+    :draw(function(def, parent, opts)
+        opts = opts or {}
+        local subframe = elements.subframe_base(parent, "subheader_frame", opts.name)
+
+        if opts.caption then
+            subframe.add{
+                type = "label",
+                name = opts.label_name,
+                caption = opts.caption,
+                tooltip = opts.tooltip,
+                style = "frame_title",
+            }
+        end
+
+        return elements.aligned_flow(subframe, { name = "flow" })
+    end)
+
+--- A footer frame within a container
+elements.footer = ExpGui.element("container_footer")
+    :draw(function(def, parent, opts)
+        opts = opts or {}
+        local subframe = elements.subframe_base(parent, "subfooter_frame", opts.name)
+
+        if opts.caption then
+            subframe.add{
+                type = "label",
+                name = opts.label_name,
+                caption = opts.caption,
+                tooltip = opts.tooltip,
+                style = "frame_title",
+            }
+        end
+
+        return elements.aligned_flow(subframe, { name = "flow" })
+    end)
+
+return elements

exp_gui/module/module.json

@@ -7,7 +7,9 @@
 		"control.lua"
 	],
 	"require": [
-		"core_elements.lua"
+		"core_elements.lua",
+		"elements.lua",
+		"styles.lua"
 	],
 	"dependencies": {
 		"clusterio": "*",

exp_gui/module/prototype.lua

@@ -60,24 +60,24 @@ function ExpElement.property_from_name()
     return ExpElement.property_from_name
 end
 
---- Used to signal that a property should be taken from the arguments
---- @param arg_number number?
---- @return [function, number?]
-function ExpElement.property_from_args(arg_number)
-    return { ExpElement.property_from_args, arg_number }
+--- Used to signal that a property should be taken from the arguments, a string means key of last arg
+--- @param arg number|string|nil
+--- @return [function, number|string|nil]
+function ExpElement.property_from_arg(arg)
+    return { ExpElement.property_from_arg, arg }
 end
 
 --- Extract the from args properties from a definition
 --- @param definition table
---- @return string[]
+--- @return table<string|number, string>
 function ExpElement._prototype:_extract_signals(definition)
     local from_args = {}
     for k, v in pairs(definition) do
-        if v == ExpElement.property_from_args then
+        if v == ExpElement.property_from_arg then
             from_args[#from_args + 1] = k
         elseif v == ExpElement.property_from_name then
             definition[k] = self.name
-        elseif type(v) == "table" and v[1] == ExpElement.property_from_args then
+        elseif type(v) == "table" and rawget(v, 1) == ExpElement.property_from_arg then
             from_args[v[2] or (#from_args + 1)] = k
         end
     end
@@ -179,8 +179,10 @@ function ExpElement._prototype:track_all_elements()
     return self
 end
 
+--- @alias ExpElement.add_param LuaGuiElement.add_param | table<string, [function, number|string|nil] | function>
+
 --- Set the draw definition
---- @param definition table | ExpElement.DrawCallback
+--- @param definition ExpElement.add_param | ExpElement.DrawCallback
 --- @return ExpElement
 function ExpElement._prototype:draw(definition)
     ExpUtil.assert_not_runtime()
@@ -193,7 +195,7 @@ function ExpElement._prototype:draw(definition)
     local from_args = self:_extract_signals(definition)
     self._debug.draw_definition = definition
 
-    if #from_args == 0 then
+    if not next(from_args) then
         self._draw = function(_, parent)
             return parent.add(definition)
         end
@@ -203,8 +205,14 @@ function ExpElement._prototype:draw(definition)
     self._debug.draw_from_args = from_args
     self._draw = function(_, parent, ...)
         local args = { ... }
+        local last = args[#args] or args
+        -- 'or args' used instead of empty table
         for i, k in pairs(from_args) do
-            definition[k] = args[i]
+            if type(i) == "string" then
+                definition[k] = last[i]
+            else
+                definition[k] = args[i]
+            end
         end
         return parent.add(definition)
     end

exp_gui/module/styles.lua

@@ -0,0 +1,16 @@
+--- @class ExpGui
+local ExpGui = require("modules/exp_gui")
+
+--- @class ExpGui.styles
+local styles = {}
+ExpGui.styles = styles
+
+function styles.sprite(style)
+    style = style or {}
+    if not style.padding then
+        style.padding = -2
+    end
+    return style
+end
+
+return styles