#544 #545 work on graphics

graphics/elements/appmultipane.lua

@@ -24,15 +24,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 app multipane element
+-- Create a new app multipane container element.
 ---@nodiscard
 ---@param args app_multipane_args
----@return graphics_element element, element_id id
-local function multipane(args)
+---@return AppMultiPane element, element_id id
+return function (args)
     element.assert(type(args.panes) == "table", "panes is a required field")
 
     -- create new graphics element base object
-    local e = element.new(args)
+    local e = element.new(args --[[@as graphics_args]])
 
     e.value = 1
 
@@ -100,10 +100,8 @@ local function multipane(args)
         end
     end
 
-    -- initial draw
-    e.redraw()
+    ---@class AppMultiPane:graphics_element
+    local AppMultiPane, id = e.complete(true)
 
-    return e.complete()
+    return AppMultiPane, id
 end
-
-return multipane

graphics/elements/colormap.lua

@@ -9,10 +9,10 @@ local element = require("graphics.element")
 ---@field y? integer auto incremented if omitted
 ---@field hidden? boolean true to hide on initial draw
 
--- new color map
+-- Create a horizontal reference color map. Primarily used for tuning custom colors.
 ---@param args colormap_args
----@return graphics_element element, element_id id
-local function colormap(args)
+---@return ColorMap element, element_id id
+return function (args)
     local bkg = "008877FFCCEE114455DD9933BBAA2266"
     local spaces = string.rep(" ", 32)
 
@@ -20,7 +20,7 @@ local function colormap(args)
     args.height = 1
 
     -- create new graphics element base object
-    local e = element.new(args)
+    local e = element.new(args --[[@as graphics_args]])
 
     -- draw color map
     function e.redraw()
@@ -28,10 +28,8 @@ local function colormap(args)
         e.w_blit(spaces, bkg, bkg)
     end
 
-    -- initial draw
-    e.redraw()
+    ---@class ColorMap:graphics_element
+    local ColorMap, id = e.complete(true)
 
-    return e.complete()
+    return ColorMap, id
 end
-
-return colormap

graphics/elements/displaybox.lua

@@ -13,13 +13,16 @@ local element = require("graphics.element")
 ---@field fg_bg? cpair foreground/background colors
 ---@field hidden? boolean true to hide on initial draw
 
--- new root display box
+-- Create a root display box.
 ---@nodiscard
 ---@param args displaybox_args
----@return graphics_element element, element_id id
-local function displaybox(args)
+---@return DisplayBox element, element_id id
+return function (args)
     -- create new graphics element base object
-    return element.new(args).complete()
-end
+    local e = element.new(args --[[@as graphics_args]])
 
-return displaybox
+    ---@class DisplayBox:graphics_element
+    local DisplayBox, id = e.complete()
+
+    return DisplayBox, id
+end

graphics/elements/div.lua

@@ -13,13 +13,16 @@ local element = require("graphics.element")
 ---@field fg_bg? cpair foreground/background colors
 ---@field hidden? boolean true to hide on initial draw
 
--- new div element
+-- Create a new div container element.
 ---@nodiscard
 ---@param args div_args
----@return graphics_element element, element_id id
-local function div(args)
+---@return Div element, element_id id
+return function (args)
     -- create new graphics element base object
-    return element.new(args).complete()
-end
+    local e = element.new(args --[[@as graphics_args]])
 
-return div
+    ---@class Div:graphics_element
+    local Div, id = e.complete()
+
+    return Div, id
+end

graphics/elements/listbox.lua

@@ -30,15 +30,15 @@ local MOUSE_CLICK = core.events.MOUSE_CLICK
 ---@field y integer y position
 ---@field h integer element height
 
--- new listbox element
+-- Create a new scrollable listbox container element.
 ---@nodiscard
 ---@param args listbox_args
----@return graphics_element element, element_id id
-local function listbox(args)
+---@return ListBox element, element_id id
+return function (args)
     args.can_focus = true
 
     -- create new graphics element base object
-    local e = element.new(args)
+    local e = element.new(args --[[@as graphics_args]])
 
     -- create content window for child elements
     local scroll_frame = window.create(e.window, 1, 1, e.frame.w - 1, args.scroll_height, false)
@@ -339,10 +339,8 @@ local function listbox(args)
         draw_bar()
     end
 
-    -- initial draw
-    e.redraw()
+    ---@class ListBox:graphics_element
+    local ListBox, id = e.complete(true)
 
-    return e.complete()
+    return ListBox, id
 end
-
-return listbox

graphics/elements/multipane.lua

@@ -14,15 +14,15 @@ local element = require("graphics.element")
 ---@field fg_bg? cpair foreground/background colors
 ---@field hidden? boolean true to hide on initial draw
 
--- new multipane element
+-- Create a new multipane container element.
 ---@nodiscard
 ---@param args multipane_args
