#544 #545 updates to graphics indicator elements

graphics/elements/indicators/AlarmLight.lua

@@ -20,11 +20,11 @@ local flasher = require("graphics.flasher")
 ---@field fg_bg? cpair foreground/background colors
 ---@field hidden? boolean true to hide on initial draw
 
--- new alarm indicator light
+-- Create a new alarm indicator light element.
 ---@nodiscard
 ---@param args alarm_indicator_light
----@return graphics_element element, element_id id
-local function alarm_indicator_light(args)
+---@return AlarmLight element, element_id id
+return function (args)
     element.assert(type(args.label) == "string", "label is a required field")
     element.assert(type(args.c1) == "number", "c1 is a required field")
     element.assert(type(args.c2) == "number", "c2 is a required field")
@@ -49,7 +49,7 @@ local function alarm_indicator_light(args)
     local c3 = colors.toBlit(args.c3)
 
     -- create new graphics element base object
-    local e = element.new(args)
+    local e = element.new(args --[[@as graphics_args]])
 
     e.value = 1
 
@@ -113,10 +113,8 @@ local function alarm_indicator_light(args)
         e.w_write(args.label)
     end
 
-    -- initial draw
-    e.redraw()
+    ---@class AlarmLight:graphics_element
+    local AlarmLight, id = e.complete(true)
 
-    return e.complete()
+    return AlarmLight, id
 end
-
-return alarm_indicator_light

graphics/elements/indicators/CoreMap.lua

@@ -13,11 +13,11 @@ local element = require("graphics.element")
 ---@field x? integer 1 if omitted
 ---@field y? integer auto incremented if omitted
 
--- new core map box
+-- Create a new core map box element.
 ---@nodiscard
 ---@param args core_map_args
----@return graphics_element element, element_id id
-local function core_map(args)
+---@return CoreMap element, element_id id
+return function (args)
     element.assert(util.is_int(args.reactor_l), "reactor_l is a required field")
     element.assert(util.is_int(args.reactor_w), "reactor_w is a required field")
 
@@ -29,7 +29,7 @@ local function core_map(args)
     args.fg_bg = core.cpair(args.parent.get_fg_bg().fgd, colors.gray)
 
     -- create new graphics element base object
-    local e = element.new(args)
+    local e = element.new(args --[[@as graphics_args]])
 
     e.value = 0
 
@@ -165,10 +165,8 @@ local function core_map(args)
         draw_core(e.value)
     end
 
-    -- initial draw
-    e.redraw()
+    ---@class CoreMap:graphics_element
+    local CoreMap, id = e.complete(true)
 
-    return e.complete()
+    return CoreMap, id
 end
-
-return core_map

graphics/elements/indicators/DataIndicator.lua

@@ -19,11 +19,11 @@ local element = require("graphics.element")
 ---@field fg_bg? cpair foreground/background colors
 ---@field hidden? boolean true to hide on initial draw
 
--- new data indicator
+-- Create new data indicator element.
 ---@nodiscard
 ---@param args data_indicator_args
----@return graphics_element element, element_id id
-local function data(args)
+---@return DataIndicator element, element_id id
+return function (args)
     element.assert(type(args.label) == "string", "label is a required field")
     element.assert(type(args.format) == "string", "format is a required field")
     element.assert(args.value ~= nil, "value is a required field")
@@ -32,7 +32,7 @@ local function data(args)
     args.height = 1
 
     -- create new graphics element base object
-    local e = element.new(args)
+    local e = element.new(args --[[@as graphics_args]])
 
     e.value = args.value
 
@@ -94,10 +94,8 @@ local function data(args)
         e.on_update(e.value)
     end
 
-    -- initial draw
-    e.redraw()
+    ---@class DataIndicator:graphics_element
+    local DataIndicator, id = e.complete(true)
 
-    return e.complete()
+    return DataIndicator, id
 end
-
-return data

graphics/elements/indicators/HorizontalBar.lua

@@ -17,13 +17,13 @@ local element = require("graphics.element")
 ---@field fg_bg? cpair foreground/background colors
 ---@field hidden? boolean true to hide on initial draw
 
--- new horizontal bar
+-- Create a new horizontal fill bar indicator element.
 ---@nodiscard
 ---@param args hbar_args
 ---@return graphics_element element, element_id id
-local function hbar(args)
+return function (args)
     -- create new graphics element base object
-    local e = element.new(args)
+    local e = element.new(args --[[@as graphics_args]])
 
     e.value = 0.0
 
@@ -119,10 +119,8 @@ local function hbar(args)
         e.on_update(e.value)
     end
 
