From 91ed7f50f5176bb392d67d14e7337ed2b40427b3 Mon Sep 17 00:00:00 2001 From: Andrea Date: Mon, 12 Sep 2022 09:34:46 +0200 Subject: [PATCH] [*] add documentation --- .gitignore | 6 ++++-- button.lua | 23 +++++++++++++++++++++++ checkbox.lua | 22 ++++++++++++++++++++++ choice.lua | 21 +++++++++++++++++++++ columns.lua | 12 ++++++++++-- config.ld | 35 +++++++++++++++++++++++++++++++++++ crush.lua | 22 ++++++++++++++-------- input.lua | 19 +++++++++++++++++++ label.lua | 16 ++++++++++++++++ layout.lua | 28 ++++++++++++++++++++++++---- rows.lua | 8 ++++++++ slider.lua | 21 +++++++++++++++++++++ spacer.lua | 11 +++++++++++ theme.lua | 24 ++++++++++++++++++++++++ ui.lua | 22 ++++++++++++++++++++-- widget.lua | 18 ++++++++++++++++++ 16 files changed, 290 insertions(+), 18 deletions(-) create mode 100644 config.ld diff --git a/.gitignore b/.gitignore index 387c892..0368e87 100644 --- a/.gitignore +++ b/.gitignore @@ -40,9 +40,11 @@ luac.out *.x86_64 *.hex +# VS Code cruft +.vscode/ +# crush output directory +lib/ # ldoc output directory doc/ -# crush library directory -lib/ diff --git a/button.lua b/button.lua index 7161838..6a64cbb 100644 --- a/button.lua +++ b/button.lua @@ -1,3 +1,13 @@ +--- Implements a clickable button widget +-- +-- @classmod yui.Button +-- @copyright 2022, The DoubleFourteen Code Forge +-- @author Lorenzo Cogotti, Andrea Pasquini +-- +-- +--- Button widget receives the following callbacks: @{yui.Widget.WidgetCallbacks|onEnter}(), @{yui.Widget.WidgetCallbacks|onHit}(), @{yui.Widget.WidgetCallbacks|onLeave}(). + + local BASE = (...):gsub('button$', '') local Widget = require(BASE..'widget') @@ -9,7 +19,20 @@ local T = require('lib.moonspeak').translate local Button = setmetatable({}, Widget) Button.__index = Button +--- Attributes accepted by the @{Button} widget beyond the standard @{yui.Widget.WidgetAttributes|attributes} +-- and @{yui.Widget.WidgetCallbacks|callbacks}. +-- +-- and @{yui.Widget.WidgetCallbacks|callbacks}. +-- @field text (string) text displayed inside the button +-- @field[opt='center'] valign (string) vertical alignment 'top', 'bottom', 'center' +-- @field[opt='center'] align (string) horizontal alignment, 'left', 'center', 'right' +-- @field cornerRadius (number) radius for rounded corners +-- @field notranslate (boolean) don't translate text +-- @table ButtonAttributes + +--- Button constructor +-- @param args (@{ButtonAttributes}) widget attributes function Button.new(args) local self = setmetatable(args, Button) diff --git a/checkbox.lua b/checkbox.lua index 07bc228..1d1b513 100644 --- a/checkbox.lua +++ b/checkbox.lua @@ -1,3 +1,11 @@ +--- Implements a checkbox widget with a binary tick selection +-- +-- @classmod yui.Checkbox +-- @copyright 2022, The DoubleFourteen Code Forge +-- @author Lorenzo Cogotti, Andrea Pasquini +-- +--- Checkbox widget receives the following callbacks: @{yui.Widget.WidgetCallbacks|onEnter}(), @{yui.Widget.WidgetCallbacks|onChange}(), @{yui.Widget.WidgetCallbacks|onLeave}(). + local BASE = (...):gsub('checkbox$', '') local Widget = require(BASE..'widget') @@ -10,6 +18,20 @@ local Checkbox = setmetatable({}, Widget) Checkbox.__index = Checkbox +--- Attributes accepted by the @{Checkbox} widget beyond the standard @{yui.Widget.WidgetAttributes|attributes} +-- and @{yui.Widget.WidgetCallbacks|callbacks}. +-- +-- @field checked (boolean) to set it checked by default +-- @field text (string) text displayed inside the Checkbox +-- @field[opt='center'] valign (string) vertical alignment 'top', 'bottom', 'center' +-- @field[opt='center'] align (string) horizontal alignment, 'left', 'center', 'right' +-- @field cornerRadius (number) radius for rounded corners +-- @field notranslate (boolean) don't translate text +-- @table CheckboxAttributes + + +--- Checkbox constructor +-- @param args (@{CheckboxAttributes}) widget attributes function Checkbox.new(args) local self = setmetatable(args, Checkbox) diff --git a/choice.lua b/choice.lua index a8848c2..9806fbe 100644 --- a/choice.lua +++ b/choice.lua @@ -1,3 +1,11 @@ +--- Implements a multi-choice widget +-- +-- @classmod yui.Choice +-- @copyright 2022, The DoubleFourteen Code Forge +-- @author Lorenzo Cogotti, Andrea Pasquini +-- +--- Multi-choice widget receives the following callbacks: @{yui.Widget.WidgetCallbacks|onEnter}(), @{yui.Widget.WidgetCallbacks|onChange}(), @{yui.Widget.WidgetCallbacks|onLeave}(). + local BASE = (...):gsub('choice$', '') local Widget = require(BASE..'widget') @@ -11,7 +19,20 @@ local Choice = setmetatable({ }, Widget) Choice.__index = Choice +--- Attributes accepted by the @{Choice} widget beyond the standard @{yui.Widget.WidgetAttributes|attributes} +-- and @{yui.Widget.WidgetCallbacks|callbacks}. +-- +-- @field choices (table) available choices list +-- @field nowrap (boolean) disable choices wrapping +-- @field[opt='center'] valign (string) vertical alignment 'top', 'bottom', 'center' +-- @field[opt='center'] align (string) horizontal alignment, 'left', 'center', 'right' +-- @field cornerRadius (number) radius for rounded corners +-- @field notranslate (boolean) don't translate text +-- @table ChoiceAttributes + +--- Choice constructor +-- @param args (@{ChoiceAttributes}) widget attributes function Choice.new(args) local self = setmetatable(args, Choice) diff --git a/columns.lua b/columns.lua index e2ba5bc..25115a4 100644 --- a/columns.lua +++ b/columns.lua @@ -1,9 +1,17 @@ +--- Columns layout for widgets +-- +-- @classmod yui.Columns +-- @copyright 2022, The DoubleFourteen Code Forge +-- @author Lorenzo Cogotti, Andrea Pasquini +-- +--- A widget container, lays down its child widgets into multiple columns. + local BASE = (...):gsub('columns$', '') local Layout = require(BASE..'layout') --- Advance position to next column, --- given current position, widget dimensions and padding. +-- Advance position to next column +-- given current position, widget dimensions and padding local function columnadvance(x,y, ww,wh, padding) return x + ww + padding, y end diff --git a/config.ld b/config.ld new file mode 100644 index 0000000..9702056 --- /dev/null +++ b/config.ld @@ -0,0 +1,35 @@ +project = 'Yui' +title = 'Yui docs' +description = 'Yui is Yet another User Interface library.' +format = 'markdown' +full_description = [[ +The Yui library assists in designing menu screens, pause menus, HUDs, and such. + +Source code: @{https://git.doublefourteen.io/lua/yui} + +Examples: @{https://git.doublefourteen.io/lua/yui-examples} + +Pictures: @{https://git.doublefourteen.io/lua/yui-examples/src/branch/master/pics} + + +The main features: grid layout, widget navigation with keyboard/joystick buttons, support for managing custom +input devices (keyboard, mouse, touch, gamepad), and an easily extensible widget collection. The user interface is +described with a declarative approach: the layout is defined once, and events are handled in the callbacks. + +Integrated support for localization was achieved through the use of another library: moonspeak. +(@{https://git.doublefourteen.io/lua/moonspeak}) + +Most of the widget and theme rendering code are re-used from Matthias Richter's SUIT library. +(@{https://github.com/vrld/suit}) + +]] +file = {'', exclude = {'crush.lua'}} + + + +custom_see_handler('^https://(.+)$', function(root) + local url ='https://'..root + + return url, + url + end) diff --git a/crush.lua b/crush.lua index 5777248..22b3ee1 100644 --- a/crush.lua +++ b/crush.lua @@ -1,12 +1,13 @@ ---- crush - The uncomplicated dependency system for LÖVE. +--- Crush +-- +-- The uncomplicated dependency system for LÖVE. +-- +-- @module crush +-- @copyright 2022 The DoubleFourteen Code Forge +-- @author Lorenzo Cogotti +-- @author Andrea Pasquini +-- -- --- Author: Lorenzo Cogotti --- Copyright: 2022 The DoubleFourteen Code Forge --- License: MIT (see LICENSE file for details) - -local io = require 'io' -local os = require 'os' - -- System specific functions -- -- Portions of this code are based on work from the LuaRocks project. @@ -15,6 +16,11 @@ local os = require 'os' -- LuaRocks website: https://luarocks.org -- LuaRocks sources: https://github.com/luarocks/luarocks +local io = require 'io' +local os = require 'os' + + + local is_windows = package.config:sub(1,1) == "\\" local is_directory diff --git a/input.lua b/input.lua index 053fcaf..b72768b 100644 --- a/input.lua +++ b/input.lua @@ -1,3 +1,12 @@ +--- Implements a text input field widget (textfield) +-- +-- @classmod yui.Input +-- @copyright 2022, The DoubleFourteen Code Forge +-- @author Lorenzo Cogotti, Andrea Pasquini +-- +--- Input widget receives the following callbacks: @{yui.Widget.WidgetCallbacks|onEnter}(), @{yui.Widget.WidgetCallbacks|onChange}(), @{yui.Widget.WidgetCallbacks|onLeave}(). + + local BASE = (...):gsub('input$', '') local Widget = require(BASE..'widget') @@ -18,6 +27,16 @@ local function split(str, pos) return str:sub(1, ofs-1), str:sub(ofs) end +--- Attributes accepted by the @{Input} widget beyond the standard @{yui.Widget.WidgetAttributes|attributes} +-- and @{yui.Widget.WidgetCallbacks|callbacks}. +-- +-- @field text (string) text displayed inside the Input +-- @field cornerRadius (number) radius for rounded corners +-- @table InputAttributes + + +--- Input constructor +-- @param args (@{InputAttributes}) widget attributes function Input.new(args) local self = setmetatable(args, Input) diff --git a/label.lua b/label.lua index 425b038..6f185e3 100644 --- a/label.lua +++ b/label.lua @@ -1,3 +1,10 @@ +--- Implements a static label widget +-- +-- @classmod yui.Label +-- @copyright 2022, The DoubleFourteen Code Forge +-- @author Lorenzo Cogotti, Andrea Pasquini +-- + local BASE = (...):gsub('label$', '') local Widget = require(BASE..'widget') @@ -13,7 +20,16 @@ local Label = setmetatable({ }, Widget) Label.__index = Label +--- Attributes accepted by the @{Label} widget in addition to the standard @{yui.Widget.WidgetAttributes|attributes}. +-- +-- @field text (string) text displayed inside the Label +-- @field[opt='center'] valign (string) vertical alignment 'top', 'bottom', 'center' +-- @field[opt='center'] align (string) horizontal alignment, 'left', 'center', 'right' +-- @field notranslate (boolean) don't translate text +-- @table LabelAttributes +--- Label constructor +-- @param args (@{LabelAttributes}) widget attributes function Label.new(args) local self = setmetatable(args, Label) diff --git a/layout.lua b/layout.lua index 66959e2..102f8c8 100644 --- a/layout.lua +++ b/layout.lua @@ -1,3 +1,15 @@ +--- Layout container widget +-- +-- Implements a layout widget +-- +-- @classmod yui.Layout +-- @copyright 2022, The DoubleFourteen Code Forge +-- @author Lorenzo Cogotti, Andrea Pasquini +-- +--- @{Layout} is an internal class, serving as a container of widgets and helping to define their organization and display order. +-- It is useful for arrangement customization. + + local BASE = (...):gsub('layout$', '') local Widget = require(BASE..'widget') @@ -147,6 +159,14 @@ local function scanbackwards(layout, from) end end +--- Attributes accepted by the Layout widget +-- +-- @field padding (number) number of pixels between two elements +-- @table LayoutAttributes + + +--- Layout constructor +-- @param args (@{LayoutAttributes}) widget attributes function Layout.new(args) local self = setmetatable(args, Layout) @@ -165,17 +185,17 @@ function Layout.new(args) return self end ---- Find first widget in layout accepting focus. +--- Find the first widget in the layout accepting focus. function Layout:first() return scanforward(self) end ---- Find last widget in layout accepting focus. +--- Find the last widget in the layout accepting focus. function Layout:last() return scanbackwards(self) end ---- Find next focusable widget after the provided one. +--- Find the next focusable widget after the provided one. function Layout:after(widget) widget = childof(self, widget) @@ -187,7 +207,7 @@ function Layout:after(widget) end end ---- Find previous focusable widget before the provided one. +--- Find the previous focusable widget before the provided one. function Layout:before(widget) widget = childof(self, widget) diff --git a/rows.lua b/rows.lua index b1f3e3e..b6de635 100644 --- a/rows.lua +++ b/rows.lua @@ -1,3 +1,11 @@ +--- Row layout for widgets +-- +-- @classmod yui.Rows +-- @copyright 2022, The DoubleFourteen Code Forge +-- @author Lorenzo Cogotti, Andrea Pasquini +-- +--- A widget container, lays down its child widgets into multiple rows. + local BASE = (...):gsub('rows$', '') local Layout = require(BASE..'layout') diff --git a/slider.lua b/slider.lua index 32a0d46..bd37f6d 100644 --- a/slider.lua +++ b/slider.lua @@ -1,3 +1,11 @@ +--- Implements a scrollable slider widget +-- +-- @classmod yui.Slider +-- @copyright 2022, The DoubleFourteen Code Forge +-- @author Lorenzo Cogotti, Andrea Pasquini +-- +--- Slider widget receives the following callbacks: @{yui.Widget.WidgetCallbacks|onEnter}(), @{yui.Widget.WidgetCallbacks|onChange}(), @{yui.Widget.WidgetCallbacks|onLeave}(). + local BASE = (...):gsub('slider$', '') local Widget = require(BASE..'widget') @@ -6,7 +14,20 @@ local core = require(BASE..'core') local Slider = setmetatable({}, Widget) Slider.__index = Slider +--- Attributes accepted by the @{Slider} widget beyond the standard @{yui.Widget.WidgetAttributes|attributes} +-- and @{yui.Widget.WidgetCallbacks|callbacks}. +-- +-- @field min (number) min value of the slider +-- @field max (number) max value of the slider +-- @field vertical (boolean) true for vertical slider, false or nil for horizontal slider +-- @field value (number) default value +-- @field step (number) number of slider's steps +-- @field cornerRadius (number) radius for rounded corners +-- @table SliderAttributes + +--- Slider constructor +-- @param args (@{SliderAttributes}) widget attributes function Slider.new(args) local self = setmetatable(args, Slider) diff --git a/spacer.lua b/spacer.lua index bc1cae2..d7f2985 100644 --- a/spacer.lua +++ b/spacer.lua @@ -1,3 +1,11 @@ +--- Implements a spacer widget +-- +-- @classmod yui.Spacer +-- @copyright 2022, The DoubleFourteen Code Forge +-- @author Lorenzo Cogotti, Andrea Pasquini +-- +--- Spacer widget insert a space between two widget. + local BASE = (...):gsub('spacer$', '') local Widget = require(BASE..'widget') @@ -10,6 +18,9 @@ local Spacer = setmetatable({ Spacer.__index = Spacer +--- Attributes accepted by the @{Spacer} widget @{yui.Widget.WidgetAttributes|attributes}. +-- +-- @param args @{yui.Widget.WidgetAttributes|Widgetattributes} widget attributes function Spacer.new(args) return setmetatable(args, Spacer) end return Spacer diff --git a/theme.lua b/theme.lua index 9d17b00..6bda54e 100644 --- a/theme.lua +++ b/theme.lua @@ -1,3 +1,27 @@ +--- Global visual theme settings +-- +-- @module yui.theme +-- @copyright 2022, The DoubleFourteen Code Forge +-- @author Lorenzo Cogotti, Andrea Pasquini + +--- Defines common visual attributes and colors applied to every @{yui.Widget|Widget}. +-- +-- @field cornerRadius (number) radius for rounded corners +-- @field color (@{ColorPalette}) default @{yui.Widget|Widget} color theme +-- @table theme + +--- Defines which color corresponds to each @{yui.Widget|Widget} state. +-- +-- @field hovered (@{Color}) color applied to hovered widgets +-- @field normal (@{Color}) color applied to widgets in their default state +-- @field active (@{Color}) color applied to active widgets +-- @table ColorPalette + +--- A pair defining background and foreground colors. +-- +-- @field bg (table) background color +-- @field fg (table) foreground color (typically used for text) +-- @table Color local theme = { cornerRadius = 4, diff --git a/ui.lua b/ui.lua index 892a60f..d063f65 100644 --- a/ui.lua +++ b/ui.lua @@ -1,3 +1,13 @@ +--- User interface manager +-- +-- @classmod yui.Ui +-- @copyright 2022, The DoubleFourteen Code Forge +-- @author Lorenzo Cogotti, Andrea Pasquini +-- + +--- An Ui manages a hierarchy of Widgets. +-- The @{Ui} draws its widgets according to their layout and position, manages input focus, and +-- dispatches events to the appropriate widgets depending on their class and activity status. local BASE = (...):gsub('ui$', '') local Widget = require(BASE..'widget') @@ -52,6 +62,15 @@ local function resolveautofocus(widget) return firstfocus, cancelfocus end +--- Attributes accepted by the Ui widget +-- +-- @field x (number) x position of the Ui +-- @field y (number) y position of the Ui +-- @table UiAttributes + + +--- Ui constructor +-- @param args (@{UiAttributes}) widget attributes function Ui.new(args) local self = setmetatable(args, Ui) assert(#self == 1, "Ui.new() must have exactly one root widget.") @@ -219,8 +238,7 @@ end --- Move focus to the given direction. -- --- @param where (string) Direction to move to, --- one of: 'up', 'down', 'left', 'right', 'cancel'. +-- @param where (string) Direction to move to, one of: 'up', 'down', 'left', 'right', 'cancel'. function Ui:navigate(where) local nextfocus = nil diff --git a/widget.lua b/widget.lua index 1bc85b2..c8769da 100644 --- a/widget.lua +++ b/widget.lua @@ -1,3 +1,20 @@ +--- A user interface element +-- @classmod yui.Widget +-- @copyright 2022, The DoubleFourteen Code Forge +-- @author Lorenzo Cogotti, Andrea Pasquini + +--- Functions accepted by all the Widget classes +-- @field onEnter function is called when the widget gets entered (e.g. hovered by pointer/mouse cursor) +-- @field onHit function is called when the widget is hit (e.g. clicked) +-- @field onChange function is called when the widget value is changed (e.g. checkbox is ticked) +-- @field onLeave function is called when the widget is left (e.g. another widget acquires focus, mouse leaves the widget area) +-- @table WidgetCallbacks + +--- Attributes accepted by all the Widget classes +-- @field w (number) widget width +-- @field h (number) widget height +-- @field color (@{yui.theme.ColorPalette|ColorPalette}) widget color +-- @table WidgetAttributes local rectunion = require('lib.gear.rect').union local Widget = { @@ -104,6 +121,7 @@ function Widget:loseFocus() end function Widget:gainFocus() end -- NOP event handlers, publicly overridable + function Widget:onHit() end function Widget:onEnter() end function Widget:onLeave() end