----@return graphics_element element, element_id id
-local function multipane(args)
+---@return MultiPane element, element_id id
+return function (args)
     element.assert(type(args.panes) == "table", "panes is a required field")
 
     -- create new graphics element base object
-    local e = element.new(args)
+    local e = element.new(args --[[@as graphics_args]])
 
     e.value = 1
 
@@ -41,10 +41,8 @@ local function multipane(args)
         end
     end
 
-    -- initial draw
-    e.redraw()
+    ---@class MultiPane:graphics_element
+    local MultiPane, id = e.complete(true)
 
-    return e.complete()
+    return MultiPane, id
 end
-
-return multipane

graphics/elements/pipenet.lua

@@ -20,10 +20,10 @@ local element = require("graphics.element")
 ---@field fg string foreground blit
 ---@field bg string background blit
 
--- new pipe network
+-- Create a pipe network diagram.
 ---@param args pipenet_args
----@return graphics_element element, element_id id
-local function pipenet(args)
+---@return PipeNetwork element, element_id id
+return function (args)
     element.assert(type(args.pipes) == "table", "pipes is a required field")
 
     args.width = 0
@@ -47,7 +47,7 @@ local function pipenet(args)
     end
 
     -- create new graphics element base object
-    local e = element.new(args)
+    local e = element.new(args --[[@as graphics_args]])
 
     -- determine if there are any thin pipes involved
     local any_thin = false
@@ -322,10 +322,8 @@ local function pipenet(args)
         if any_thin then map_draw() else vector_draw() end
     end
 
-    -- initial draw
-    e.redraw()
+    ---@class PipeNetwork:graphics_element
+    local PipeNetwork, id = e.complete(true)
 
-    return e.complete()
+    return PipeNetwork, id
 end
-
-return pipenet

graphics/elements/rectangle.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 rectangle
+-- Create a new rectangle container element.
 ---@param args rectangle_args
----@return graphics_element element, element_id id
-local function rectangle(args)
+---@return Rectangle element, element_id id
+return function (args)
     element.assert(args.border ~= nil or args.thin ~= true, "thin requires border to be provided")
 
     -- if thin, then width will always need to be 1
@@ -45,7 +45,7 @@ local function rectangle(args)
     end
 
     -- create new graphics element base object
-    local e = element.new(args, nil, offset_x, offset_y)
+    local e = element.new(args --[[@as graphics_args]], nil, offset_x, offset_y)
 
     -- create content window for child elements
     e.content_window = window.create(e.window, 1 + offset_x, 1 + offset_y, e.frame.w - (2 * offset_x), e.frame.h - (2 * offset_y))
@@ -191,7 +191,8 @@ local function rectangle(args)
         e.redraw()
     end
 
-    return e.complete()
-end
+    ---@class Rectangle:graphics_element
+    local Rectangle, id = e.complete()
 
-return rectangle
+    return Rectangle, id
+end

graphics/elements/textbox.lua

@@ -23,8 +23,8 @@ local ALIGN = core.ALIGN
 
 -- new text box
 ---@param args textbox_args
----@return graphics_element element, element_id id
-local function textbox(args)
+---@return TextBox element, element_id id
+return function (args)
     element.assert(type(args.text) == "string", "text is a required field")
 
     if args.anchor == true then args.can_focus = true end
@@ -42,7 +42,7 @@ local function textbox(args)
     end
 
     -- create new graphics element base object
-    local e = element.new(args, constrain)
+    local e = element.new(args --[[@as graphics_args]], constrain)
 
     e.value = args.text
 
@@ -82,10 +82,8 @@ local function textbox(args)
         e.redraw()
     end
 
-    -- initial draw
-    e.redraw()
+    ---@class TextBox:graphics_element
+    local TextBox, id = e.complete(true)
 
-    return e.complete()
+    return TextBox, id
 end
-
-return textbox

graphics/elements/tiling.lua

@@ -20,12 +20,12 @@ local element = require("graphics.element")
 
 -- new tiling box
 ---@param args tiling_args
----@return graphics_element element, element_id id
-local function tiling(args)
+---@return Tiling element, element_id id
+return function (args)
     element.assert(type(args.fill_c) == "table", "fill_c is a required field")
 
     -- create new graphics element base object
-    local e = element.new(args)
+    local e = element.new(args --[[@as graphics_args]])
 
     local fill_a = args.fill_c.blit_a
     local fill_b = args.fill_c.blit_b
@@ -52,7 +52,7 @@ local function tiling(args)
     element.assert(start_x <= inner_width, "start_x > inner_width")
     element.assert(start_y <= inner_height, "start_y > inner_height")
 
-    -- draw tiling box
+    -- draw the tiling box
     function e.redraw()
         local alternator = true
 
@@ -86,10 +86,8 @@ local function tiling(args)
         end
     end
 
-    -- initial draw
-    e.redraw()
+    ---@class Tiling:graphics_element
+    local Tiling, id = e.complete(true)
 
-    return e.complete()
+    return Tiling, id
 end
-
-return tiling