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

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