updated type hints and comments

graphics/element.lua

@@ -57,7 +57,7 @@ function element.new(args, constraint, child_offset_x, child_offset_y)
         offset_x = 0,
         offset_y = 0,
         next_y = 1,                                     -- next child y coordinate
-        next_id = 0,                                    -- next child ID[
+        next_id = 0,                                    -- next child ID
         subscriptions = {},                             ---@type { ps: psil, key: string, func: function }[]
         button_down = { events.new_coord_2d(-1, -1), events.new_coord_2d(-1, -1), events.new_coord_2d(-1, -1) },
         focused = false,
@@ -87,9 +87,9 @@ function element.new(args, constraint, child_offset_x, child_offset_y)
 
     setmetatable(public, self.mt)
 
-    -----------------------
-    -- PRIVATE FUNCTIONS --
-    -----------------------
+    ------------------------------
+    --#region PRIVATE FUNCTIONS --
+    ------------------------------
 
     -- use tab to jump to the next focusable field
     ---@param reverse boolean
@@ -150,9 +150,11 @@ function element.new(args, constraint, child_offset_x, child_offset_y)
         end
     end
 
-    -------------------------
-    -- PROTECTED FUNCTIONS --
-    -------------------------
+    --#endregion
+
+    --------------------------------
+    --#region PROTECTED FUNCTIONS --
+    --------------------------------
 
     -- prepare the template
     ---@param offset_x integer x offset for mouse events
@@ -371,7 +373,8 @@ function element.new(args, constraint, child_offset_x, child_offset_y)
     function protected.on_update(...) end
 
     --#endregion
-    --#region Accessors and Control --
+
+    --#region Accessors and Control
 
     -- get value
     ---@nodiscard
@@ -409,9 +412,13 @@ function element.new(args, constraint, child_offset_x, child_offset_y)
     -- stop animations
     function protected.stop_anim() end
 
-    -----------
-    -- SETUP --
-    -----------
+    --#endregion
+
+    --#endregion
+
+    ------------------
+    --#region SETUP --
+    ------------------
 
     -- get the parent window
     self.p_window = args.window
@@ -430,9 +437,11 @@ function element.new(args, constraint, child_offset_x, child_offset_y)
         self.id = args.parent.__add_child(args.id, protected)
     end
 
-    ----------------------
-    -- PUBLIC FUNCTIONS --
-    ----------------------
+    --#endregion
+
+    -----------------------------
+    --#region PUBLIC FUNCTIONS --
+    -----------------------------
 
     -- get the window object
     ---@nodiscard
@@ -474,7 +483,7 @@ function element.new(args, constraint, child_offset_x, child_offset_y)
         end
     end
 
-    -- ELEMENT TREE --
+    --#region ELEMENT TREE
 
     -- add a child element
     ---@package
@@ -590,14 +599,18 @@ function element.new(args, constraint, child_offset_x, child_offset_y)
         else return ({ protected.children[index].get() })[1] end
     end
 
-    -- AUTO-PLACEMENT --
+    --#endregion
+
+    --#region AUTO-PLACEMENT
 
     -- skip a line for automatically placed elements
     function public.line_break()
         self.next_y = self.next_y + 1
     end
 
-    -- PROPERTIES --
+    --#endregion
+
+    --#region PROPERTIES
 
     -- get element ID
     ---@nodiscard
@@ -724,7 +737,9 @@ function element.new(args, constraint, child_offset_x, child_offset_y)
         self.bounds.y2 = self.position.y + protected.frame.h - 1
     end
 
-    -- FUNCTION CALLBACKS --
+    --#endregion
+
+    --#region FUNCTION CALLBACKS
 
     -- handle a monitor touch or mouse click if this element is visible
     ---@param event mouse_interaction mouse interaction event
@@ -799,7 +814,9 @@ function element.new(args, constraint, child_offset_x, child_offset_y)
         ps.subscribe(key, func)
     end
 
-    -- VISIBILITY & ANIMATIONS --
+    --#endregion
+
+    --#region VISIBILITY & ANIMATIONS
 
     -- check if this element is visible
     function public.is_visible() return protected.window.isVisible() end
@@ -865,6 +882,10 @@ function element.new(args, constraint, child_offset_x, child_offset_y)
         end
     end
 
+    --#endregion
+
+    --#endregion
+
     return protected
 end
 

graphics/elements/controls/App.lua

@@ -20,7 +20,7 @@ local MOUSE_CLICK = core.events.MOUSE_CLICK
 ---@field fg_bg? cpair foreground/background colors
 ---@field hidden? boolean true to hide on initial draw
 
--- Create a new 'app' style button control element, like on a phone.
+-- Create a new app icon style button control element, like on a mobile device.
 ---@param args app_button_args
 ---@return App element, element_id id
 return function (args)

graphics/elements/controls/Radio2D.lua

@@ -23,7 +23,7 @@ local element = require("graphics.element")
 ---@field fg_bg? cpair foreground/background colors
 ---@field hidden? boolean true to hide on initial draw
 
--- Create a new 2D radio button list control element (latch selection, exclusively one color at a time).
+-- Create a new 2-dimensional (rows and columns of options) radio button list control element (latch selection, exclusively one color at a time).
 ---@param args radio_2d_args
 ---@return Radio2D element, element_id id
 return function (args)

graphics/elements/indicators/CoreMap.lua

@@ -13,7 +13,7 @@ local element = require("graphics.element")
 ---@field x? integer 1 if omitted
 ---@field y? integer auto incremented if omitted
 
--- Create a new core map box element.
+-- Create a new core map diagram indicator element.
 ---@nodiscard
 ---@param args core_map_args
 ---@return CoreMap element, element_id id