-    -- initial draw
-    e.redraw()
+    ---@class HorizontalBar:graphics_element
+    local HorizontalBar, id = e.complete(true)
 
-    return e.complete()
+    return HorizontalBar, id
 end
-
-return hbar

graphics/elements/indicators/IconIndicator.lua

@@ -18,11 +18,11 @@ local element = require("graphics.element")
 ---@field fg_bg? cpair foreground/background colors
 ---@field hidden? boolean true to hide on initial draw
 
--- new icon indicator
+-- Create a new icon indicator element.
 ---@nodiscard
 ---@param args icon_indicator_args
----@return graphics_element element, element_id id
-local function icon(args)
+---@return IconIndicator element, element_id id
+return function (args)
     element.assert(type(args.label) == "string", "label is a required field")
     element.assert(type(args.states) == "table", "states is a required field")
 
@@ -30,7 +30,7 @@ local function icon(args)
     args.width = math.max(args.min_label_width or 1, string.len(args.label)) + 4
 
     -- create new graphics element base object
-    local e = element.new(args)
+    local e = element.new(args --[[@as graphics_args]])
 
     e.value = args.value or 1
     if e.value == true then e.value = 2 end
@@ -71,10 +71,8 @@ local function icon(args)
         e.on_update(e.value)
     end
 
-    -- initial draw
-    e.redraw()
+    ---@class IconIndicator:graphics_element
+    local IconIndicator, id = e.complete(true)
 
-    return e.complete()
+    return IconIndicator, id
 end
-
-return icon

graphics/elements/indicators/IndicatorLight.lua

@@ -18,11 +18,11 @@ local flasher = require("graphics.flasher")
 ---@field fg_bg? cpair foreground/background colors
 ---@field hidden? boolean true to hide on initial draw
 
--- new indicator light
+-- Create a new indicator light element.
 ---@nodiscard
 ---@param args indicator_light_args
----@return graphics_element element, element_id id
-local function indicator_light(args)
+---@return IndicatorLight element, element_id id
+return function (args)
     element.assert(type(args.label) == "string", "label is a required field")
     element.assert(type(args.colors) == "table", "colors is a required field")
 
@@ -36,7 +36,7 @@ local function indicator_light(args)
     local flash_on = true
 
     -- create new graphics element base object
-    local e = element.new(args)
+    local e = element.new(args --[[@as graphics_args]])
 
     e.value = false
 
@@ -93,10 +93,8 @@ local function indicator_light(args)
         e.w_write(args.label)
     end
 
-    -- initial draw
-    e.redraw()
+    ---@class IndicatorLight:graphics_element
+    local IndicatorLight, id = e.complete(true)
 
-    return e.complete()
+    return IndicatorLight, id
 end
-
-return indicator_light

graphics/elements/indicators/LED.lua

@@ -18,11 +18,11 @@ local flasher = require("graphics.flasher")
 ---@field fg_bg? cpair foreground/background colors
 ---@field hidden? boolean true to hide on initial draw
 
--- new indicator LED
+-- Create a new indicator LED element.
 ---@nodiscard
 ---@param args indicator_led_args
----@return graphics_element element, element_id id
-local function indicator_led(args)
+---@return LED element, element_id id
+return function (args)
     element.assert(type(args.label) == "string", "label is a required field")
     element.assert(type(args.colors) == "table", "colors is a required field")
 
@@ -36,7 +36,7 @@ local function indicator_led(args)
     local flash_on = true
 
     -- create new graphics element base object
-    local e = element.new(args)
+    local e = element.new(args --[[@as graphics_args]])
 
     e.value = false
 
@@ -95,10 +95,8 @@ local function indicator_led(args)
         end
     end
 
-    -- initial draw
-    e.redraw()
+    ---@class LED:graphics_element
+    local LED, id = e.complete(true)
 
-    return e.complete()
+    return LED, id
 end
-
-return indicator_led

graphics/elements/indicators/LEDPair.lua

@@ -20,11 +20,12 @@ local flasher = require("graphics.flasher")
 ---@field fg_bg? cpair foreground/background colors
 ---@field hidden? boolean true to hide on initial draw
 
--- new dual LED indicator light
+-- Create a new three-state LED indicator light. Two "active" states (colors c1 and c2) and an inactive state (off).<br>
+-- Values: 1 = off, 2 = c1, 3 = c2
 ---@nodiscard
 ---@param args indicator_led_pair_args
----@return graphics_element element, element_id id
-local function indicator_led_pair(args)
+---@return LEDPair element, element_id id
+return function (args)
     element.assert(type(args.label) == "string", "label is a required field")
     element.assert(type(args.off) == "number", "off is a required field")
     element.assert(type(args.c1) == "number", "c1 is a required field")
