#544 #545 updates to graphics animations, controls, and form elements

coordinator/configure.lua

@@ -460,9 +460,9 @@ local function config_view(display)
     TextBox{parent=net_c_4,x=1,y=4,height=6,text="This enables verifying that messages are authentic, so it is intended for security on multiplayer servers. All devices on the same network MUST use the same key if any device has a key. This does result in some extra compution (can slow things down).",fg_bg=g_lg_fg_bg}
 
     TextBox{parent=net_c_4,x=1,y=11,text="Facility Auth Key"}
-    local key, _, censor = TextField{parent=net_c_4,x=1,y=12,max_len=64,value=ini_cfg.AuthKey,width=32,height=1,fg_bg=bw_fg_bg}
+    local key, _ = TextField{parent=net_c_4,x=1,y=12,max_len=64,value=ini_cfg.AuthKey,width=32,height=1,fg_bg=bw_fg_bg}
 
-    local function censor_key(enable) censor(util.trinary(enable, "*", nil)) end
+    local function censor_key(enable) key.censor(util.trinary(enable, "*", nil)) end
 
     local hide_key = CheckBox{parent=net_c_4,x=34,y=12,label="Hide",box_fg_bg=cpair(colors.lightBlue,colors.black),callback=censor_key}
 

graphics/elements/animations/Waiting.lua

@@ -12,10 +12,10 @@ local element = require("graphics.element")
 ---@field fg_bg? cpair foreground/background colors
 ---@field hidden? boolean true to hide on initial draw
 
--- new waiting animation element
+-- Create a new waiting animation element.
 ---@param args waiting_args
----@return graphics_element element, element_id id
-local function waiting(args)
+---@return Waiting element, element_id id
+return function (args)
     local state = 0
     local run_animation = false
 
@@ -23,7 +23,7 @@ local function waiting(args)
     args.height = 3
 
     -- create new graphics element base object
-    local e = element.new(args)
+    local e = element.new(args --[[@as graphics_args]])
 
     local blit_fg = e.fg_bg.blit_fgd
     local blit_bg = e.fg_bg.blit_bkg
@@ -103,7 +103,8 @@ local function waiting(args)
 
     e.start_anim()
 
-    return e.complete()
-end
+    ---@class Waiting:graphics_element
+    local Waiting, id = e.complete()
 
-return waiting
+    return Waiting, id
+end

graphics/elements/controls/App.lua

@@ -20,10 +20,10 @@ local MOUSE_CLICK = core.events.MOUSE_CLICK
 ---@field fg_bg? cpair foreground/background colors
 ---@field hidden? boolean true to hide on initial draw
 
--- new app button
+-- Create a new 'app' style button control element, like on a phone.
 ---@param args app_button_args
----@return graphics_element element, element_id id
-local function app_button(args)
+---@return App element, element_id id
+return function (args)
     element.assert(type(args.text) == "string", "text is a required field")
     element.assert(type(args.title) == "string", "title is a required field")
     element.assert(type(args.callback) == "function", "callback is a required field")
@@ -33,7 +33,7 @@ local function app_button(args)
     args.width = 7
 
     -- create new graphics element base object
-    local e = element.new(args)
+    local e = element.new(args --[[@as graphics_args]])
 
     -- draw the app button
     local function draw()
@@ -123,10 +123,8 @@ local function app_button(args)
         draw()
     end
 
-    -- initial draw
-    e.redraw()
+    ---@class App:graphics_element
+    local App, id = e.complete(true)
 
-    return e.complete()
+    return App, id
 end
-
-return app_button

graphics/elements/controls/CheckBox.lua

@@ -15,10 +15,10 @@ local element = require("graphics.element")
 ---@field fg_bg? cpair foreground/background colors
 ---@field hidden? boolean true to hide on initial draw
 
--- new checkbox control
+-- Create a new checkbox control element.
 ---@param args checkbox_args
----@return graphics_element element, element_id id
-local function checkbox(args)
+---@return CheckBox element, element_id id
+return function (args)
     element.assert(type(args.label) == "string", "label is a required field")
     element.assert(type(args.box_fg_bg) == "table", "box_fg_bg is a required field")
 