@@ -44,7 +45,7 @@ local function indicator_led_pair(args)
     local c2 = colors.toBlit(args.c2)
 
     -- create new graphics element base object
-    local e = element.new(args)
+    local e = element.new(args --[[@as graphics_args]])
 
     e.value = 1
 
@@ -104,10 +105,8 @@ local function indicator_led_pair(args)
         end
     end
 
-    -- initial draw
-    e.redraw()
+    ---@class LEDPair:graphics_element
+    local LEDPair, id = e.complete(true)
 
-    return e.complete()
+    return LEDPair, id
 end
-
-return indicator_led_pair

graphics/elements/indicators/PowerIndicator.lua

@@ -19,11 +19,11 @@ local element = require("graphics.element")
 ---@field fg_bg? cpair foreground/background colors
 ---@field hidden? boolean true to hide on initial draw
 
--- new power indicator
+-- Create a new power indicator. Variant of a data indicator with dynamic energy units.
 ---@nodiscard
 ---@param args power_indicator_args
----@return graphics_element element, element_id id
-local function power(args)
+---@return PowerIndicator element, element_id id
+return function (args)
     element.assert(type(args.label) == "string", "label is a required field")
     element.assert(type(args.unit) == "string", "unit is a required field")
     element.assert(type(args.value) == "number", "value is a required field")
@@ -32,7 +32,7 @@ local function power(args)
     args.height = 1
 
     -- create new graphics element base object
-    local e = element.new(args)
+    local e = element.new(args --[[@as graphics_args]])
 
     e.value = args.value
 
@@ -82,10 +82,8 @@ local function power(args)
         e.on_update(e.value)
     end
 
-    -- initial draw
-    e.redraw()
+    ---@class PowerIndicator:graphics_element
+    local PowerIndicator, id = e.complete(true)
 
-    return e.complete()
+    return PowerIndicator, id
 end
-
-return power

graphics/elements/indicators/RGBLED.lua

@@ -13,11 +13,11 @@ local element = require("graphics.element")
 ---@field fg_bg? cpair foreground/background colors
 ---@field hidden? boolean true to hide on initial draw
 
--- new RGB LED indicator light
+-- Create a new RGB LED indicator light element.
 ---@nodiscard
 ---@param args indicator_led_rgb_args
----@return graphics_element element, element_id id
-local function indicator_led_rgb(args)
+---@return RGBLED element, element_id id
+return function (args)
     element.assert(type(args.label) == "string", "label is a required field")
     element.assert(type(args.colors) == "table", "colors is a required field")
 
@@ -25,7 +25,7 @@ local function indicator_led_rgb(args)
     args.width = math.max(args.min_label_width or 0, string.len(args.label)) + 2
 
     -- create new graphics element base object
-    local e = element.new(args)
+    local e = element.new(args --[[@as graphics_args]])
 
     e.value = 1
 
@@ -52,10 +52,8 @@ local function indicator_led_rgb(args)
         end
     end
 
-    -- initial draw
-    e.redraw()
+    ---@class RGBLED:graphics_element
+    local RGBLED, id = e.complete(true)
 
-    return e.complete()
+    return RGBLED, id
 end
-
-return indicator_led_rgb

graphics/elements/indicators/RadIndicator.lua

@@ -19,11 +19,11 @@ local element = require("graphics.element")
 ---@field fg_bg? cpair foreground/background colors
 ---@field hidden? boolean true to hide on initial draw
 
--- new radiation indicator
+-- Create a new radiation indicator element. Variant of a data indicator using dynamic Sievert unit precision.
 ---@nodiscard
 ---@param args rad_indicator_args
----@return graphics_element element, element_id id
-local function rad(args)
+---@return RadIndicator element, element_id id
+return function (args)
     element.assert(type(args.label) == "string", "label is a required field")
     element.assert(type(args.format) == "string", "format is a required field")
     element.assert(util.is_int(args.width), "width is a required field")
@@ -31,7 +31,7 @@ local function rad(args)
     args.height = 1
 
     -- create new graphics element base object
-    local e = element.new(args)
+    local e = element.new(args --[[@as graphics_args]])
 
     e.value = args.value or types.new_zero_radiation_reading()
 
@@ -83,10 +83,8 @@ local function rad(args)
         e.on_update(e.value)
     end
 
-    -- initial draw
-    e.redraw()
+    ---@class RadIndicator:graphics_element
+    local RadIndicator, id = e.complete(true)
 
-    return e.complete()
+    return RadIndicator, id
 end
-
-return rad

graphics/elements/indicators/SignalBar.lua