@@ -27,7 +27,7 @@ local function checkbox(args)
     args.width = 2 + string.len(args.label)
 
     -- create new graphics element base object
-    local e = element.new(args)
+    local e = element.new(args --[[@as graphics_args]])
 
     e.value = args.default == true
 
@@ -112,10 +112,8 @@ local function checkbox(args)
         draw_label()
     end
 
-    -- initial draw
-    e.redraw()
+    ---@class CheckBox:graphics_element
+    local CheckBox, id = e.complete(true)
 
-    return e.complete()
+    return CheckBox, id
 end
-
-return checkbox

graphics/elements/controls/HazardButton.lua

@@ -18,10 +18,10 @@ local element = require("graphics.element")
 ---@field fg_bg? cpair foreground/background colors
 ---@field hidden? boolean true to hide on initial draw
 
--- new hazard button
+-- Create a new hazard button control element.
 ---@param args hazard_button_args
----@return graphics_element element, element_id id
-local function hazard_button(args)
+---@return HazardButton element, element_id id
+return function (args)
     element.assert(type(args.text) == "string", "text is a required field")
     element.assert(type(args.accent) == "number", "accent is a required field")
     element.assert(type(args.callback) == "function", "callback is a required field")
@@ -32,7 +32,7 @@ local function hazard_button(args)
     local timeout = args.timeout or 1.5
 
     -- create new graphics element base object
-    local e = element.new(args)
+    local e = element.new(args --[[@as graphics_args]])
 
     -- draw border
     ---@param accent color accent color
@@ -198,10 +198,8 @@ local function hazard_button(args)
         draw_border(args.accent)
     end
 
-    -- initial draw
-    e.redraw()
+    ---@class HazardButton:graphics_element
+    local HazardButton, id = e.complete(true)
 
-    return e.complete()
+    return HazardButton, id
 end
-
-return hazard_button

graphics/elements/controls/MultiButton.lua

@@ -25,10 +25,10 @@ local element = require("graphics.element")
 ---@field fg_bg? cpair foreground/background colors
 ---@field hidden? boolean true to hide on initial draw
 
--- new multi button (latch selection, exclusively one button at a time)
+-- Create a new multi button control element (latch selection, exclusively one button at a time).
 ---@param args multi_button_args