@@ -15,16 +15,16 @@ local element = require("graphics.element")
 ---@field fg_bg? cpair foreground/background colors (foreground is used for high signal quality)
 ---@field hidden? boolean true to hide on initial draw
 
--- new signal bar
+-- Create a new signal bar indicator element.
 ---@nodiscard
 ---@param args signal_bar_args
----@return graphics_element element, element_id id
-local function signal_bar(args)
+---@return SignalBar element, element_id id
+return function (args)
     args.height = 1
     args.width = util.trinary(args.compact, 1, 2)
 
     -- create new graphics element base object
-    local e = element.new(args)
+    local e = element.new(args --[[@as graphics_args]])
 
     e.value = 0
 
@@ -76,10 +76,8 @@ local function signal_bar(args)
         end
     end
 
-    -- initial draw
-    e.redraw()
+    ---@class SignalBar:graphics_element
+    local SignalBar, id = e.complete(true)
 
-    return e.complete()
+    return SignalBar, id
 end
-
-return signal_bar

graphics/elements/indicators/StateIndicator.lua

@@ -20,11 +20,11 @@ local element = require("graphics.element")
 ---@field fg_bg? cpair foreground/background colors
 ---@field hidden? boolean true to hide on initial draw
 
--- new state indicator
+-- Create a new state indicator element.
 ---@nodiscard
 ---@param args state_indicator_args
----@return graphics_element element, element_id id
-local function state_indicator(args)
+---@return StateIndicator element, element_id id
+return function (args)
     element.assert(type(args.states) == "table", "states is a required field")
 
     if util.is_int(args.height) then
@@ -52,7 +52,7 @@ local function state_indicator(args)
     end
 
     -- create new graphics element base object
-    local e = element.new(args)
+    local e = element.new(args --[[@as graphics_args]])
 
     e.value = args.value or 1
 
@@ -74,10 +74,8 @@ local function state_indicator(args)
     ---@param val integer indicator state
     function e.set_value(val) e.on_update(val) end
 
-    -- initial draw
-    e.redraw()
+    ---@class StateIndicator:graphics_element
+    local StateIndicator, id = e.complete(true)
 
-    return e.complete()
+    return StateIndicator, id
 end
-
-return state_indicator

graphics/elements/indicators/TriIndicatorLight.lua

@@ -20,11 +20,11 @@ local flasher = require("graphics.flasher")
 ---@field fg_bg? cpair foreground/background colors
 ---@field hidden? boolean true to hide on initial draw
 
--- new tri-state indicator light
+-- Create a new tri-state indicator light element.
 ---@nodiscard
 ---@param args tristate_indicator_light_args
----@return graphics_element element, element_id id
-local function tristate_indicator_light(args)
+---@return TriIndicatorLight element, element_id id
+return function (args)
     element.assert(type(args.label) == "string", "label is a required field")
     element.assert(type(args.c1) == "number", "c1 is a required field")
     element.assert(type(args.c2) == "number", "c2 is a required field")
@@ -38,7 +38,7 @@ local function tristate_indicator_light(args)
     args.width = math.max(args.min_label_width or 1, string.len(args.label)) + 2
 
     -- create new graphics element base object
-    local e = element.new(args)
+    local e = element.new(args --[[@as graphics_args]])
 
     e.value = 1
 
@@ -102,10 +102,8 @@ local function tristate_indicator_light(args)
         e.w_write(args.label)
     end
 
-    -- initial draw
-    e.redraw()
+    ---@class TriIndicatorLight:graphics_element
+    local TriIndicatorLight, id = e.complete(true)
 
-    return e.complete()
+    return TriIndicatorLight, id
 end
-
-return tristate_indicator_light

graphics/elements/indicators/VerticalBar.lua

@@ -15,13 +15,13 @@ local element = require("graphics.element")
 ---@field fg_bg? cpair foreground/background colors
 ---@field hidden? boolean true to hide on initial draw
 
--- new vertical bar
+-- Create a new vertical fill bar indicator element.
 ---@nodiscard
 ---@param args vbar_args
----@return graphics_element element, element_id id
-local function vbar(args)
+---@return VerticalBar element, element_id id
+return function (args)
     -- create new graphics element base object
-    local e = element.new(args)
+    local e = element.new(args --[[@as graphics_args]])
 
     e.value = 0.0
 
@@ -98,10 +98,8 @@ local function vbar(args)
         e.redraw()
     end
 
-    -- initial draw
-    e.redraw()
+    ---@class VerticalBar:graphics_element
+    local VerticalBar, id = e.complete(true)
 
-    return e.complete()
+    return VerticalBar, id
 end
-
-return vbar