----@return graphics_element element, element_id id
-local function multi_button(args)
+---@return MultiButton element, element_id id
+return function (args)
     element.assert(type(args.options) == "table", "options is a required field")
     element.assert(#args.options > 0, "at least one option is required")
     element.assert(type(args.callback) == "function", "callback is a required field")
@@ -52,7 +52,7 @@ local function multi_button(args)
     args.width = (button_width * #args.options) + #args.options + 1
 
     -- create new graphics element base object
-    local e = element.new(args)
+    local e = element.new(args --[[@as graphics_args]])
 
     -- button state (convert nil to 1 if missing)
     e.value = args.default or 1
@@ -126,10 +126,8 @@ local function multi_button(args)
         e.redraw()
     end
 
-    -- initial draw
-    e.redraw()
+    ---@class MultiButton:graphics_element
+    local MultiButton, id = e.complete(true)
 
-    return e.complete()
+    return MultiButton, id
 end
-
-return multi_button

graphics/elements/controls/PushButton.lua

@@ -25,10 +25,10 @@ local KEY_CLICK = core.events.KEY_CLICK
 ---@field fg_bg? cpair foreground/background colors
 ---@field hidden? boolean true to hide on initial draw
 
--- new push button
+-- Create a new push button control element.
 ---@param args push_button_args
----@return graphics_element element, element_id id
-local function push_button(args)
+---@return PushButton element, element_id id
+return function (args)
     element.assert(type(args.text) == "string", "text is a required field")
     element.assert(type(args.callback) == "function", "callback is a required field")
     element.assert(type(args.min_width) == "nil" or (type(args.min_width) == "number" and args.min_width > 0), "min_width must be nil or a number > 0")
@@ -48,7 +48,7 @@ local function push_button(args)
     end
 
     -- create new graphics element base object
-    local e = element.new(args, constrain)
+    local e = element.new(args --[[@as graphics_args]], constrain)
 
     local text_lines = util.strwrap(args.text, e.frame.w)
 
@@ -157,10 +157,8 @@ local function push_button(args)
     e.on_focused = show_pressed
     e.on_unfocused = show_unpressed
 
-    -- initial draw
-    e.redraw()
+    ---@class PushButton:graphics_element
+    local PushButton, id = e.complete(true)
 
-    return e.complete()
+    return PushButton, id
 end
-
-return push_button

graphics/elements/controls/Radio2D.lua

@@ -23,10 +23,10 @@ local element = require("graphics.element")
 ---@field fg_bg? cpair foreground/background colors
 ---@field hidden? boolean true to hide on initial draw
 
--- new 2D radio button list (latch selection, exclusively one color at a time)
+-- Create a new 2D radio button list control element (latch selection, exclusively one color at a time).
 ---@param args radio_2d_args
----@return graphics_element element, element_id id
-local function radio_2d_button(args)
+---@return Radio2D element, element_id id
+return function (args)
     element.assert(type(args.options) == "table" and #args.options > 0, "options should be a table with length >= 1")
     element.assert(util.is_int(args.rows) and util.is_int(args.columns), "rows/columns must be integers")
     element.assert((args.rows * args.columns) >= #args.options, "rows x columns size insufficient for provided number of options")
@@ -70,7 +70,7 @@ local function radio_2d_button(args)
     args.height = max_rows
 
     -- create new graphics element base object
-    local e = element.new(args)
+    local e = element.new(args --[[@as graphics_args]])
 
     -- selected option (convert nil to 1 if missing)
     e.value = args.default or 1
@@ -194,10 +194,8 @@ local function radio_2d_button(args)
     e.on_enabled = e.redraw
     e.on_disabled = e.redraw
 
-    -- initial draw
-    e.redraw()
+    ---@class Radio2D:graphics_element
+    local Radio2D, id = e.complete(true)
 
-    return e.complete()
+    return Radio2D, id
 end
-
-return radio_2d_button

graphics/elements/controls/RadioButton.lua

@@ -21,10 +21,10 @@ local KEY_CLICK = core.events.KEY_CLICK
 ---@field fg_bg? cpair foreground/background colors
 ---@field hidden? boolean true to hide on initial draw
 
--- new radio button list (latch selection, exclusively one button at a time)
+-- Create a new radio button list control element (latch selection, exclusively one button at a time).
 ---@param args radio_button_args
----@return graphics_element element, element_id id
-local function radio_button(args)
+---@return RadioButton element, element_id id
+return function (args)
     element.assert(type(args.options) == "table", "options is a required field")
     element.assert(#args.options > 0, "at least one option is required")
     element.assert(type(args.radio_colors) == "table", "radio_colors is a required field")
@@ -49,7 +49,7 @@ local function radio_button(args)
     args.height = #args.options -- one line per option
 
     -- create new graphics element base object
-    local e = element.new(args)
+    local e = element.new(args --[[@as graphics_args]])
 
     local focused_opt = 1
 
@@ -139,10 +139,8 @@ local function radio_button(args)
     e.on_enabled = e.redraw
     e.on_disabled = e.redraw
 
-    -- initial draw
-    e.redraw()
+    ---@class RadioButton:graphics_element
+    local RadioButton, id = e.complete(true)
 
-    return e.complete()
+    return RadioButton, id
 end
-
-return radio_button

graphics/elements/controls/Sidebar.lua

@@ -17,14 +17,14 @@ local MOUSE_CLICK = core.events.MOUSE_CLICK
 ---@field fg_bg? cpair foreground/background colors
 ---@field hidden? boolean true to hide on initial draw
 
--- new sidebar tab selector
+-- Create a new sidebar tab selector control element.
 ---@param args sidebar_args
----@return graphics_element element, element_id id
-local function sidebar(args)
+---@return Sidebar element, element_id id
+return function (args)
     args.width = 3
 
     -- create new graphics element base object
-    local e = element.new(args)
+    local e = element.new(args --[[@as graphics_args]])
 
     -- default to 1st tab
     e.value = 1
@@ -166,9 +166,8 @@ local function sidebar(args)
     -- element redraw
     e.redraw = draw
 
-    e.redraw()
+    ---@class Sidebar:graphics_element
+    local Sidebar, id = e.complete(true)
 
-    return e.complete()
+    return Sidebar, id
 end
-
-return sidebar

graphics/elements/controls/SpinboxNumeric.lua

@@ -20,10 +20,10 @@ local element = require("graphics.element")
 ---@field fg_bg? cpair foreground/background colors
 ---@field hidden? boolean true to hide on initial draw
 
--- new spinbox control (minimum value is 0)
+-- Create a new spinbox control element (minimum value is 0).
 ---@param args spinbox_args
----@return graphics_element element, element_id id
-local function spinbox(args)
+---@return SpinboxNumeric element, element_id id
+return function (args)
     -- properties
     local digits = {}
     local wn_prec = args.whole_num_precision
@@ -51,7 +51,7 @@ local function spinbox(args)
     args.height = 3
 
     -- create new graphics element base object
-    local e = element.new(args)
+    local e = element.new(args --[[@as graphics_args]])
 
     -- set initial value
     e.value = args.default or 0
@@ -179,10 +179,8 @@ local function spinbox(args)
         draw_arrows(util.trinary(e.enabled, args.arrow_fg_bg.fgd, args.arrow_disable or colors.lightGray))
     end
 
-    -- initial draw
-    e.redraw()
+    ---@class SpinboxNumeric:graphics_element
+    local SpinboxNumeric, id = e.complete(true)
 
-    return e.complete()
+    return SpinboxNumeric, id
 end
-
-return spinbox

graphics/elements/controls/SwitchButton.lua

@@ -17,10 +17,10 @@ local element = require("graphics.element")
 ---@field fg_bg? cpair foreground/background colors
 ---@field hidden? boolean true to hide on initial draw
 
--- new switch button (latch high/low)
+-- Create a new latching switch button control element.
 ---@param args switch_button_args
----@return graphics_element element, element_id id
-local function switch_button(args)
+---@return SwitchButton element, element_id id
+return function (args)
     element.assert(type(args.text) == "string", "text is a required field")
     element.assert(type(args.callback) == "function", "callback is a required field")
     element.assert(type(args.active_fg_bg) == "table", "active_fg_bg is a required field")
@@ -33,7 +33,7 @@ local function switch_button(args)
     args.width = math.max(text_width, args.min_width)
 
     -- create new graphics element base object
-    local e = element.new(args)
+    local e = element.new(args --[[@as graphics_args]])
 
     e.value = args.default or false
 
@@ -72,10 +72,8 @@ local function switch_button(args)
         e.redraw()
     end
 
-    -- initial draw
-    e.redraw()
+    ---@class SwitchButton:graphics_element
+    local SwitchButton, id = e.complete(true)
 
-    return e.complete()
+    return SwitchButton, id
 end
-
-return switch_button

graphics/elements/controls/TabBar.lua

@@ -23,10 +23,10 @@ local element = require("graphics.element")
 ---@field fg_bg? cpair foreground/background colors
 ---@field hidden? boolean true to hide on initial draw
 
--- new tab selector
+-- Create a new tab selector control element.
 ---@param args tabbar_args
----@return graphics_element element, element_id id
-local function tabbar(args)
+---@return TabBar element, element_id id
+return function (args)
     element.assert(type(args.tabs) == "table", "tabs is a required field")
     element.assert(#args.tabs > 0, "at least one tab is required")
     element.assert(type(args.callback) == "function", "callback is a required field")
@@ -46,7 +46,7 @@ local function tabbar(args)
     local button_width = math.max(max_width, args.min_width or 0)
 
     -- create new graphics element base object
-    local e = element.new(args)
+    local e = element.new(args --[[@as graphics_args]])
 
     element.assert(e.frame.w >= (button_width * #args.tabs), "width insufficent to display all tabs")
 
@@ -120,10 +120,8 @@ local function tabbar(args)
         e.redraw()
     end
 
-    -- initial draw
-    e.redraw()
+    ---@class TabBar:graphics_element
+    local TabBar, id = e.complete(true)
 
-    return e.complete()
+    return TabBar, id
 end
-
-return tabbar

graphics/elements/form/NumberField.lua

@@ -27,10 +27,10 @@ local MOUSE_CLICK = core.events.MOUSE_CLICK
 ---@field fg_bg? cpair foreground/background colors
 ---@field hidden? boolean true to hide on initial draw
 
--- new numeric entry field
+-- Create a new numeric entry field.
 ---@param args number_field_args
----@return graphics_element element, element_id id
-local function number_field(args)
+---@return NumberField element, element_id id
+return function (args)
     element.assert(args.max_int_digits == nil or (util.is_int(args.max_int_digits) and args.max_int_digits > 0), "max_int_digits must be an integer greater than zero if supplied")
     element.assert(args.max_frac_digits == nil or (util.is_int(args.max_frac_digits) and args.max_frac_digits > 0), "max_frac_digits must be an integer greater than zero if supplied")
 
@@ -38,7 +38,7 @@ local function number_field(args)
     args.can_focus = true
 
     -- create new graphics element base object
-    local e = element.new(args)
+    local e = element.new(args --[[@as graphics_args]])
 
     local has_decimal = false
 
@@ -195,10 +195,8 @@ local function number_field(args)
     e.on_disabled = ifield.show
     e.redraw = ifield.show
 
-    -- initial draw
-    e.redraw()
+    ---@class NumberField:graphics_element
+    local NumberField, id = e.complete(true)
 
-    return e.complete()
+    return NumberField, id
 end
-
-return number_field

graphics/elements/form/TextField.lua

@@ -19,15 +19,15 @@ local MOUSE_CLICK = core.events.MOUSE_CLICK
 ---@field fg_bg? cpair foreground/background colors
 ---@field hidden? boolean true to hide on initial draw
 
--- new text entry field
+-- Create a new text entry field.
 ---@param args text_field_args
----@return graphics_element element, element_id id, function censor_ctl
-local function text_field(args)
+---@return TextField element, element_id id
+return function (args)
     args.height = 1
     args.can_focus = true
 
     -- create new graphics element base object
-    local e = element.new(args)
+    local e = element.new(args --[[@as graphics_args]])
 
     -- set initial value
     e.value = args.value or ""
@@ -95,11 +95,10 @@ local function text_field(args)
     e.on_disabled = ifield.show
     e.redraw = ifield.show
 
-    -- initial draw
-    e.redraw()
+    ---@class TextField:graphics_element
+    local TextField, id = e.complete(true)
 
-    local elem, id = e.complete()
-    return elem, id, ifield.censor
+    TextField.censor = ifield.censor
+
+    return TextField, id
 end
-
-return text_field

pocket/configure.lua

@@ -282,9 +282,9 @@ local function config_view(display)
     TextBox{parent=net_c_4,x=1,y=6,height=6,text="This enables verifying that messages are authentic, so it is intended for security on multiplayer servers.",fg_bg=g_lg_fg_bg}
 
     TextBox{parent=net_c_4,x=1,y=12,text="Facility Auth Key"}
-    local key, _, censor = TextField{parent=net_c_4,x=1,y=13,max_len=64,value=ini_cfg.AuthKey,width=24,height=1,fg_bg=bw_fg_bg}
+    local key, _ = TextField{parent=net_c_4,x=1,y=13,max_len=64,value=ini_cfg.AuthKey,width=24,height=1,fg_bg=bw_fg_bg}
 
-    local function censor_key(enable) censor(util.trinary(enable, "*", nil)) end
+    local function censor_key(enable) key.censor(util.trinary(enable, "*", nil)) end
 
     -- declare back first so tabbing makes sense visually
     PushButton{parent=net_c_4,x=1,y=15,text="\x1b Back",callback=function()net_pane.set_value(3)end,fg_bg=nav_fg_bg,active_fg_bg=btn_act_fg_bg}

reactor-plc/config/system.lua

@@ -240,9 +240,9 @@ function system.create(tool_ctl, main_pane, cfg_sys, divs, style, exit)
     TextBox{parent=net_c_3,x=1,y=4,height=6,text="This enables verifying that messages are authentic, so it is intended for security on multiplayer servers. All devices on the same network MUST use the same key if any device has a key. This does result in some extra compution (can slow things down).",fg_bg=g_lg_fg_bg}
 
     TextBox{parent=net_c_3,x=1,y=11,text="Facility Auth Key"}
-    local key, _, censor = TextField{parent=net_c_3,x=1,y=12,max_len=64,value=ini_cfg.AuthKey,width=32,height=1,fg_bg=bw_fg_bg}
+    local key, _ = TextField{parent=net_c_3,x=1,y=12,max_len=64,value=ini_cfg.AuthKey,width=32,height=1,fg_bg=bw_fg_bg}
 
-    local function censor_key(enable) censor(util.trinary(enable, "*", nil)) end
+    local function censor_key(enable) key.censor(util.trinary(enable, "*", nil)) end
 
     local hide_key = CheckBox{parent=net_c_3,x=34,y=12,label="Hide",box_fg_bg=cpair(colors.lightBlue,colors.black),callback=censor_key}
 

rtu/configure.lua

@@ -446,9 +446,9 @@ local function config_view(display)
     TextBox{parent=net_c_3,x=1,y=4,height=6,text="This enables verifying that messages are authentic, so it is intended for security on multiplayer servers. All devices on the same network MUST use the same key if any device has a key. This does result in some extra compution (can slow things down).",fg_bg=g_lg_fg_bg}
 
     TextBox{parent=net_c_3,x=1,y=11,text="Facility Auth Key"}
-    local key, _, censor = TextField{parent=net_c_3,x=1,y=12,max_len=64,value=ini_cfg.AuthKey,width=32,height=1,fg_bg=bw_fg_bg}
+    local key, _ = TextField{parent=net_c_3,x=1,y=12,max_len=64,value=ini_cfg.AuthKey,width=32,height=1,fg_bg=bw_fg_bg}
 
-    local function censor_key(enable) censor(tri(enable, "*", nil)) end
+    local function censor_key(enable) key.censor(tri(enable, "*", nil)) end
 
     local hide_key = CheckBox{parent=net_c_3,x=34,y=12,label="Hide",box_fg_bg=cpair(colors.lightBlue,colors.black),callback=censor_key}
 

supervisor/configure.lua

@@ -710,9 +710,9 @@ local function config_view(display)
     TextBox{parent=net_c_4,x=1,y=4,height=6,text="This enables verifying that messages are authentic, so it is intended for security on multiplayer servers. All devices on the same network MUST use the same key if any device has a key. This does result in some extra compution (can slow things down).",fg_bg=g_lg_fg_bg}
 
     TextBox{parent=net_c_4,x=1,y=11,text="Facility Auth Key"}
-    local key, _, censor = TextField{parent=net_c_4,x=1,y=12,max_len=64,value=ini_cfg.AuthKey,width=32,height=1,fg_bg=bw_fg_bg}
+    local key, _ = TextField{parent=net_c_4,x=1,y=12,max_len=64,value=ini_cfg.AuthKey,width=32,height=1,fg_bg=bw_fg_bg}
 
-    local function censor_key(enable) censor(util.trinary(enable, "*", nil)) end
+    local function censor_key(enable) key.censor(util.trinary(enable, "*", nil)) end
 
     local hide_key = CheckBox{parent=net_c_4,x=34,y=12,label="Hide",box_fg_bg=cpair(colors.lightBlue,colors.black),callback=censor_key}