From c6f3d4c36b69a82c6afdfc14f887685afc3db402 Mon Sep 17 00:00:00 2001 From: Peter Feerick <5500713+pfeerick@users.noreply.github.com> Date: Mon, 7 Sep 2026 15:47:30 +1000 Subject: [PATCH 1/6] docs(lua): add luadoc annotations for the LVGL Lua API radio/src/lua/api_colorlcd_lvgl.cpp implements ~45 LVGL Lua bindings (buttons, sliders, labels, containers, dialogs, and other GUI controls for color-LCD scripts) but had zero /*luadoc*/ annotations, so the Lua-reference-guide doc-generation pipeline could extract nothing for LVGL at all. The official EdgeTX Lua reference guide has long carried full, accurate LVGL documentation for this exact file, written by philmoz (GitHub handle phil.a.mitchell in the docs repo's GitBook history), who also implemented the large majority of this file's actual C++ bindings. That content lived only in the docs repo, disconnected from the source it describes, which is what let it drift and made it impossible for any doc pipeline reading source comments to pick it up. This finishes and relocates that work into the source tree as the durable source of truth: every LROT_FUNCENTRY'd lvgl.* constructor and every standalone lvgl utility function (set/show/hide/clear/build/ enable/disable/close/getScrollPos/isAppMode/isFullScreen/ exitFullScreen/getContext) now has a @function-style luadoc block matching the convention used throughout the rest of the Lua API, sourced from that original documentation and cross-checked against this file's actual current parameter handling on the 2.12 branch. Comment-only change, no behavior change (diff is 1024 pure additions, 0 deletions, 0 modified lines). Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_015yCHydHbzZYCKpav38SonD --- radio/src/lua/api_colorlcd_lvgl.cpp | 1024 +++++++++++++++++++++++++++ 1 file changed, 1024 insertions(+) diff --git a/radio/src/lua/api_colorlcd_lvgl.cpp b/radio/src/lua/api_colorlcd_lvgl.cpp index 3792c627dbe..b3c9c419415 100644 --- a/radio/src/lua/api_colorlcd_lvgl.cpp +++ b/radio/src/lua/api_colorlcd_lvgl.cpp @@ -113,6 +113,19 @@ static int luaDestroyLvglWidget(lua_State *L) return 0; } +/*luadoc +@function lvgl.set([parent, ]params) + +Update the settings of an existing LVGL object. Can also be used to change settings that have no dedicated update function (e.g. rectangle thickness). + +@param parent (object) LVGL object to update + +@param params (table) settings to update; use the same keys documented for the object's constructor function + +@retval none + +@status current Introduced in 2.11.0 +*/ static int luaLvglSet(lua_State *L) { auto p = LvglWidgetObjectBase::checkLvgl(L, 1, true); @@ -122,6 +135,20 @@ static int luaLvglSet(lua_State *L) return 0; } +/*luadoc +@function lvgl.clear([parent]) + +Delete LVGL objects. + +@param parent (object) optional LVGL object whose children should be deleted; if omitted, the entire script UI is deleted + +@retval none + +@notice If `parent` is not set, the entire script UI is deleted -- use this when the UI changes dramatically (e.g. widget size changes). +@notice If `parent` is set, only its child LVGL objects are deleted -- use this to remove and replace a specific set of objects. + +@status current Introduced in 2.11.0 +*/ static int luaLvglClear(lua_State *L) { if (luaScriptManager) { @@ -138,6 +165,19 @@ static int luaLvglClear(lua_State *L) return 0; } +/*luadoc +@function lvgl.show(parent) + +Show an LVGL object. + +@param parent (object) LVGL object to show + +@retval none + +@notice The `visible` setting function can also be used to dynamically show and hide objects. + +@status current Introduced in 2.11.0 +*/ static int luaLvglShow(lua_State *L) { auto p = LvglWidgetObjectBase::checkLvgl(L, 1, true); @@ -147,6 +187,19 @@ static int luaLvglShow(lua_State *L) return 0; } +/*luadoc +@function lvgl.hide(parent) + +Hide an LVGL object. + +@param parent (object) LVGL object to hide + +@retval none + +@notice The `visible` setting function can also be used to dynamically show and hide objects. + +@status current Introduced in 2.11.0 +*/ static int luaLvglHide(lua_State *L) { auto p = LvglWidgetObjectBase::checkLvgl(L, 1, true); @@ -156,6 +209,17 @@ static int luaLvglHide(lua_State *L) return 0; } +/*luadoc +@function lvgl.enable(obj) + +Enable interaction for an LVGL control object. + +@param obj (object) LVGL object previously created by the `lvgl` library + +@retval none + +@status current Introduced in current +*/ static int luaLvglEnable(lua_State *L) { auto p = LvglWidgetObjectBase::checkLvgl(L, 1, true); @@ -165,6 +229,17 @@ static int luaLvglEnable(lua_State *L) return 0; } +/*luadoc +@function lvgl.disable(obj) + +Disable interaction for an LVGL control object. + +@param obj (object) LVGL object previously created by the `lvgl` library + +@retval none + +@status current Introduced in current +*/ static int luaLvglDisable(lua_State *L) { auto p = LvglWidgetObjectBase::checkLvgl(L, 1, true); @@ -174,6 +249,17 @@ static int luaLvglDisable(lua_State *L) return 0; } +/*luadoc +@function lvgl.close(obj) + +Close an LVGL object that represents a closable container or dialog. + +@param obj (object) LVGL object previously created by the `lvgl` library + +@retval none + +@status current Introduced in current +*/ static int luaLvglClose(lua_State *L) { auto p = LvglWidgetObjectBase::checkLvgl(L, 1, true); @@ -364,6 +450,26 @@ static int luaLvglObjEx(lua_State *L, std::function cre return 1; } +/*luadoc +@function lvgl.build([parent, ]params) + +Build a complex UI in a single operation from a table of object definitions. + +@param parent (object) optional LVGL object to attach the built objects to; if omitted they attach to the top-level script window + +@param params (table) a table of tables, each defining one LVGL object: + * `type` (string or type constant) mandatory, selects the kind of object to create, e.g. `"rectangle"` or `lvgl.RECTANGLE` + * `name` (string) optional name used to look up this object in the returned table, defaults to an empty string + * `children` (table) optional nested table of the same shape, to create child objects + * any other key accepted by the constructor function for the chosen `type` + +@retval table named LVGL objects (only entries whose definition included a `name` are included) + +@notice Objects can be nested via `children`, another table of tables using the same shape as the top-level `params`. +@notice Very large or deeply nested tables may fail to compile to `.luac` -- if a script works from `.lua` but fails from `.luac`, split the call into multiple smaller `lvgl.build()` calls. + +@status current Introduced in 2.11.0 +*/ static int luaLvglBuild(lua_State *L) { if (luaScriptManager) { @@ -389,6 +495,15 @@ static int luaLvglBuild(lua_State *L) return 1; } +/*luadoc +@function lvgl.isAppMode() + +Test if the script is running in App Mode. + +@retval boolean true if running in App Mode, false otherwise + +@status current Introduced in 2.11.0 +*/ static int luaLvglIsAppMode(lua_State *L) { if (luaScriptManager) { @@ -399,6 +514,17 @@ static int luaLvglIsAppMode(lua_State *L) return 1; } +/*luadoc +@function lvgl.isFullScreen() + +Test if the script is running in full screen mode. + +@retval boolean true if running in full screen mode, false otherwise + +@notice Always returns true for stand alone tool scripts. + +@status current Introduced in 2.11.0 +*/ static int luaLvglIsFullscreen(lua_State *L) { if (luaScriptManager) { @@ -409,6 +535,15 @@ static int luaLvglIsFullscreen(lua_State *L) return 1; } +/*luadoc +@function lvgl.exitFullScreen() + +If the script is running in full screen mode, return it to normal mode. + +@retval none + +@status current Introduced in 2.11.0 +*/ static int luaLvglExitFullscreen(lua_State *L) { if (luaScriptManager) @@ -416,6 +551,15 @@ static int luaLvglExitFullscreen(lua_State *L) return 0; } +/*luadoc +@function lvgl.getContext() + +For a widget script, returns the local instance table created by (and returned from) the script's `create()` function. + +@retval table the widget instance's local data table, or nil for stand alone tool scripts + +@status current Introduced in 2.11.0 +*/ static int luaLvglGetContext(lua_State *L) { if (luaScriptManager && luaScriptManager->getContext() != LUA_REFNIL) { @@ -427,6 +571,19 @@ static int luaLvglGetContext(lua_State *L) return 1; } +/*luadoc +@function lvgl.getScrollPos(parent) + +Get the current scroll position of a container object. + +@param parent (object) LVGL container object (e.g. `box`, `rectangle`, or `page`) + +@retval number, number the X and Y scroll position of the container's top-left corner + +@notice Only applies to container objects such as `box`, `rectangle`, and `page`. + +@status current Introduced in 2.11.2 +*/ static int luaLvglGetScrollPos(lua_State *L) { auto p = LvglWidgetObjectBase::checkLvgl(L, 1, true); @@ -448,40 +605,907 @@ LROT_BEGIN(lvgllib, NULL, 0) LROT_FUNCENTRY(exitFullScreen, luaLvglExitFullscreen) LROT_FUNCENTRY(getContext, luaLvglGetContext) // Objects - widgets and standalone scripts + /*luadoc + @function lvgl.label([parent, ]params) + + Display a text label. + + @param parent (object) optional LVGL object to attach the new object to; if omitted the object is created in the top-level script window + + @param params (table): + * `x` (number) position relative to the top-left of the parent + * `y` (number) position relative to the top-left of the parent + * `w` (number) width + * `h` (number) height + * `color` (color or function) primary color for the object + * `pos` (function) dynamic position callback returning `x, y` + * `size` (function) dynamic size callback returning `w, h` + * `visible` (function) dynamic visibility callback + * `floating` (boolean) keep the object fixed inside a scrollable container, defaults to false + * `text` (string or function) text to display, defaults to an empty string + * `font` (font value or function) sets the font size, e.g. `MIDSIZE`, `DBLSIZE`; defaults to `STDSIZE` + * `align` (text alignment value or function) sets the text justification, e.g. `RIGHT`, `VCENTER`; defaults to `LEFT`. `RIGHT`/`CENTER` require `w` to be set. `LEFT`/`RIGHT`/`CENTER` align text horizontally within the label's bounding box `(x,y,w,h)`; `VCENTER`/`VTOP`/`VBOTTOM` align the label's bounding box vertically within the parent object + + @retval table LVGL object + + @status current Introduced in 2.11.0 + */ LROT_FUNCENTRY(label, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetLabel(); }); }) + /*luadoc + @function lvgl.rectangle([parent, ]params) + + Display a rectangle. Based on `lvgl.box`, so all `lvgl.box` settings also apply. + + @param parent (object) optional LVGL object to attach the new object to; if omitted the object is created in the top-level script window + + @param params (table): + * `x` (number) position relative to the top-left of the parent + * `y` (number) position relative to the top-left of the parent + * `w` (number) width + * `h` (number) height + * `color` (color or function) primary color for the object + * `pos` (function) dynamic position callback returning `x, y` + * `size` (function) dynamic size callback returning `w, h` + * `visible` (function) dynamic visibility callback + * `floating` (boolean) keep the object fixed inside a scrollable container, defaults to false + * `thickness` (number) width of the border line, defaults to 1 + * `filled` (boolean or function) if true the rectangle is filled with `color`, defaults to false (function support added in 2.11.4) + * `rounded` (number) if greater than 0, rounds the corners with this radius; must be >= `thickness` if set, defaults to 0 + * `opacity` (number or function) opacity from 0 (transparent) to 255 (opaque), defaults to 255 + + @retval table LVGL object + + @notice When used in a stand alone tool script, the rectangle automatically adds scroll bars if any child objects are placed outside its boundaries. For widgets, child objects outside the bounds are clipped instead. + + @status current Introduced in 2.11.0 + */ LROT_FUNCENTRY(rectangle, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetRectangle(); }); }) + /*luadoc + @function lvgl.hline([parent, ]params) + + Display a horizontal line. + + @param parent (object) optional LVGL object to attach the new object to; if omitted the object is created in the top-level script window + + `w` sets the length of the line; `h` sets its thickness. + + @param params (table): + * `x` (number) position relative to the top-left of the parent + * `y` (number) position relative to the top-left of the parent + * `w` (number) width + * `h` (number) height + * `color` (color or function) primary color for the object + * `pos` (function) dynamic position callback returning `x, y` + * `size` (function) dynamic size callback returning `w, h` + * `visible` (function) dynamic visibility callback + * `floating` (boolean) keep the object fixed inside a scrollable container, defaults to false + * `rounded` (boolean) if true the line's end caps are rounded, defaults to false + * `opacity` (number or function) opacity from 0 (transparent) to 255 (opaque), defaults to 255 + * `dashGap` (number) gap size for dashed lines, defaults to 0 + * `dashWidth` (number) dash size for dashed lines, defaults to 0; both `dashGap` and `dashWidth` must be > 0 to draw dashed lines + + @retval table LVGL object + + @status current Introduced in 2.11.0 + */ LROT_FUNCENTRY(hline, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetHLine(); }); }) + /*luadoc + @function lvgl.vline([parent, ]params) + + Display a vertical line. + + @param parent (object) optional LVGL object to attach the new object to; if omitted the object is created in the top-level script window + + `h` sets the length of the line; `w` sets its thickness. + + @param params (table): + * `x` (number) position relative to the top-left of the parent + * `y` (number) position relative to the top-left of the parent + * `w` (number) width + * `h` (number) height + * `color` (color or function) primary color for the object + * `pos` (function) dynamic position callback returning `x, y` + * `size` (function) dynamic size callback returning `w, h` + * `visible` (function) dynamic visibility callback + * `floating` (boolean) keep the object fixed inside a scrollable container, defaults to false + * `rounded` (boolean) if true the line's end caps are rounded, defaults to false + * `opacity` (number or function) opacity from 0 (transparent) to 255 (opaque), defaults to 255 + * `dashGap` (number) gap size for dashed lines, defaults to 0 + * `dashWidth` (number) dash size for dashed lines, defaults to 0; both `dashGap` and `dashWidth` must be > 0 to draw dashed lines + + @retval table LVGL object + + @status current Introduced in 2.11.0 + */ LROT_FUNCENTRY(vline, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetVLine(); }); }) + /*luadoc + @function lvgl.line([parent, ]params) + + Display one or more connected line segments. + + @param parent (object) optional LVGL object to attach the new object to; if omitted the object is created in the top-level script window + + `x`, `y`, `w`, and `h` are not used. + + @param params (table): + * `x` (number) position relative to the top-left of the parent + * `y` (number) position relative to the top-left of the parent + * `w` (number) width + * `h` (number) height + * `color` (color or function) primary color for the object + * `pos` (function) dynamic position callback returning `x, y` + * `size` (function) dynamic size callback returning `w, h` + * `visible` (function) dynamic visibility callback + * `floating` (boolean) keep the object fixed inside a scrollable container, defaults to false + * `rounded` (boolean) if true the line's end caps are rounded, defaults to false + * `thickness` (number) thickness of each line segment, defaults to 1 + * `opacity` (number or function) opacity from 0 (transparent) to 255 (opaque), defaults to 255 + * `pts` (table or function) table of points, each a `{x, y}` pair; at least two points are required, defaults to nil + + @retval table LVGL object + + @status current Introduced in 2.11.0 + */ LROT_FUNCENTRY(line, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetLine(); }); }) + /*luadoc + @function lvgl.triangle([parent, ]params) + + Display a filled triangle. + + @param parent (object) optional LVGL object to attach the new object to; if omitted the object is created in the top-level script window + + `x`, `y`, `w`, and `h` are not used. + + @param params (table): + * `x` (number) position relative to the top-left of the parent + * `y` (number) position relative to the top-left of the parent + * `w` (number) width + * `h` (number) height + * `color` (color or function) primary color for the object + * `pos` (function) dynamic position callback returning `x, y` + * `size` (function) dynamic size callback returning `w, h` + * `visible` (function) dynamic visibility callback + * `floating` (boolean) keep the object fixed inside a scrollable container, defaults to false + * `opacity` (number or function) opacity from 0 (transparent) to 255 (opaque), defaults to 255 + * `pts` (table or function) table of exactly three points, each a `{x, y}` pair, defaults to nil + + @retval table LVGL object + + @notice Unlike the line-drawing objects, LVGL has no built-in triangle primitive. The drawing method used is simple and does not anti-alias. + + @status current Introduced in 2.11.0 + */ LROT_FUNCENTRY(triangle, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetTriangle(); }); }) + /*luadoc + @function lvgl.circle([parent, ]params) + + Display a solid or outlined circle. + + @param parent (object) optional LVGL object to attach the new object to; if omitted the object is created in the top-level script window + + `w`, `h`, and `size` should not be used with `lvgl.circle` -- use `radius` instead. + + @param params (table): + * `x` (number) position relative to the top-left of the parent + * `y` (number) position relative to the top-left of the parent + * `w` (number) width + * `h` (number) height + * `color` (color or function) primary color for the object + * `pos` (function) dynamic position callback returning `x, y` + * `size` (function) dynamic size callback returning `w, h` + * `visible` (function) dynamic visibility callback + * `floating` (boolean) keep the object fixed inside a scrollable container, defaults to false + * `thickness` (number) width of the border line, defaults to 1 + * `filled` (boolean) if true the circle is filled with `color`, defaults to false + * `radius` (number or function) radius of the circle, defaults to 0 + * `opacity` (number or function) opacity from 0 (transparent) to 255 (opaque), defaults to 255 + + @retval table LVGL object + + @status current Introduced in 2.11.0 + */ LROT_FUNCENTRY(circle, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetCircle(); }); }) + /*luadoc + @function lvgl.arc([parent, ]params) + + Display an arc. + + @param parent (object) optional LVGL object to attach the new object to; if omitted the object is created in the top-level script window + + `w`, `h`, and `size` should not be used with `lvgl.arc` -- use `radius` instead. + + @param params (table): + * `x` (number) position relative to the top-left of the parent + * `y` (number) position relative to the top-left of the parent + * `w` (number) width + * `h` (number) height + * `color` (color or function) primary color for the object + * `pos` (function) dynamic position callback returning `x, y` + * `size` (function) dynamic size callback returning `w, h` + * `visible` (function) dynamic visibility callback + * `floating` (boolean) keep the object fixed inside a scrollable container, defaults to false + * `thickness` (number) width of the arc's line, defaults to 1 + * `radius` (number or function) radius of the arc, defaults to 0 + * `startAngle` (number or function) starting angle in degrees (0-360), 0 is 3 o'clock, defaults to 0 + * `endAngle` (number or function) ending angle in degrees, defaults to 360 + * `opacity` (number or function) opacity from 0 (transparent) to 255 (opaque), defaults to 255 + * `rounded` (boolean) if true the ends of the arc are rounded, defaults to false + * `bgColor` (color or function) color of the background arc, not used by default + * `bgOpacity` (number or function) opacity of the background arc, defaults to 0 (not visible) + * `bgStartAngle` (number or function) starting angle of the background arc in degrees, defaults to 0 + * `bgEndAngle` (number or function) ending angle of the background arc in degrees, defaults to 360 + + @retval table LVGL object + + @status current Introduced in 2.11.0 + */ LROT_FUNCENTRY(arc, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetArc(); }); }) + /*luadoc + @function lvgl.image([parent, ]params) + + Display an image, centered in the frame `(x, y, w, h)`. Images can be scaled to fit entirely within the frame or to fill it completely. + + @param parent (object) optional LVGL object to attach the new object to; if omitted the object is created in the top-level script window + + @param params (table): + * `x` (number) position relative to the top-left of the parent + * `y` (number) position relative to the top-left of the parent + * `w` (number) width + * `h` (number) height + * `color` (color or function) primary color for the object + * `pos` (function) dynamic position callback returning `x, y` + * `size` (function) dynamic size callback returning `w, h` + * `visible` (function) dynamic visibility callback + * `floating` (boolean) keep the object fixed inside a scrollable container, defaults to false + * `file` (string) full path to the image file on the SD card, defaults to an empty string + * `fill` (boolean) if true the image is scaled to completely fill the frame (may be cropped); if false it is scaled to fit entirely within the frame (may have empty borders), defaults to false + + @retval table LVGL object + + @status current Introduced in 2.11.0 + */ LROT_FUNCENTRY(image, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetImage(); }); }) + /*luadoc + @function lvgl.qrcode([parent, ]params) + + Display a QR code. + + @param parent (object) optional LVGL object to attach the new object to; if omitted the object is created in the top-level script window + + `w` and `h` should be set to the same value for a QR code. + + @param params (table): + * `x` (number) position relative to the top-left of the parent + * `y` (number) position relative to the top-left of the parent + * `w` (number) width + * `h` (number) height + * `color` (color or function) primary color for the object + * `pos` (function) dynamic position callback returning `x, y` + * `size` (function) dynamic size callback returning `w, h` + * `visible` (function) dynamic visibility callback + * `floating` (boolean) keep the object fixed inside a scrollable container, defaults to false + * `data` (string) URL or other content to encode, defaults to an empty string + * `bgColor` (color) background color for the QR code image, defaults to `COLOR_THEME_SECONDARY3` + + @retval table LVGL object + + @status current Introduced in 2.11.0 + */ LROT_FUNCENTRY(qrcode, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetQRCode(); }); }) // Objects - standalone scripts and full screen widgets only + /*luadoc + @function lvgl.button([parent, ]params) + + Add a text button using the EdgeTX style. + + @param parent (object) optional LVGL object to attach the new object to; if omitted the object is created in the top-level script window + + @param params (table): + * `x` (number) position relative to the top-left of the parent + * `y` (number) position relative to the top-left of the parent + * `w` (number) width + * `h` (number) height + * `color` (color or function) primary color for the object + * `pos` (function) dynamic position callback returning `x, y` + * `size` (function) dynamic size callback returning `w, h` + * `visible` (function) dynamic visibility callback + * `floating` (boolean) keep the object fixed inside a scrollable container, defaults to false + * `text` (string or function) text displayed in the button, defaults to an empty string + * `press` (function) called when the user taps the button, after releasing ENTER or the screen; may optionally return a non-zero integer to display the button in the checked state, defaults to nil + * `longpress` (function) called on a long tap; may optionally return a non-zero integer to display the button in the checked state, defaults to nil + * `active` (function) sets the enabled/disabled state; must return a boolean, true to enable, defaults to nil + * `checked` (boolean) sets the initial checked state; can be updated with `lvgl.set()`, defaults to false + * `color` (color or function) background color, defaults to the EdgeTX button style PRIMARY2 theme color + * `textColor` (color or function) text color, defaults to the EdgeTX button style SECONDARY1 theme color + * `cornerRadius` (number) radius for the button's corners, defaults to the EdgeTX button style radius + * `font` (font value or function) sets the font size, e.g. `MIDSIZE`, `DBLSIZE`; defaults to `STDSIZE` + + @retval table LVGL object + + @status current Introduced in 2.11.0 + */ LROT_FUNCENTRY(button, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetTextButton(); }, true); }) + /*luadoc + @function lvgl.momentaryButton([parent, ]params) + + Add a momentary text button using the EdgeTX style. + + @param parent (object) optional LVGL object to attach the new object to; if omitted the object is created in the top-level script window + + @param params (table): + * `x` (number) position relative to the top-left of the parent + * `y` (number) position relative to the top-left of the parent + * `w` (number) width + * `h` (number) height + * `color` (color or function) primary color for the object + * `pos` (function) dynamic position callback returning `x, y` + * `size` (function) dynamic size callback returning `w, h` + * `visible` (function) dynamic visibility callback + * `floating` (boolean) keep the object fixed inside a scrollable container, defaults to false + * `text` (string or function) text displayed in the button, defaults to an empty string + * `press` (function) called immediately when the user first taps the button or presses ENTER, defaults to nil + * `release` (function) called when the user releases ENTER or stops touching the screen, defaults to nil + * `active` (function) sets the enabled/disabled state; must return a boolean, true to enable, defaults to nil + * `color` (color or function) background color, defaults to the EdgeTX button style PRIMARY2 theme color + * `textColor` (color or function) text color, defaults to the EdgeTX button style SECONDARY1 theme color + * `cornerRadius` (number) radius for the button's corners, defaults to the EdgeTX button style radius + * `font` (font value or function) sets the font size, e.g. `MIDSIZE`, `DBLSIZE`; defaults to `STDSIZE` + + @retval table LVGL object + + @notice Unlike `lvgl.button`, `press` fires immediately on tap/press rather than on release. The button shows the checked state until ENTER is released or the screen is no longer touched. + + @status current Introduced in 2.11.0 + */ LROT_FUNCENTRY(momentaryButton, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetMomentaryButton(); }, true); }) + /*luadoc + @function lvgl.toggle([parent, ]params) + + Add a toggle switch using the EdgeTX style. + + @param parent (object) optional LVGL object to attach the new object to; if omitted the object is created in the top-level script window + + @param params (table): + * `x` (number) position relative to the top-left of the parent + * `y` (number) position relative to the top-left of the parent + * `w` (number) width + * `h` (number) height + * `color` (color or function) primary color for the object + * `pos` (function) dynamic position callback returning `x, y` + * `size` (function) dynamic size callback returning `w, h` + * `visible` (function) dynamic visibility callback + * `floating` (boolean) keep the object fixed inside a scrollable container, defaults to false + * `get` (function) called to get the current state; must return a boolean or number (0/false = off, 1/true = on), defaults to nil + * `set` (function) called when the user interacts with the switch; passed a single number, 0 = off, 1 = on, defaults to nil + * `active` (function) sets the enabled/disabled state; must return a boolean, true to enable, defaults to nil + + @retval table LVGL object + + @status current Introduced in 2.11.0 + */ LROT_FUNCENTRY(toggle, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetToggleSwitch(); }, true); }) + /*luadoc + @function lvgl.textEdit([parent, ]params) + + Add a text edit box using the EdgeTX style. + + @param parent (object) optional LVGL object to attach the new object to; if omitted the object is created in the top-level script window + + @param params (table): + * `x` (number) position relative to the top-left of the parent + * `y` (number) position relative to the top-left of the parent + * `w` (number) width + * `h` (number) height + * `color` (color or function) primary color for the object + * `pos` (function) dynamic position callback returning `x, y` + * `size` (function) dynamic size callback returning `w, h` + * `visible` (function) dynamic visibility callback + * `floating` (boolean) keep the object fixed inside a scrollable container, defaults to false + * `value` (string or function) text to edit; if a function, the text can be changed by both script and user, defaults to an empty string + * `length` (number) maximum editable text length, 1 to 128, defaults to 32 + * `set` (function) called when the user edits the text; passed the new string content, defaults to nil + * `active` (function) sets the enabled/disabled state; must return a boolean, true to enable, defaults to nil + + @retval table LVGL object + + @status current Introduced in 2.11.0 + */ LROT_FUNCENTRY(textEdit, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetTextEdit(); }, true); }) + /*luadoc + @function lvgl.numberEdit([parent, ]params) + + Add a number edit box using the EdgeTX style. + + @param parent (object) optional LVGL object to attach the new object to; if omitted the object is created in the top-level script window + + @param params (table): + * `x` (number) position relative to the top-left of the parent + * `y` (number) position relative to the top-left of the parent + * `w` (number) width + * `h` (number) height + * `color` (color or function) primary color for the object + * `pos` (function) dynamic position callback returning `x, y` + * `size` (function) dynamic size callback returning `w, h` + * `visible` (function) dynamic visibility callback + * `floating` (boolean) keep the object fixed inside a scrollable container, defaults to false + * `get` (function) called to get the current value to display, defaults to nil + * `set` (function) called for every change to the number while editing; passed the new value, defaults to nil + * `edited` (function) called after the user finishes editing; passed the final value (added in 2.11.5), defaults to nil + * `active` (function) sets the enabled/disabled state; must return a boolean, true to enable, defaults to nil + * `min` (number) minimum allowed value, defaults to -1024 + * `max` (number) maximum allowed value, defaults to 1024 + * `display` (function) overrides how the value is displayed; passed the current value, must return a string, defaults to nil + + @retval table LVGL object + + @notice Use `set` to react to every change during editing, or `edited` to only react to the final value once editing is complete. + + @status current Introduced in 2.11.0 + */ LROT_FUNCENTRY(numberEdit, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetNumberEdit(); }, true); }) + /*luadoc + @function lvgl.choice([parent, ]params) + + Display a button showing an option value. Tapping it opens a popup menu of options to choose from, using EdgeTX styling. + + @param parent (object) optional LVGL object to attach the new object to; if omitted the object is created in the top-level script window + + @param params (table): + * `x` (number) position relative to the top-left of the parent + * `y` (number) position relative to the top-left of the parent + * `w` (number) width + * `h` (number) height + * `color` (color or function) primary color for the object + * `pos` (function) dynamic position callback returning `x, y` + * `size` (function) dynamic size callback returning `w, h` + * `visible` (function) dynamic visibility callback + * `floating` (boolean) keep the object fixed inside a scrollable container, defaults to false + * `title` (string) text displayed in the popup menu's header, defaults to an empty string + * `values` (table) simple table of option strings shown in the popup; can be changed via `lvgl.set()` since 2.11.6, defaults to an empty list + * `get` (function) called when the popup is opened, to get the index of the currently selected option (1..number of values), defaults to nil + * `set` (function) called when the user taps a menu item; passed the selected item's index (1..number of values), defaults to nil + * `active` (function) sets the enabled/disabled state; must return a boolean, true to enable, defaults to nil + * `filter` (function) called for each option when the popup opens, passed the option's index; return true to show it, false to hide it, defaults to nil + * `popupWidth` (number) width of the popup window, defaults to 0 (use default width) + + @retval table LVGL object + + @notice The popup closes and `set` is called when the user selects an item. + @notice If the user taps outside the popup or presses RTN, the popup closes without calling `set`. + + @status current Introduced in 2.11.0 + */ LROT_FUNCENTRY(choice, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetChoice(); }, true); }) + /*luadoc + @function lvgl.slider([parent, ]params) + + Add a horizontal slider using the EdgeTX style. + + @param parent (object) optional LVGL object to attach the new object to; if omitted the object is created in the top-level script window + + `w` sets the size of the slider; `h` is not used. + + @param params (table): + * `x` (number) position relative to the top-left of the parent + * `y` (number) position relative to the top-left of the parent + * `w` (number) width + * `h` (number) height + * `color` (color or function) primary color for the object + * `pos` (function) dynamic position callback returning `x, y` + * `size` (function) dynamic size callback returning `w, h` + * `visible` (function) dynamic visibility callback + * `floating` (boolean) keep the object fixed inside a scrollable container, defaults to false + * `min` (number) minimum value at the left end of the range, defaults to 0 + * `max` (number) maximum value at the right end of the range, defaults to 100 + * `get` (function) called to get the current knob value; should return a value between `min` and `max` inclusive, defaults to nil + * `set` (function) called when the user moves the knob; passed the new value, defaults to nil + * `active` (function) sets the enabled/disabled state; must return a boolean, true to enable, defaults to nil + + @retval table LVGL object + + @status current Introduced in 2.11.0 + */ LROT_FUNCENTRY(slider, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetSlider(); }, true); }) + /*luadoc + @function lvgl.verticalSlider([parent, ]params) + + Add a vertical slider using the EdgeTX style. + + @param parent (object) optional LVGL object to attach the new object to; if omitted the object is created in the top-level script window + + `h` sets the size of the slider; `w` is not used. + + @param params (table): + * `x` (number) position relative to the top-left of the parent + * `y` (number) position relative to the top-left of the parent + * `w` (number) width + * `h` (number) height + * `color` (color or function) primary color for the object + * `pos` (function) dynamic position callback returning `x, y` + * `size` (function) dynamic size callback returning `w, h` + * `visible` (function) dynamic visibility callback + * `floating` (boolean) keep the object fixed inside a scrollable container, defaults to false + * `min` (number) minimum value at the bottom end of the range, defaults to 0 + * `max` (number) maximum value at the top end of the range, defaults to 100 + * `get` (function) called to get the current knob value; should return a value between `min` and `max` inclusive, defaults to nil + * `set` (function) called when the user moves the knob; passed the new value, defaults to nil + * `active` (function) sets the enabled/disabled state; must return a boolean, true to enable, defaults to nil + + @retval table LVGL object + + @status current Introduced in 2.11.0 + */ LROT_FUNCENTRY(verticalSlider, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetVerticalSlider(); }, true); }) + /*luadoc + @function lvgl.font([parent, ]params) + + Display a button showing a font name. Tapping it opens a popup menu to choose a font from, using EdgeTX styling. + + @param parent (object) optional LVGL object to attach the new object to; if omitted the object is created in the top-level script window + + @param params (table): + * `x` (number) position relative to the top-left of the parent + * `y` (number) position relative to the top-left of the parent + * `w` (number) width + * `h` (number) height + * `color` (color or function) primary color for the object + * `pos` (function) dynamic position callback returning `x, y` + * `size` (function) dynamic size callback returning `w, h` + * `visible` (function) dynamic visibility callback + * `floating` (boolean) keep the object fixed inside a scrollable container, defaults to false + * `get` (function) called when the popup opens, to get the currently selected font, defaults to nil + * `set` (function) called when the user taps a font in the popup; passed the selected font value, defaults to nil + * `active` (function) sets the enabled/disabled state; must return a boolean, true to enable, defaults to nil + + @retval table LVGL object + + @notice The popup closes and `set` is called when the user selects an item. + @notice If the user taps outside the popup or presses RTN, the popup closes without calling `set`. + + @status current Introduced in 2.11.0 + */ LROT_FUNCENTRY(font, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetFontPicker(); }, true); }) + /*luadoc + @function lvgl.align([parent, ]params) + + Display a button showing a text alignment name. Tapping it opens a popup menu to choose an alignment from, using EdgeTX styling. + + @param parent (object) optional LVGL object to attach the new object to; if omitted the object is created in the top-level script window + + @param params (table): + * `x` (number) position relative to the top-left of the parent + * `y` (number) position relative to the top-left of the parent + * `w` (number) width + * `h` (number) height + * `color` (color or function) primary color for the object + * `pos` (function) dynamic position callback returning `x, y` + * `size` (function) dynamic size callback returning `w, h` + * `visible` (function) dynamic visibility callback + * `floating` (boolean) keep the object fixed inside a scrollable container, defaults to false + * `get` (function) called when the popup opens, to get the currently selected alignment, defaults to nil + * `set` (function) called when the user taps an alignment in the popup; passed the selected alignment value, defaults to nil + + @retval table LVGL object, or nil + + @notice The popup closes and `set` is called when the user selects an item. + @notice If the user taps outside the popup or presses RTN, the popup closes without calling `set`. + + @status current Introduced in 2.11.0 + */ LROT_FUNCENTRY(align, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetAlignPicker(); }, true); }) + /*luadoc + @function lvgl.color([parent, ]params) + + Display a button showing a color swatch. Tapping it opens the color picker dialog, using EdgeTX styling. + + @param parent (object) optional LVGL object to attach the new object to; if omitted the object is created in the top-level script window + + @param params (table): + * `x` (number) position relative to the top-left of the parent + * `y` (number) position relative to the top-left of the parent + * `w` (number) width + * `h` (number) height + * `color` (color or function) primary color for the object + * `pos` (function) dynamic position callback returning `x, y` + * `size` (function) dynamic size callback returning `w, h` + * `visible` (function) dynamic visibility callback + * `floating` (boolean) keep the object fixed inside a scrollable container, defaults to false + * `get` (function) called when the picker opens, to get the currently selected color, defaults to nil + * `set` (function) called when the user picks a color; passed the selected color value, defaults to nil + + @retval table LVGL object + + @notice The popup closes and `set` is called when the user selects a color. + @notice If the user taps outside the popup or presses RTN, the popup closes without calling `set`. + + @status current Introduced in 2.11.0 + */ LROT_FUNCENTRY(color, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetColorPicker(); }, true); }) + /*luadoc + @function lvgl.timer([parent, ]params) + + Display a button showing a timer name. Tapping it opens a popup menu to choose a timer from, using EdgeTX styling. + + @param parent (object) optional LVGL object to attach the new object to; if omitted the object is created in the top-level script window + + @param params (table): + * `x` (number) position relative to the top-left of the parent + * `y` (number) position relative to the top-left of the parent + * `w` (number) width + * `h` (number) height + * `color` (color or function) primary color for the object + * `pos` (function) dynamic position callback returning `x, y` + * `size` (function) dynamic size callback returning `w, h` + * `visible` (function) dynamic visibility callback + * `floating` (boolean) keep the object fixed inside a scrollable container, defaults to false + * `get` (function) called when the popup opens, to get the currently selected timer, defaults to nil + * `set` (function) called when the user taps a timer in the popup; passed the selected timer value, defaults to nil + * `active` (function) sets the enabled/disabled state; must return a boolean, true to enable, defaults to nil + + @retval table LVGL object + + @notice The popup closes and `set` is called when the user selects an item. + @notice If the user taps outside the popup or presses RTN, the popup closes without calling `set`. + + @status current Introduced in 2.11.0 + */ LROT_FUNCENTRY(timer, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetTimerPicker(); }, true); }) + /*luadoc + @function lvgl.switch([parent, ]params) + + Display a button showing a switch name. Tapping it opens the switch-select popup, using EdgeTX styling. + + @param parent (object) optional LVGL object to attach the new object to; if omitted the object is created in the top-level script window + + @param params (table): + * `x` (number) position relative to the top-left of the parent + * `y` (number) position relative to the top-left of the parent + * `w` (number) width + * `h` (number) height + * `color` (color or function) primary color for the object + * `pos` (function) dynamic position callback returning `x, y` + * `size` (function) dynamic size callback returning `w, h` + * `visible` (function) dynamic visibility callback + * `floating` (boolean) keep the object fixed inside a scrollable container, defaults to false + * `get` (function) called when the popup opens, to get the currently selected switch, defaults to nil + * `set` (function) called when the user picks a switch; passed the selected switch value, defaults to nil + * `active` (function) sets the enabled/disabled state; must return a boolean, true to enable, defaults to nil + + @retval table LVGL object + + @notice The popup closes and `set` is called when the user selects an item. + @notice If the user taps outside the popup or presses RTN, the popup closes without calling `set`. + + @status current Introduced in 2.11.0 + */ LROT_FUNCENTRY(switch, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetSwitchPicker(); }, true); }) + /*luadoc + @function lvgl.source([parent, ]params) + + Display a button showing a source name. Tapping it opens the source-select popup, using EdgeTX styling. + + @param parent (object) optional LVGL object to attach the new object to; if omitted the object is created in the top-level script window + + @param params (table): + * `x` (number) position relative to the top-left of the parent + * `y` (number) position relative to the top-left of the parent + * `w` (number) width + * `h` (number) height + * `color` (color or function) primary color for the object + * `pos` (function) dynamic position callback returning `x, y` + * `size` (function) dynamic size callback returning `w, h` + * `visible` (function) dynamic visibility callback + * `floating` (boolean) keep the object fixed inside a scrollable container, defaults to false + * `get` (function) called when the popup opens, to get the currently selected source, defaults to nil + * `set` (function) called when the user picks a source; passed the selected source value, defaults to nil + * `filter` (number) controls which source types the user can pick; combine `lvgl.SRC_xxx` constants to build a custom filter, defaults to `lvgl.SRC_ALL` + + @retval table LVGL object + + @notice The popup closes and `set` is called when the user selects an item. + @notice If the user taps outside the popup or presses RTN, the popup closes without calling `set`. + + @status current Introduced in 2.11.0 + */ LROT_FUNCENTRY(source, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetSourcePicker(); }, true); }) + /*luadoc + @function lvgl.file([parent, ]params) + + Display a button showing a filename. Tapping it opens a popup file picker, using EdgeTX styling. + + @param parent (object) optional LVGL object to attach the new object to; if omitted the object is created in the top-level script window + + @param params (table): + * `x` (number) position relative to the top-left of the parent + * `y` (number) position relative to the top-left of the parent + * `w` (number) width + * `h` (number) height + * `color` (color or function) primary color for the object + * `pos` (function) dynamic position callback returning `x, y` + * `size` (function) dynamic size callback returning `w, h` + * `visible` (function) dynamic visibility callback + * `floating` (boolean) keep the object fixed inside a scrollable container, defaults to false + * `title` (string) text displayed in the popup's header, defaults to an empty string + * `get` (function) called when the popup opens, to get the currently selected filename; must return a string, defaults to nil + * `set` (function) called when the user picks a file; passed the selected filename (without path), defaults to nil + * `active` (function) sets the enabled/disabled state; must return a boolean, true to enable, defaults to nil + * `folder` (string) SD card folder to browse for files, defaults to nil + * `extension` (string) extension filter, e.g. `.png` or concatenated `.png.bmp` to match multiple, defaults to nil (no filter) + * `hideExtension` (boolean) if true, the extension is stripped before `set` is called and hidden in the picker list, defaults to false + * `maxLen` (number) maximum filename length shown in the picker, defaults to 255 + + @retval table LVGL object + + @notice The popup closes and `set` is called when the user picks a file. + @notice If the user taps outside the popup or presses RTN, the popup closes without calling `set`. + + @status current Introduced in 2.11.0 + */ LROT_FUNCENTRY(file, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetFilePicker(); }, true); }) // Containers + /*luadoc + @function lvgl.box([parent, ]params) + + Create a container for managing object layout. + + @param parent (object) optional LVGL object to attach the new object to; if omitted the object is created in the top-level script window + + @param params (table): + * `x` (number) position relative to the top-left of the parent + * `y` (number) position relative to the top-left of the parent + * `w` (number) width + * `h` (number) height + * `color` (color or function) primary color for the object + * `pos` (function) dynamic position callback returning `x, y` + * `size` (function) dynamic size callback returning `w, h` + * `visible` (function) dynamic visibility callback + * `floating` (boolean) keep the object fixed inside a scrollable container, defaults to false + * `flexFlow` (lvgl.FLOW_COLUMN or lvgl.FLOW_ROW) enables flex layout for this box, not used by default + * `flexPad` (number) padding between rows/columns when flex layout is used; recommend using `lvgl.PAD_xxx` values, defaults to `PAD_OUTLINE` + * `scrollBar` (boolean) enables/disables scroll bars, defaults to true + * `scrollDir` (lvgl.SCROLL_xx) allowed scroll directions when child objects extend past the box bounds (stand alone scripts only), defaults to `lvgl.SCROLL_ALL` + * `scrolled` (function) called when the box content is scrolled; passed `x`, `y` of the current scroll position, defaults to nil + * `scrollTo` (function) overrides the box scroll position; must return `x`, `y` to scroll to, defaults to nil + * `align` (alignment type (LEFT, RIGHT, CENTER, VTOP, VBOTTOM, VCENTER)) alignment used with flex layouts (added in 2.11.4); avoid combining an alignment with a scrollbar on the same axis, defaults to `CENTER | VTOP` + * `borderPad` (number or table) border padding around the container edges; a single number applies to all sides, or a table `{left=?, right=?, top=?, bottom=?}` (added in 2.11.5), defaults to `PAD_OUTLINE` if `flexFlow` is set, otherwise 0 + + @retval table LVGL object + + @notice The box is a helper for managing screen layouts. + @notice When adding controls such as button/toggle/textEdit, leave enough space around them for the focus outline. + @notice In a stand alone tool script, the box automatically adds scroll bars if child objects fall outside its boundaries; for widgets, out-of-bounds children are clipped instead. + + @status current Introduced in 2.11.0 + */ LROT_FUNCENTRY(box, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetBox(); }); }) + /*luadoc + @function lvgl.setting([parent, ]params) + + Create a container for a single row of a settings page, automatically padded for controls such as toggle/textEdit/button. + + @param parent (object) optional LVGL object to attach the new object to; if omitted the object is created in the top-level script window + + @param params (table): + * `x` (number) position relative to the top-left of the parent + * `y` (number) position relative to the top-left of the parent + * `w` (number) width + * `h` (number) height + * `color` (color or function) primary color for the object + * `pos` (function) dynamic position callback returning `x, y` + * `size` (function) dynamic size callback returning `w, h` + * `visible` (function) dynamic visibility callback + * `floating` (boolean) keep the object fixed inside a scrollable container, defaults to false + * `title` (string or function) text displayed on the left; function support added in 2.11.6, defaults to an empty string + + @retval table LVGL object + + @status current Introduced in 2.11.0 + */ LROT_FUNCENTRY(setting, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetSetting(); }, true); }) + /*luadoc + @function lvgl.page(params) + + Create a page layout for a One-Time script using EdgeTX styling: a header with title/sub-title lines and a back button in the top-left corner. Should be created as the top-level LVGL object, with all other objects added as its children. + + @param params (table): + * `title` (string or function) title text in the header; function support added in 2.11.4, defaults to an empty string + * `subtitle` (string or function) sub-title text in the header; function support added in 2.11.4, defaults to an empty string + * `icon` (string) full path to a 30x30 grey-scale mask image for the back button icon (white = transparent, black = opaque); defaults to the EdgeTX logo icon + * `back` (function) called when the user taps the back button or presses RTN, defaults to nil + * `menu` (function) called when the user taps the menu button (added in 2.11.4), defaults to nil + * `prevButton` (table) adds a prev navigation button; table has a `press` function and optional `active` function (added in 2.11.4), defaults to nil + * `nextButton` (table) adds a next navigation button; table has a `press` function and optional `active` function (added in 2.11.4), defaults to nil + * `flexFlow` (lvgl.FLOW_COLUMN or lvgl.FLOW_ROW) enables flex layout for this page, not used by default + * `flexPad` (number) padding between rows/columns when flex layout is used, defaults to `PAD_OUTLINE` + * `scrollBar` (boolean) enables/disables scroll bars, defaults to true + * `scrollDir` (lvgl.SCROLL_xx) allowed scroll directions when child objects extend past the page bounds (stand alone scripts only), defaults to `lvgl.SCROLL_ALL` + * `scrolled` (function) called when the page content is scrolled; passed `x`, `y` of the current scroll position, defaults to nil + * `scrollTo` (function) overrides the page scroll position; must return `x`, `y` to scroll to, defaults to nil + * `align` (alignment type (LEFT, RIGHT, CENTER, VTOP, VBOTTOM, VCENTER)) alignment used with flex layouts (added in 2.11.4), defaults to `CENTER | TOP` + * `backButton` (boolean) if true, displays an exit/back button on the right of the header (added in 2.11.4), defaults to false + * `borderPad` (number or table) border padding around the container edges; a single number applies to all sides, or a table `{left=?, right=?, top=?, bottom=?}` (added in 2.11.5), defaults to `PAD_OUTLINE` if `flexFlow` is set, otherwise 0 + + @retval table LVGL object + + @notice The common object settings (x, y, w, h, color, etc.) are not used by `lvgl.page` -- only the settings listed above apply. + @notice The page automatically adds scroll bars if child objects fall outside its boundaries. + + @status current Introduced in 2.11.0 + */ LROT_FUNCENTRY(page, [](lua_State* L) { return luaLvglObj(L, []() { return new LvglWidgetPage(); }, true); }) + /*luadoc + @function lvgl.dialog(params) + + Display a dialog box. + + @param params (table): + * `title` (string) text displayed in the dialog's header, defaults to an empty string + * `close` (function) called when the dialog is closed, defaults to nil + * `flexFlow` (lvgl.FLOW_COLUMN or lvgl.FLOW_ROW) enables flex layout for this box, not used by default + * `flexPad` (number) padding between rows/columns when flex layout is used, defaults to 0 + + @retval table LVGL object + + @notice The common object settings (x, y, w, h, color, etc.) are not used by `lvgl.dialog` -- only the settings listed above apply. + + @status current Introduced in 2.11.0 + */ LROT_FUNCENTRY(dialog, [](lua_State* L) { return luaLvglObj(L, []() { return new LvglWidgetDialog(); }, true); }) // Dialogs + /*luadoc + @function lvgl.confirm(params) + + Display a Yes/No confirmation dialog box. + + @param params (table): + * `title` (string) text displayed in the dialog's header, defaults to an empty string + * `message` (string) text displayed in the dialog's body, defaults to an empty string + * `confirm` (function) called when the user taps Yes, defaults to nil + * `cancel` (function) called when the user taps No, defaults to nil + + @retval none + + @notice The common object settings (x, y, w, h, color, etc.) are not used by `lvgl.confirm` -- only the settings listed above apply. + + @status current Introduced in 2.11.0 + */ LROT_FUNCENTRY(confirm, [](lua_State* L) { return luaLvglPopup(L, []() { return new LvglWidgetConfirmDialog(); }); }) + /*luadoc + @function lvgl.message(params) + + Display a message dialog box. + + @param params (table): + * `title` (string) text displayed in the dialog's header, defaults to an empty string + * `message` (string) text displayed in the dialog's body, defaults to an empty string + * `details` (function) additional text displayed in the dialog's body, defaults to an empty string + + @retval none + + @notice The common object settings (x, y, w, h, color, etc.) are not used by `lvgl.message` -- only the settings listed above apply. + + @status current Introduced in 2.11.0 + */ LROT_FUNCENTRY(message, [](lua_State* L) { return luaLvglPopup(L, []() { return new LvglWidgetMessageDialog(); }); }) + /*luadoc + @function lvgl.menu(params) + + Open a popup menu with multiple options to choose from, using EdgeTX styling. + + @param params (table): + * `title` (string) text displayed in the popup's header, defaults to an empty string + * `values` (table) simple table of option strings shown in the popup, defaults to an empty list + * `get` (function) called when the popup opens, to get the index of the currently selected option (1..number of values), defaults to nil + * `set` (function) called when the user taps a menu item; passed the selected item's index (1..number of values), defaults to nil + + @retval none + + @notice The common object settings (x, y, w, h, color, etc.) are not used by `lvgl.menu` -- only the settings listed above apply. + @notice The popup closes and `set` is called when the user selects an item. + @notice If the user taps outside the popup or presses RTN, the popup closes without calling `set`. + + @status current Introduced in 2.11.1 + */ LROT_FUNCENTRY(menu, [](lua_State* L) { return luaLvglPopup(L, []() { return new LvglWidgetMenu(); }); }) // Object manipulation functions LROT_FUNCENTRY(set, luaLvglSet) From 04daca947c6e60d020b1de9f89ecaa5b2909fc86 Mon Sep 17 00:00:00 2001 From: Peter Feerick <5500713+pfeerick@users.noreply.github.com> Date: Mon, 7 Sep 2026 16:07:23 +1000 Subject: [PATCH 2/6] docs(lua): add missing version-history to LVGL luadoc @status lines The initial LVGL luadoc annotation commit captured several post-2.11.0 additions inline in individual @param descriptions (filled/edited/values/align/borderPad/title-as-function) but never rolled them into the @status line, and consistently omitted the `floating` common-property's introduction version. Verified against actual EdgeTX commit/tag history (not the official guide's copy, which claims 2.11.6/2.11.4 for several of these) that `floating`, the SCROLL_xx constants + scrollBar/scrollDir/scrolled/ scrollTo, and lvgl.build's named type constants (lvgl.RECTANGLE etc.) were all first released in 2.12.0, not any 2.11.x version -- the official guide's version numbers for these predate the 2.12.0 tag cut and are stale relative to actual release history. Updates every affected function's @status line to name the specific version each field/capability was added in, following this codebase's existing convention (e.g. model.getInfo's "@status current Introduced in 2.0.6, changed in 2.2.0, filename added in 2.6.0, ..."). Adds the missing "(added in 2.12.0)" note to all 27 `floating` occurrences, and adds @notice/status coverage for box/page's scroll-related parameters and lvgl.build's type-constant parameter, which had no version note of any kind before this commit. Comment-only change, no behavior change. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_015yCHydHbzZYCKpav38SonD --- radio/src/lua/api_colorlcd_lvgl.cpp | 116 ++++++++++++++-------------- 1 file changed, 59 insertions(+), 57 deletions(-) diff --git a/radio/src/lua/api_colorlcd_lvgl.cpp b/radio/src/lua/api_colorlcd_lvgl.cpp index b3c9c419415..c441ff12973 100644 --- a/radio/src/lua/api_colorlcd_lvgl.cpp +++ b/radio/src/lua/api_colorlcd_lvgl.cpp @@ -458,7 +458,7 @@ Build a complex UI in a single operation from a table of object definitions. @param parent (object) optional LVGL object to attach the built objects to; if omitted they attach to the top-level script window @param params (table) a table of tables, each defining one LVGL object: - * `type` (string or type constant) mandatory, selects the kind of object to create, e.g. `"rectangle"` or `lvgl.RECTANGLE` + * `type` (string or type constant) mandatory, selects the kind of object to create, e.g. `"rectangle"` or `lvgl.RECTANGLE`; named type constants (e.g. `lvgl.RECTANGLE`) added in 2.12.0, string names work in all versions * `name` (string) optional name used to look up this object in the returned table, defaults to an empty string * `children` (table) optional nested table of the same shape, to create child objects * any other key accepted by the constructor function for the chosen `type` @@ -468,7 +468,7 @@ Build a complex UI in a single operation from a table of object definitions. @notice Objects can be nested via `children`, another table of tables using the same shape as the top-level `params`. @notice Very large or deeply nested tables may fail to compile to `.luac` -- if a script works from `.lua` but fails from `.luac`, split the call into multiple smaller `lvgl.build()` calls. -@status current Introduced in 2.11.0 +@status current Introduced in 2.11.0, named type constants added in 2.12.0 */ static int luaLvglBuild(lua_State *L) { @@ -621,14 +621,14 @@ LROT_BEGIN(lvgllib, NULL, 0) * `pos` (function) dynamic position callback returning `x, y` * `size` (function) dynamic size callback returning `w, h` * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, defaults to false + * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.12.0, defaults to false * `text` (string or function) text to display, defaults to an empty string * `font` (font value or function) sets the font size, e.g. `MIDSIZE`, `DBLSIZE`; defaults to `STDSIZE` * `align` (text alignment value or function) sets the text justification, e.g. `RIGHT`, `VCENTER`; defaults to `LEFT`. `RIGHT`/`CENTER` require `w` to be set. `LEFT`/`RIGHT`/`CENTER` align text horizontally within the label's bounding box `(x,y,w,h)`; `VCENTER`/`VTOP`/`VBOTTOM` align the label's bounding box vertically within the parent object @retval table LVGL object - @status current Introduced in 2.11.0 + @status current Introduced in 2.11.0, floating added in 2.12.0 */ LROT_FUNCENTRY(label, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetLabel(); }); }) /*luadoc @@ -647,7 +647,7 @@ LROT_BEGIN(lvgllib, NULL, 0) * `pos` (function) dynamic position callback returning `x, y` * `size` (function) dynamic size callback returning `w, h` * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, defaults to false + * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.12.0, defaults to false * `thickness` (number) width of the border line, defaults to 1 * `filled` (boolean or function) if true the rectangle is filled with `color`, defaults to false (function support added in 2.11.4) * `rounded` (number) if greater than 0, rounds the corners with this radius; must be >= `thickness` if set, defaults to 0 @@ -657,7 +657,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @notice When used in a stand alone tool script, the rectangle automatically adds scroll bars if any child objects are placed outside its boundaries. For widgets, child objects outside the bounds are clipped instead. - @status current Introduced in 2.11.0 + @status current Introduced in 2.11.0, filled function support added in 2.11.4, floating added in 2.12.0 */ LROT_FUNCENTRY(rectangle, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetRectangle(); }); }) /*luadoc @@ -678,7 +678,7 @@ LROT_BEGIN(lvgllib, NULL, 0) * `pos` (function) dynamic position callback returning `x, y` * `size` (function) dynamic size callback returning `w, h` * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, defaults to false + * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.12.0, defaults to false * `rounded` (boolean) if true the line's end caps are rounded, defaults to false * `opacity` (number or function) opacity from 0 (transparent) to 255 (opaque), defaults to 255 * `dashGap` (number) gap size for dashed lines, defaults to 0 @@ -686,7 +686,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @retval table LVGL object - @status current Introduced in 2.11.0 + @status current Introduced in 2.11.0, floating added in 2.12.0 */ LROT_FUNCENTRY(hline, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetHLine(); }); }) /*luadoc @@ -707,7 +707,7 @@ LROT_BEGIN(lvgllib, NULL, 0) * `pos` (function) dynamic position callback returning `x, y` * `size` (function) dynamic size callback returning `w, h` * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, defaults to false + * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.12.0, defaults to false * `rounded` (boolean) if true the line's end caps are rounded, defaults to false * `opacity` (number or function) opacity from 0 (transparent) to 255 (opaque), defaults to 255 * `dashGap` (number) gap size for dashed lines, defaults to 0 @@ -715,7 +715,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @retval table LVGL object - @status current Introduced in 2.11.0 + @status current Introduced in 2.11.0, floating added in 2.12.0 */ LROT_FUNCENTRY(vline, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetVLine(); }); }) /*luadoc @@ -736,7 +736,7 @@ LROT_BEGIN(lvgllib, NULL, 0) * `pos` (function) dynamic position callback returning `x, y` * `size` (function) dynamic size callback returning `w, h` * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, defaults to false + * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.12.0, defaults to false * `rounded` (boolean) if true the line's end caps are rounded, defaults to false * `thickness` (number) thickness of each line segment, defaults to 1 * `opacity` (number or function) opacity from 0 (transparent) to 255 (opaque), defaults to 255 @@ -744,7 +744,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @retval table LVGL object - @status current Introduced in 2.11.0 + @status current Introduced in 2.11.0, floating added in 2.12.0 */ LROT_FUNCENTRY(line, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetLine(); }); }) /*luadoc @@ -765,7 +765,7 @@ LROT_BEGIN(lvgllib, NULL, 0) * `pos` (function) dynamic position callback returning `x, y` * `size` (function) dynamic size callback returning `w, h` * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, defaults to false + * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.12.0, defaults to false * `opacity` (number or function) opacity from 0 (transparent) to 255 (opaque), defaults to 255 * `pts` (table or function) table of exactly three points, each a `{x, y}` pair, defaults to nil @@ -773,7 +773,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @notice Unlike the line-drawing objects, LVGL has no built-in triangle primitive. The drawing method used is simple and does not anti-alias. - @status current Introduced in 2.11.0 + @status current Introduced in 2.11.0, floating added in 2.12.0 */ LROT_FUNCENTRY(triangle, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetTriangle(); }); }) /*luadoc @@ -794,7 +794,7 @@ LROT_BEGIN(lvgllib, NULL, 0) * `pos` (function) dynamic position callback returning `x, y` * `size` (function) dynamic size callback returning `w, h` * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, defaults to false + * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.12.0, defaults to false * `thickness` (number) width of the border line, defaults to 1 * `filled` (boolean) if true the circle is filled with `color`, defaults to false * `radius` (number or function) radius of the circle, defaults to 0 @@ -802,7 +802,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @retval table LVGL object - @status current Introduced in 2.11.0 + @status current Introduced in 2.11.0, floating added in 2.12.0 */ LROT_FUNCENTRY(circle, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetCircle(); }); }) /*luadoc @@ -823,7 +823,7 @@ LROT_BEGIN(lvgllib, NULL, 0) * `pos` (function) dynamic position callback returning `x, y` * `size` (function) dynamic size callback returning `w, h` * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, defaults to false + * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.12.0, defaults to false * `thickness` (number) width of the arc's line, defaults to 1 * `radius` (number or function) radius of the arc, defaults to 0 * `startAngle` (number or function) starting angle in degrees (0-360), 0 is 3 o'clock, defaults to 0 @@ -837,7 +837,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @retval table LVGL object - @status current Introduced in 2.11.0 + @status current Introduced in 2.11.0, floating added in 2.12.0 */ LROT_FUNCENTRY(arc, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetArc(); }); }) /*luadoc @@ -856,13 +856,13 @@ LROT_BEGIN(lvgllib, NULL, 0) * `pos` (function) dynamic position callback returning `x, y` * `size` (function) dynamic size callback returning `w, h` * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, defaults to false + * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.12.0, defaults to false * `file` (string) full path to the image file on the SD card, defaults to an empty string * `fill` (boolean) if true the image is scaled to completely fill the frame (may be cropped); if false it is scaled to fit entirely within the frame (may have empty borders), defaults to false @retval table LVGL object - @status current Introduced in 2.11.0 + @status current Introduced in 2.11.0, floating added in 2.12.0 */ LROT_FUNCENTRY(image, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetImage(); }); }) /*luadoc @@ -883,13 +883,13 @@ LROT_BEGIN(lvgllib, NULL, 0) * `pos` (function) dynamic position callback returning `x, y` * `size` (function) dynamic size callback returning `w, h` * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, defaults to false + * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.12.0, defaults to false * `data` (string) URL or other content to encode, defaults to an empty string * `bgColor` (color) background color for the QR code image, defaults to `COLOR_THEME_SECONDARY3` @retval table LVGL object - @status current Introduced in 2.11.0 + @status current Introduced in 2.11.0, floating added in 2.12.0 */ LROT_FUNCENTRY(qrcode, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetQRCode(); }); }) // Objects - standalone scripts and full screen widgets only @@ -909,7 +909,7 @@ LROT_BEGIN(lvgllib, NULL, 0) * `pos` (function) dynamic position callback returning `x, y` * `size` (function) dynamic size callback returning `w, h` * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, defaults to false + * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.12.0, defaults to false * `text` (string or function) text displayed in the button, defaults to an empty string * `press` (function) called when the user taps the button, after releasing ENTER or the screen; may optionally return a non-zero integer to display the button in the checked state, defaults to nil * `longpress` (function) called on a long tap; may optionally return a non-zero integer to display the button in the checked state, defaults to nil @@ -922,7 +922,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @retval table LVGL object - @status current Introduced in 2.11.0 + @status current Introduced in 2.11.0, floating added in 2.12.0 */ LROT_FUNCENTRY(button, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetTextButton(); }, true); }) /*luadoc @@ -941,7 +941,7 @@ LROT_BEGIN(lvgllib, NULL, 0) * `pos` (function) dynamic position callback returning `x, y` * `size` (function) dynamic size callback returning `w, h` * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, defaults to false + * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.12.0, defaults to false * `text` (string or function) text displayed in the button, defaults to an empty string * `press` (function) called immediately when the user first taps the button or presses ENTER, defaults to nil * `release` (function) called when the user releases ENTER or stops touching the screen, defaults to nil @@ -955,7 +955,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @notice Unlike `lvgl.button`, `press` fires immediately on tap/press rather than on release. The button shows the checked state until ENTER is released or the screen is no longer touched. - @status current Introduced in 2.11.0 + @status current Introduced in 2.11.0, floating added in 2.12.0 */ LROT_FUNCENTRY(momentaryButton, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetMomentaryButton(); }, true); }) /*luadoc @@ -974,14 +974,14 @@ LROT_BEGIN(lvgllib, NULL, 0) * `pos` (function) dynamic position callback returning `x, y` * `size` (function) dynamic size callback returning `w, h` * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, defaults to false + * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.12.0, defaults to false * `get` (function) called to get the current state; must return a boolean or number (0/false = off, 1/true = on), defaults to nil * `set` (function) called when the user interacts with the switch; passed a single number, 0 = off, 1 = on, defaults to nil * `active` (function) sets the enabled/disabled state; must return a boolean, true to enable, defaults to nil @retval table LVGL object - @status current Introduced in 2.11.0 + @status current Introduced in 2.11.0, floating added in 2.12.0 */ LROT_FUNCENTRY(toggle, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetToggleSwitch(); }, true); }) /*luadoc @@ -1000,7 +1000,7 @@ LROT_BEGIN(lvgllib, NULL, 0) * `pos` (function) dynamic position callback returning `x, y` * `size` (function) dynamic size callback returning `w, h` * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, defaults to false + * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.12.0, defaults to false * `value` (string or function) text to edit; if a function, the text can be changed by both script and user, defaults to an empty string * `length` (number) maximum editable text length, 1 to 128, defaults to 32 * `set` (function) called when the user edits the text; passed the new string content, defaults to nil @@ -1008,7 +1008,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @retval table LVGL object - @status current Introduced in 2.11.0 + @status current Introduced in 2.11.0, floating added in 2.12.0 */ LROT_FUNCENTRY(textEdit, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetTextEdit(); }, true); }) /*luadoc @@ -1027,7 +1027,7 @@ LROT_BEGIN(lvgllib, NULL, 0) * `pos` (function) dynamic position callback returning `x, y` * `size` (function) dynamic size callback returning `w, h` * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, defaults to false + * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.12.0, defaults to false * `get` (function) called to get the current value to display, defaults to nil * `set` (function) called for every change to the number while editing; passed the new value, defaults to nil * `edited` (function) called after the user finishes editing; passed the final value (added in 2.11.5), defaults to nil @@ -1040,7 +1040,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @notice Use `set` to react to every change during editing, or `edited` to only react to the final value once editing is complete. - @status current Introduced in 2.11.0 + @status current Introduced in 2.11.0, edited added in 2.11.5, floating added in 2.12.0 */ LROT_FUNCENTRY(numberEdit, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetNumberEdit(); }, true); }) /*luadoc @@ -1059,7 +1059,7 @@ LROT_BEGIN(lvgllib, NULL, 0) * `pos` (function) dynamic position callback returning `x, y` * `size` (function) dynamic size callback returning `w, h` * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, defaults to false + * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.12.0, defaults to false * `title` (string) text displayed in the popup menu's header, defaults to an empty string * `values` (table) simple table of option strings shown in the popup; can be changed via `lvgl.set()` since 2.11.6, defaults to an empty list * `get` (function) called when the popup is opened, to get the index of the currently selected option (1..number of values), defaults to nil @@ -1073,7 +1073,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @notice The popup closes and `set` is called when the user selects an item. @notice If the user taps outside the popup or presses RTN, the popup closes without calling `set`. - @status current Introduced in 2.11.0 + @status current Introduced in 2.11.0, values updatable via lvgl.set() added in 2.11.6, floating added in 2.12.0 */ LROT_FUNCENTRY(choice, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetChoice(); }, true); }) /*luadoc @@ -1094,7 +1094,7 @@ LROT_BEGIN(lvgllib, NULL, 0) * `pos` (function) dynamic position callback returning `x, y` * `size` (function) dynamic size callback returning `w, h` * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, defaults to false + * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.12.0, defaults to false * `min` (number) minimum value at the left end of the range, defaults to 0 * `max` (number) maximum value at the right end of the range, defaults to 100 * `get` (function) called to get the current knob value; should return a value between `min` and `max` inclusive, defaults to nil @@ -1103,7 +1103,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @retval table LVGL object - @status current Introduced in 2.11.0 + @status current Introduced in 2.11.0, floating added in 2.12.0 */ LROT_FUNCENTRY(slider, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetSlider(); }, true); }) /*luadoc @@ -1124,7 +1124,7 @@ LROT_BEGIN(lvgllib, NULL, 0) * `pos` (function) dynamic position callback returning `x, y` * `size` (function) dynamic size callback returning `w, h` * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, defaults to false + * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.12.0, defaults to false * `min` (number) minimum value at the bottom end of the range, defaults to 0 * `max` (number) maximum value at the top end of the range, defaults to 100 * `get` (function) called to get the current knob value; should return a value between `min` and `max` inclusive, defaults to nil @@ -1133,7 +1133,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @retval table LVGL object - @status current Introduced in 2.11.0 + @status current Introduced in 2.11.0, floating added in 2.12.0 */ LROT_FUNCENTRY(verticalSlider, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetVerticalSlider(); }, true); }) /*luadoc @@ -1152,7 +1152,7 @@ LROT_BEGIN(lvgllib, NULL, 0) * `pos` (function) dynamic position callback returning `x, y` * `size` (function) dynamic size callback returning `w, h` * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, defaults to false + * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.12.0, defaults to false * `get` (function) called when the popup opens, to get the currently selected font, defaults to nil * `set` (function) called when the user taps a font in the popup; passed the selected font value, defaults to nil * `active` (function) sets the enabled/disabled state; must return a boolean, true to enable, defaults to nil @@ -1162,7 +1162,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @notice The popup closes and `set` is called when the user selects an item. @notice If the user taps outside the popup or presses RTN, the popup closes without calling `set`. - @status current Introduced in 2.11.0 + @status current Introduced in 2.11.0, floating added in 2.12.0 */ LROT_FUNCENTRY(font, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetFontPicker(); }, true); }) /*luadoc @@ -1181,7 +1181,7 @@ LROT_BEGIN(lvgllib, NULL, 0) * `pos` (function) dynamic position callback returning `x, y` * `size` (function) dynamic size callback returning `w, h` * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, defaults to false + * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.12.0, defaults to false * `get` (function) called when the popup opens, to get the currently selected alignment, defaults to nil * `set` (function) called when the user taps an alignment in the popup; passed the selected alignment value, defaults to nil @@ -1190,7 +1190,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @notice The popup closes and `set` is called when the user selects an item. @notice If the user taps outside the popup or presses RTN, the popup closes without calling `set`. - @status current Introduced in 2.11.0 + @status current Introduced in 2.11.0, floating added in 2.12.0 */ LROT_FUNCENTRY(align, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetAlignPicker(); }, true); }) /*luadoc @@ -1209,7 +1209,7 @@ LROT_BEGIN(lvgllib, NULL, 0) * `pos` (function) dynamic position callback returning `x, y` * `size` (function) dynamic size callback returning `w, h` * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, defaults to false + * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.12.0, defaults to false * `get` (function) called when the picker opens, to get the currently selected color, defaults to nil * `set` (function) called when the user picks a color; passed the selected color value, defaults to nil @@ -1218,7 +1218,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @notice The popup closes and `set` is called when the user selects a color. @notice If the user taps outside the popup or presses RTN, the popup closes without calling `set`. - @status current Introduced in 2.11.0 + @status current Introduced in 2.11.0, floating added in 2.12.0 */ LROT_FUNCENTRY(color, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetColorPicker(); }, true); }) /*luadoc @@ -1237,7 +1237,7 @@ LROT_BEGIN(lvgllib, NULL, 0) * `pos` (function) dynamic position callback returning `x, y` * `size` (function) dynamic size callback returning `w, h` * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, defaults to false + * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.12.0, defaults to false * `get` (function) called when the popup opens, to get the currently selected timer, defaults to nil * `set` (function) called when the user taps a timer in the popup; passed the selected timer value, defaults to nil * `active` (function) sets the enabled/disabled state; must return a boolean, true to enable, defaults to nil @@ -1247,7 +1247,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @notice The popup closes and `set` is called when the user selects an item. @notice If the user taps outside the popup or presses RTN, the popup closes without calling `set`. - @status current Introduced in 2.11.0 + @status current Introduced in 2.11.0, floating added in 2.12.0 */ LROT_FUNCENTRY(timer, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetTimerPicker(); }, true); }) /*luadoc @@ -1266,7 +1266,7 @@ LROT_BEGIN(lvgllib, NULL, 0) * `pos` (function) dynamic position callback returning `x, y` * `size` (function) dynamic size callback returning `w, h` * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, defaults to false + * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.12.0, defaults to false * `get` (function) called when the popup opens, to get the currently selected switch, defaults to nil * `set` (function) called when the user picks a switch; passed the selected switch value, defaults to nil * `active` (function) sets the enabled/disabled state; must return a boolean, true to enable, defaults to nil @@ -1276,7 +1276,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @notice The popup closes and `set` is called when the user selects an item. @notice If the user taps outside the popup or presses RTN, the popup closes without calling `set`. - @status current Introduced in 2.11.0 + @status current Introduced in 2.11.0, floating added in 2.12.0 */ LROT_FUNCENTRY(switch, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetSwitchPicker(); }, true); }) /*luadoc @@ -1295,7 +1295,7 @@ LROT_BEGIN(lvgllib, NULL, 0) * `pos` (function) dynamic position callback returning `x, y` * `size` (function) dynamic size callback returning `w, h` * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, defaults to false + * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.12.0, defaults to false * `get` (function) called when the popup opens, to get the currently selected source, defaults to nil * `set` (function) called when the user picks a source; passed the selected source value, defaults to nil * `filter` (number) controls which source types the user can pick; combine `lvgl.SRC_xxx` constants to build a custom filter, defaults to `lvgl.SRC_ALL` @@ -1305,7 +1305,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @notice The popup closes and `set` is called when the user selects an item. @notice If the user taps outside the popup or presses RTN, the popup closes without calling `set`. - @status current Introduced in 2.11.0 + @status current Introduced in 2.11.0, floating added in 2.12.0 */ LROT_FUNCENTRY(source, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetSourcePicker(); }, true); }) /*luadoc @@ -1324,7 +1324,7 @@ LROT_BEGIN(lvgllib, NULL, 0) * `pos` (function) dynamic position callback returning `x, y` * `size` (function) dynamic size callback returning `w, h` * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, defaults to false + * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.12.0, defaults to false * `title` (string) text displayed in the popup's header, defaults to an empty string * `get` (function) called when the popup opens, to get the currently selected filename; must return a string, defaults to nil * `set` (function) called when the user picks a file; passed the selected filename (without path), defaults to nil @@ -1339,7 +1339,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @notice The popup closes and `set` is called when the user picks a file. @notice If the user taps outside the popup or presses RTN, the popup closes without calling `set`. - @status current Introduced in 2.11.0 + @status current Introduced in 2.11.0, floating added in 2.12.0 */ LROT_FUNCENTRY(file, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetFilePicker(); }, true); }) // Containers @@ -1359,7 +1359,7 @@ LROT_BEGIN(lvgllib, NULL, 0) * `pos` (function) dynamic position callback returning `x, y` * `size` (function) dynamic size callback returning `w, h` * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, defaults to false + * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.12.0, defaults to false * `flexFlow` (lvgl.FLOW_COLUMN or lvgl.FLOW_ROW) enables flex layout for this box, not used by default * `flexPad` (number) padding between rows/columns when flex layout is used; recommend using `lvgl.PAD_xxx` values, defaults to `PAD_OUTLINE` * `scrollBar` (boolean) enables/disables scroll bars, defaults to true @@ -1374,8 +1374,9 @@ LROT_BEGIN(lvgllib, NULL, 0) @notice The box is a helper for managing screen layouts. @notice When adding controls such as button/toggle/textEdit, leave enough space around them for the focus outline. @notice In a stand alone tool script, the box automatically adds scroll bars if child objects fall outside its boundaries; for widgets, out-of-bounds children are clipped instead. + @notice `scrollBar`, `scrollDir`, `scrolled`, and `scrollTo` were added in 2.12.0. - @status current Introduced in 2.11.0 + @status current Introduced in 2.11.0, align added in 2.11.4, borderPad added in 2.11.5, floating added in 2.12.0, scrollBar/scrollDir/scrolled/scrollTo added in 2.12.0 */ LROT_FUNCENTRY(box, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetBox(); }); }) /*luadoc @@ -1394,12 +1395,12 @@ LROT_BEGIN(lvgllib, NULL, 0) * `pos` (function) dynamic position callback returning `x, y` * `size` (function) dynamic size callback returning `w, h` * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, defaults to false + * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.12.0, defaults to false * `title` (string or function) text displayed on the left; function support added in 2.11.6, defaults to an empty string @retval table LVGL object - @status current Introduced in 2.11.0 + @status current Introduced in 2.11.0, title function support added in 2.11.6, floating added in 2.12.0 */ LROT_FUNCENTRY(setting, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetSetting(); }, true); }) /*luadoc @@ -1429,8 +1430,9 @@ LROT_BEGIN(lvgllib, NULL, 0) @notice The common object settings (x, y, w, h, color, etc.) are not used by `lvgl.page` -- only the settings listed above apply. @notice The page automatically adds scroll bars if child objects fall outside its boundaries. + @notice `scrollBar`, `scrollDir`, `scrolled`, and `scrollTo` were added in 2.12.0. - @status current Introduced in 2.11.0 + @status current Introduced in 2.11.0, title/subtitle function support, menu, prevButton, nextButton, align, and backButton added in 2.11.4, borderPad added in 2.11.5, scrollBar/scrollDir/scrolled/scrollTo added in 2.12.0 */ LROT_FUNCENTRY(page, [](lua_State* L) { return luaLvglObj(L, []() { return new LvglWidgetPage(); }, true); }) /*luadoc From 22c5d29e3329f6cb7687d04b8ef77ed30b9a8d9f Mon Sep 17 00:00:00 2001 From: Peter Feerick <5500713+pfeerick@users.noreply.github.com> Date: Mon, 7 Sep 2026 16:13:12 +1000 Subject: [PATCH 3/6] fix(lua): correct LVGL version citations to lowest-supporting release A prior commit on this branch "corrected" three version citations by checking `git tag --contains ` against a single commit found on the main/2.12 line. That method is unreliable here because 2.11 is a maintained LTS branch that continued shipping point releases well after 2.12.0 (2.11.6 and 2.11.7 both released after 2.12.0) -- a feature can be backported to 2.11.x as a separate commit with a different SHA, which `git tag --contains` on the original commit would never find. Direct verification against the actual tagged trees (not single-commit ancestry) gives different answers: - `floating`: present on both 2.11.6 (LTS backport) and 2.12.0. Per convention, cite the lowest version number that supports a feature, not whichever shipped chronologically first -- so 2.11.6, not the previously-written 2.12.0. - `scrollBar`/`scrollDir`/`scrolled`/`scrollTo` on lvgl.box/lvgl.page: actually present since 2.11.2 (verified via git grep across each 2.11.x tag), not 2.12.0 as the prior commit claimed -- that claim wasn't even present in the original source material being ported. - lvgl.build's named type constants: present since 2.11.4, matching the original source material; the prior commit's "correction" to 2.12.0 was itself the error. Comment-only change, no behavior change. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_015yCHydHbzZYCKpav38SonD --- radio/src/lua/api_colorlcd_lvgl.cpp | 118 ++++++++++++++-------------- 1 file changed, 59 insertions(+), 59 deletions(-) diff --git a/radio/src/lua/api_colorlcd_lvgl.cpp b/radio/src/lua/api_colorlcd_lvgl.cpp index c441ff12973..bccba552bef 100644 --- a/radio/src/lua/api_colorlcd_lvgl.cpp +++ b/radio/src/lua/api_colorlcd_lvgl.cpp @@ -458,7 +458,7 @@ Build a complex UI in a single operation from a table of object definitions. @param parent (object) optional LVGL object to attach the built objects to; if omitted they attach to the top-level script window @param params (table) a table of tables, each defining one LVGL object: - * `type` (string or type constant) mandatory, selects the kind of object to create, e.g. `"rectangle"` or `lvgl.RECTANGLE`; named type constants (e.g. `lvgl.RECTANGLE`) added in 2.12.0, string names work in all versions + * `type` (string or type constant) mandatory, selects the kind of object to create, e.g. `"rectangle"` or `lvgl.RECTANGLE`; named type constants (e.g. `lvgl.RECTANGLE`) added in 2.11.4, string names work in all versions * `name` (string) optional name used to look up this object in the returned table, defaults to an empty string * `children` (table) optional nested table of the same shape, to create child objects * any other key accepted by the constructor function for the chosen `type` @@ -468,7 +468,7 @@ Build a complex UI in a single operation from a table of object definitions. @notice Objects can be nested via `children`, another table of tables using the same shape as the top-level `params`. @notice Very large or deeply nested tables may fail to compile to `.luac` -- if a script works from `.lua` but fails from `.luac`, split the call into multiple smaller `lvgl.build()` calls. -@status current Introduced in 2.11.0, named type constants added in 2.12.0 +@status current Introduced in 2.11.0, named type constants added in 2.11.4 */ static int luaLvglBuild(lua_State *L) { @@ -621,14 +621,14 @@ LROT_BEGIN(lvgllib, NULL, 0) * `pos` (function) dynamic position callback returning `x, y` * `size` (function) dynamic size callback returning `w, h` * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.12.0, defaults to false + * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.11.6, defaults to false * `text` (string or function) text to display, defaults to an empty string * `font` (font value or function) sets the font size, e.g. `MIDSIZE`, `DBLSIZE`; defaults to `STDSIZE` * `align` (text alignment value or function) sets the text justification, e.g. `RIGHT`, `VCENTER`; defaults to `LEFT`. `RIGHT`/`CENTER` require `w` to be set. `LEFT`/`RIGHT`/`CENTER` align text horizontally within the label's bounding box `(x,y,w,h)`; `VCENTER`/`VTOP`/`VBOTTOM` align the label's bounding box vertically within the parent object @retval table LVGL object - @status current Introduced in 2.11.0, floating added in 2.12.0 + @status current Introduced in 2.11.0, floating added in 2.11.6 */ LROT_FUNCENTRY(label, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetLabel(); }); }) /*luadoc @@ -647,7 +647,7 @@ LROT_BEGIN(lvgllib, NULL, 0) * `pos` (function) dynamic position callback returning `x, y` * `size` (function) dynamic size callback returning `w, h` * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.12.0, defaults to false + * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.11.6, defaults to false * `thickness` (number) width of the border line, defaults to 1 * `filled` (boolean or function) if true the rectangle is filled with `color`, defaults to false (function support added in 2.11.4) * `rounded` (number) if greater than 0, rounds the corners with this radius; must be >= `thickness` if set, defaults to 0 @@ -657,7 +657,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @notice When used in a stand alone tool script, the rectangle automatically adds scroll bars if any child objects are placed outside its boundaries. For widgets, child objects outside the bounds are clipped instead. - @status current Introduced in 2.11.0, filled function support added in 2.11.4, floating added in 2.12.0 + @status current Introduced in 2.11.0, filled function support added in 2.11.4, floating added in 2.11.6 */ LROT_FUNCENTRY(rectangle, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetRectangle(); }); }) /*luadoc @@ -678,7 +678,7 @@ LROT_BEGIN(lvgllib, NULL, 0) * `pos` (function) dynamic position callback returning `x, y` * `size` (function) dynamic size callback returning `w, h` * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.12.0, defaults to false + * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.11.6, defaults to false * `rounded` (boolean) if true the line's end caps are rounded, defaults to false * `opacity` (number or function) opacity from 0 (transparent) to 255 (opaque), defaults to 255 * `dashGap` (number) gap size for dashed lines, defaults to 0 @@ -686,7 +686,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @retval table LVGL object - @status current Introduced in 2.11.0, floating added in 2.12.0 + @status current Introduced in 2.11.0, floating added in 2.11.6 */ LROT_FUNCENTRY(hline, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetHLine(); }); }) /*luadoc @@ -707,7 +707,7 @@ LROT_BEGIN(lvgllib, NULL, 0) * `pos` (function) dynamic position callback returning `x, y` * `size` (function) dynamic size callback returning `w, h` * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.12.0, defaults to false + * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.11.6, defaults to false * `rounded` (boolean) if true the line's end caps are rounded, defaults to false * `opacity` (number or function) opacity from 0 (transparent) to 255 (opaque), defaults to 255 * `dashGap` (number) gap size for dashed lines, defaults to 0 @@ -715,7 +715,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @retval table LVGL object - @status current Introduced in 2.11.0, floating added in 2.12.0 + @status current Introduced in 2.11.0, floating added in 2.11.6 */ LROT_FUNCENTRY(vline, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetVLine(); }); }) /*luadoc @@ -736,7 +736,7 @@ LROT_BEGIN(lvgllib, NULL, 0) * `pos` (function) dynamic position callback returning `x, y` * `size` (function) dynamic size callback returning `w, h` * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.12.0, defaults to false + * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.11.6, defaults to false * `rounded` (boolean) if true the line's end caps are rounded, defaults to false * `thickness` (number) thickness of each line segment, defaults to 1 * `opacity` (number or function) opacity from 0 (transparent) to 255 (opaque), defaults to 255 @@ -744,7 +744,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @retval table LVGL object - @status current Introduced in 2.11.0, floating added in 2.12.0 + @status current Introduced in 2.11.0, floating added in 2.11.6 */ LROT_FUNCENTRY(line, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetLine(); }); }) /*luadoc @@ -765,7 +765,7 @@ LROT_BEGIN(lvgllib, NULL, 0) * `pos` (function) dynamic position callback returning `x, y` * `size` (function) dynamic size callback returning `w, h` * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.12.0, defaults to false + * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.11.6, defaults to false * `opacity` (number or function) opacity from 0 (transparent) to 255 (opaque), defaults to 255 * `pts` (table or function) table of exactly three points, each a `{x, y}` pair, defaults to nil @@ -773,7 +773,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @notice Unlike the line-drawing objects, LVGL has no built-in triangle primitive. The drawing method used is simple and does not anti-alias. - @status current Introduced in 2.11.0, floating added in 2.12.0 + @status current Introduced in 2.11.0, floating added in 2.11.6 */ LROT_FUNCENTRY(triangle, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetTriangle(); }); }) /*luadoc @@ -794,7 +794,7 @@ LROT_BEGIN(lvgllib, NULL, 0) * `pos` (function) dynamic position callback returning `x, y` * `size` (function) dynamic size callback returning `w, h` * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.12.0, defaults to false + * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.11.6, defaults to false * `thickness` (number) width of the border line, defaults to 1 * `filled` (boolean) if true the circle is filled with `color`, defaults to false * `radius` (number or function) radius of the circle, defaults to 0 @@ -802,7 +802,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @retval table LVGL object - @status current Introduced in 2.11.0, floating added in 2.12.0 + @status current Introduced in 2.11.0, floating added in 2.11.6 */ LROT_FUNCENTRY(circle, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetCircle(); }); }) /*luadoc @@ -823,7 +823,7 @@ LROT_BEGIN(lvgllib, NULL, 0) * `pos` (function) dynamic position callback returning `x, y` * `size` (function) dynamic size callback returning `w, h` * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.12.0, defaults to false + * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.11.6, defaults to false * `thickness` (number) width of the arc's line, defaults to 1 * `radius` (number or function) radius of the arc, defaults to 0 * `startAngle` (number or function) starting angle in degrees (0-360), 0 is 3 o'clock, defaults to 0 @@ -837,7 +837,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @retval table LVGL object - @status current Introduced in 2.11.0, floating added in 2.12.0 + @status current Introduced in 2.11.0, floating added in 2.11.6 */ LROT_FUNCENTRY(arc, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetArc(); }); }) /*luadoc @@ -856,13 +856,13 @@ LROT_BEGIN(lvgllib, NULL, 0) * `pos` (function) dynamic position callback returning `x, y` * `size` (function) dynamic size callback returning `w, h` * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.12.0, defaults to false + * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.11.6, defaults to false * `file` (string) full path to the image file on the SD card, defaults to an empty string * `fill` (boolean) if true the image is scaled to completely fill the frame (may be cropped); if false it is scaled to fit entirely within the frame (may have empty borders), defaults to false @retval table LVGL object - @status current Introduced in 2.11.0, floating added in 2.12.0 + @status current Introduced in 2.11.0, floating added in 2.11.6 */ LROT_FUNCENTRY(image, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetImage(); }); }) /*luadoc @@ -883,13 +883,13 @@ LROT_BEGIN(lvgllib, NULL, 0) * `pos` (function) dynamic position callback returning `x, y` * `size` (function) dynamic size callback returning `w, h` * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.12.0, defaults to false + * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.11.6, defaults to false * `data` (string) URL or other content to encode, defaults to an empty string * `bgColor` (color) background color for the QR code image, defaults to `COLOR_THEME_SECONDARY3` @retval table LVGL object - @status current Introduced in 2.11.0, floating added in 2.12.0 + @status current Introduced in 2.11.0, floating added in 2.11.6 */ LROT_FUNCENTRY(qrcode, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetQRCode(); }); }) // Objects - standalone scripts and full screen widgets only @@ -909,7 +909,7 @@ LROT_BEGIN(lvgllib, NULL, 0) * `pos` (function) dynamic position callback returning `x, y` * `size` (function) dynamic size callback returning `w, h` * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.12.0, defaults to false + * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.11.6, defaults to false * `text` (string or function) text displayed in the button, defaults to an empty string * `press` (function) called when the user taps the button, after releasing ENTER or the screen; may optionally return a non-zero integer to display the button in the checked state, defaults to nil * `longpress` (function) called on a long tap; may optionally return a non-zero integer to display the button in the checked state, defaults to nil @@ -922,7 +922,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @retval table LVGL object - @status current Introduced in 2.11.0, floating added in 2.12.0 + @status current Introduced in 2.11.0, floating added in 2.11.6 */ LROT_FUNCENTRY(button, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetTextButton(); }, true); }) /*luadoc @@ -941,7 +941,7 @@ LROT_BEGIN(lvgllib, NULL, 0) * `pos` (function) dynamic position callback returning `x, y` * `size` (function) dynamic size callback returning `w, h` * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.12.0, defaults to false + * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.11.6, defaults to false * `text` (string or function) text displayed in the button, defaults to an empty string * `press` (function) called immediately when the user first taps the button or presses ENTER, defaults to nil * `release` (function) called when the user releases ENTER or stops touching the screen, defaults to nil @@ -955,7 +955,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @notice Unlike `lvgl.button`, `press` fires immediately on tap/press rather than on release. The button shows the checked state until ENTER is released or the screen is no longer touched. - @status current Introduced in 2.11.0, floating added in 2.12.0 + @status current Introduced in 2.11.0, floating added in 2.11.6 */ LROT_FUNCENTRY(momentaryButton, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetMomentaryButton(); }, true); }) /*luadoc @@ -974,14 +974,14 @@ LROT_BEGIN(lvgllib, NULL, 0) * `pos` (function) dynamic position callback returning `x, y` * `size` (function) dynamic size callback returning `w, h` * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.12.0, defaults to false + * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.11.6, defaults to false * `get` (function) called to get the current state; must return a boolean or number (0/false = off, 1/true = on), defaults to nil * `set` (function) called when the user interacts with the switch; passed a single number, 0 = off, 1 = on, defaults to nil * `active` (function) sets the enabled/disabled state; must return a boolean, true to enable, defaults to nil @retval table LVGL object - @status current Introduced in 2.11.0, floating added in 2.12.0 + @status current Introduced in 2.11.0, floating added in 2.11.6 */ LROT_FUNCENTRY(toggle, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetToggleSwitch(); }, true); }) /*luadoc @@ -1000,7 +1000,7 @@ LROT_BEGIN(lvgllib, NULL, 0) * `pos` (function) dynamic position callback returning `x, y` * `size` (function) dynamic size callback returning `w, h` * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.12.0, defaults to false + * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.11.6, defaults to false * `value` (string or function) text to edit; if a function, the text can be changed by both script and user, defaults to an empty string * `length` (number) maximum editable text length, 1 to 128, defaults to 32 * `set` (function) called when the user edits the text; passed the new string content, defaults to nil @@ -1008,7 +1008,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @retval table LVGL object - @status current Introduced in 2.11.0, floating added in 2.12.0 + @status current Introduced in 2.11.0, floating added in 2.11.6 */ LROT_FUNCENTRY(textEdit, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetTextEdit(); }, true); }) /*luadoc @@ -1027,7 +1027,7 @@ LROT_BEGIN(lvgllib, NULL, 0) * `pos` (function) dynamic position callback returning `x, y` * `size` (function) dynamic size callback returning `w, h` * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.12.0, defaults to false + * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.11.6, defaults to false * `get` (function) called to get the current value to display, defaults to nil * `set` (function) called for every change to the number while editing; passed the new value, defaults to nil * `edited` (function) called after the user finishes editing; passed the final value (added in 2.11.5), defaults to nil @@ -1040,7 +1040,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @notice Use `set` to react to every change during editing, or `edited` to only react to the final value once editing is complete. - @status current Introduced in 2.11.0, edited added in 2.11.5, floating added in 2.12.0 + @status current Introduced in 2.11.0, edited added in 2.11.5, floating added in 2.11.6 */ LROT_FUNCENTRY(numberEdit, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetNumberEdit(); }, true); }) /*luadoc @@ -1059,7 +1059,7 @@ LROT_BEGIN(lvgllib, NULL, 0) * `pos` (function) dynamic position callback returning `x, y` * `size` (function) dynamic size callback returning `w, h` * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.12.0, defaults to false + * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.11.6, defaults to false * `title` (string) text displayed in the popup menu's header, defaults to an empty string * `values` (table) simple table of option strings shown in the popup; can be changed via `lvgl.set()` since 2.11.6, defaults to an empty list * `get` (function) called when the popup is opened, to get the index of the currently selected option (1..number of values), defaults to nil @@ -1073,7 +1073,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @notice The popup closes and `set` is called when the user selects an item. @notice If the user taps outside the popup or presses RTN, the popup closes without calling `set`. - @status current Introduced in 2.11.0, values updatable via lvgl.set() added in 2.11.6, floating added in 2.12.0 + @status current Introduced in 2.11.0, values updatable via lvgl.set() added in 2.11.6, floating added in 2.11.6 */ LROT_FUNCENTRY(choice, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetChoice(); }, true); }) /*luadoc @@ -1094,7 +1094,7 @@ LROT_BEGIN(lvgllib, NULL, 0) * `pos` (function) dynamic position callback returning `x, y` * `size` (function) dynamic size callback returning `w, h` * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.12.0, defaults to false + * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.11.6, defaults to false * `min` (number) minimum value at the left end of the range, defaults to 0 * `max` (number) maximum value at the right end of the range, defaults to 100 * `get` (function) called to get the current knob value; should return a value between `min` and `max` inclusive, defaults to nil @@ -1103,7 +1103,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @retval table LVGL object - @status current Introduced in 2.11.0, floating added in 2.12.0 + @status current Introduced in 2.11.0, floating added in 2.11.6 */ LROT_FUNCENTRY(slider, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetSlider(); }, true); }) /*luadoc @@ -1124,7 +1124,7 @@ LROT_BEGIN(lvgllib, NULL, 0) * `pos` (function) dynamic position callback returning `x, y` * `size` (function) dynamic size callback returning `w, h` * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.12.0, defaults to false + * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.11.6, defaults to false * `min` (number) minimum value at the bottom end of the range, defaults to 0 * `max` (number) maximum value at the top end of the range, defaults to 100 * `get` (function) called to get the current knob value; should return a value between `min` and `max` inclusive, defaults to nil @@ -1133,7 +1133,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @retval table LVGL object - @status current Introduced in 2.11.0, floating added in 2.12.0 + @status current Introduced in 2.11.0, floating added in 2.11.6 */ LROT_FUNCENTRY(verticalSlider, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetVerticalSlider(); }, true); }) /*luadoc @@ -1152,7 +1152,7 @@ LROT_BEGIN(lvgllib, NULL, 0) * `pos` (function) dynamic position callback returning `x, y` * `size` (function) dynamic size callback returning `w, h` * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.12.0, defaults to false + * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.11.6, defaults to false * `get` (function) called when the popup opens, to get the currently selected font, defaults to nil * `set` (function) called when the user taps a font in the popup; passed the selected font value, defaults to nil * `active` (function) sets the enabled/disabled state; must return a boolean, true to enable, defaults to nil @@ -1162,7 +1162,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @notice The popup closes and `set` is called when the user selects an item. @notice If the user taps outside the popup or presses RTN, the popup closes without calling `set`. - @status current Introduced in 2.11.0, floating added in 2.12.0 + @status current Introduced in 2.11.0, floating added in 2.11.6 */ LROT_FUNCENTRY(font, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetFontPicker(); }, true); }) /*luadoc @@ -1181,7 +1181,7 @@ LROT_BEGIN(lvgllib, NULL, 0) * `pos` (function) dynamic position callback returning `x, y` * `size` (function) dynamic size callback returning `w, h` * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.12.0, defaults to false + * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.11.6, defaults to false * `get` (function) called when the popup opens, to get the currently selected alignment, defaults to nil * `set` (function) called when the user taps an alignment in the popup; passed the selected alignment value, defaults to nil @@ -1190,7 +1190,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @notice The popup closes and `set` is called when the user selects an item. @notice If the user taps outside the popup or presses RTN, the popup closes without calling `set`. - @status current Introduced in 2.11.0, floating added in 2.12.0 + @status current Introduced in 2.11.0, floating added in 2.11.6 */ LROT_FUNCENTRY(align, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetAlignPicker(); }, true); }) /*luadoc @@ -1209,7 +1209,7 @@ LROT_BEGIN(lvgllib, NULL, 0) * `pos` (function) dynamic position callback returning `x, y` * `size` (function) dynamic size callback returning `w, h` * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.12.0, defaults to false + * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.11.6, defaults to false * `get` (function) called when the picker opens, to get the currently selected color, defaults to nil * `set` (function) called when the user picks a color; passed the selected color value, defaults to nil @@ -1218,7 +1218,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @notice The popup closes and `set` is called when the user selects a color. @notice If the user taps outside the popup or presses RTN, the popup closes without calling `set`. - @status current Introduced in 2.11.0, floating added in 2.12.0 + @status current Introduced in 2.11.0, floating added in 2.11.6 */ LROT_FUNCENTRY(color, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetColorPicker(); }, true); }) /*luadoc @@ -1237,7 +1237,7 @@ LROT_BEGIN(lvgllib, NULL, 0) * `pos` (function) dynamic position callback returning `x, y` * `size` (function) dynamic size callback returning `w, h` * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.12.0, defaults to false + * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.11.6, defaults to false * `get` (function) called when the popup opens, to get the currently selected timer, defaults to nil * `set` (function) called when the user taps a timer in the popup; passed the selected timer value, defaults to nil * `active` (function) sets the enabled/disabled state; must return a boolean, true to enable, defaults to nil @@ -1247,7 +1247,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @notice The popup closes and `set` is called when the user selects an item. @notice If the user taps outside the popup or presses RTN, the popup closes without calling `set`. - @status current Introduced in 2.11.0, floating added in 2.12.0 + @status current Introduced in 2.11.0, floating added in 2.11.6 */ LROT_FUNCENTRY(timer, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetTimerPicker(); }, true); }) /*luadoc @@ -1266,7 +1266,7 @@ LROT_BEGIN(lvgllib, NULL, 0) * `pos` (function) dynamic position callback returning `x, y` * `size` (function) dynamic size callback returning `w, h` * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.12.0, defaults to false + * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.11.6, defaults to false * `get` (function) called when the popup opens, to get the currently selected switch, defaults to nil * `set` (function) called when the user picks a switch; passed the selected switch value, defaults to nil * `active` (function) sets the enabled/disabled state; must return a boolean, true to enable, defaults to nil @@ -1276,7 +1276,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @notice The popup closes and `set` is called when the user selects an item. @notice If the user taps outside the popup or presses RTN, the popup closes without calling `set`. - @status current Introduced in 2.11.0, floating added in 2.12.0 + @status current Introduced in 2.11.0, floating added in 2.11.6 */ LROT_FUNCENTRY(switch, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetSwitchPicker(); }, true); }) /*luadoc @@ -1295,7 +1295,7 @@ LROT_BEGIN(lvgllib, NULL, 0) * `pos` (function) dynamic position callback returning `x, y` * `size` (function) dynamic size callback returning `w, h` * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.12.0, defaults to false + * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.11.6, defaults to false * `get` (function) called when the popup opens, to get the currently selected source, defaults to nil * `set` (function) called when the user picks a source; passed the selected source value, defaults to nil * `filter` (number) controls which source types the user can pick; combine `lvgl.SRC_xxx` constants to build a custom filter, defaults to `lvgl.SRC_ALL` @@ -1305,7 +1305,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @notice The popup closes and `set` is called when the user selects an item. @notice If the user taps outside the popup or presses RTN, the popup closes without calling `set`. - @status current Introduced in 2.11.0, floating added in 2.12.0 + @status current Introduced in 2.11.0, floating added in 2.11.6 */ LROT_FUNCENTRY(source, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetSourcePicker(); }, true); }) /*luadoc @@ -1324,7 +1324,7 @@ LROT_BEGIN(lvgllib, NULL, 0) * `pos` (function) dynamic position callback returning `x, y` * `size` (function) dynamic size callback returning `w, h` * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.12.0, defaults to false + * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.11.6, defaults to false * `title` (string) text displayed in the popup's header, defaults to an empty string * `get` (function) called when the popup opens, to get the currently selected filename; must return a string, defaults to nil * `set` (function) called when the user picks a file; passed the selected filename (without path), defaults to nil @@ -1339,7 +1339,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @notice The popup closes and `set` is called when the user picks a file. @notice If the user taps outside the popup or presses RTN, the popup closes without calling `set`. - @status current Introduced in 2.11.0, floating added in 2.12.0 + @status current Introduced in 2.11.0, floating added in 2.11.6 */ LROT_FUNCENTRY(file, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetFilePicker(); }, true); }) // Containers @@ -1359,7 +1359,7 @@ LROT_BEGIN(lvgllib, NULL, 0) * `pos` (function) dynamic position callback returning `x, y` * `size` (function) dynamic size callback returning `w, h` * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.12.0, defaults to false + * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.11.6, defaults to false * `flexFlow` (lvgl.FLOW_COLUMN or lvgl.FLOW_ROW) enables flex layout for this box, not used by default * `flexPad` (number) padding between rows/columns when flex layout is used; recommend using `lvgl.PAD_xxx` values, defaults to `PAD_OUTLINE` * `scrollBar` (boolean) enables/disables scroll bars, defaults to true @@ -1374,9 +1374,9 @@ LROT_BEGIN(lvgllib, NULL, 0) @notice The box is a helper for managing screen layouts. @notice When adding controls such as button/toggle/textEdit, leave enough space around them for the focus outline. @notice In a stand alone tool script, the box automatically adds scroll bars if child objects fall outside its boundaries; for widgets, out-of-bounds children are clipped instead. - @notice `scrollBar`, `scrollDir`, `scrolled`, and `scrollTo` were added in 2.12.0. + @notice `scrollBar`, `scrollDir`, `scrolled`, and `scrollTo` were added in 2.11.2. - @status current Introduced in 2.11.0, align added in 2.11.4, borderPad added in 2.11.5, floating added in 2.12.0, scrollBar/scrollDir/scrolled/scrollTo added in 2.12.0 + @status current Introduced in 2.11.0, align added in 2.11.4, borderPad added in 2.11.5, floating added in 2.11.6, scrollBar/scrollDir/scrolled/scrollTo added in 2.11.2 */ LROT_FUNCENTRY(box, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetBox(); }); }) /*luadoc @@ -1395,12 +1395,12 @@ LROT_BEGIN(lvgllib, NULL, 0) * `pos` (function) dynamic position callback returning `x, y` * `size` (function) dynamic size callback returning `w, h` * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.12.0, defaults to false + * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.11.6, defaults to false * `title` (string or function) text displayed on the left; function support added in 2.11.6, defaults to an empty string @retval table LVGL object - @status current Introduced in 2.11.0, title function support added in 2.11.6, floating added in 2.12.0 + @status current Introduced in 2.11.0, title function support added in 2.11.6, floating added in 2.11.6 */ LROT_FUNCENTRY(setting, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetSetting(); }, true); }) /*luadoc @@ -1430,9 +1430,9 @@ LROT_BEGIN(lvgllib, NULL, 0) @notice The common object settings (x, y, w, h, color, etc.) are not used by `lvgl.page` -- only the settings listed above apply. @notice The page automatically adds scroll bars if child objects fall outside its boundaries. - @notice `scrollBar`, `scrollDir`, `scrolled`, and `scrollTo` were added in 2.12.0. + @notice `scrollBar`, `scrollDir`, `scrolled`, and `scrollTo` were added in 2.11.2. - @status current Introduced in 2.11.0, title/subtitle function support, menu, prevButton, nextButton, align, and backButton added in 2.11.4, borderPad added in 2.11.5, scrollBar/scrollDir/scrolled/scrollTo added in 2.12.0 + @status current Introduced in 2.11.0, title/subtitle function support, menu, prevButton, nextButton, align, and backButton added in 2.11.4, borderPad added in 2.11.5, scrollBar/scrollDir/scrolled/scrollTo added in 2.11.2 */ LROT_FUNCENTRY(page, [](lua_State* L) { return luaLvglObj(L, []() { return new LvglWidgetPage(); }, true); }) /*luadoc From b42d336ad3274e10eadb64073eb4d9f095f0aecb Mon Sep 17 00:00:00 2001 From: Peter Feerick <5500713+pfeerick@users.noreply.github.com> Date: Mon, 7 Sep 2026 16:27:48 +1000 Subject: [PATCH 4/6] refactor(lua): deduplicate LVGL common object properties via @commonparams The 9-line "common object properties" bullet list (x, y, w, h, color, pos, size, visible, floating) was repeated verbatim across all 27 widget-constructor luadoc comments in this file. A companion doc-pipeline change (jimb40/lua-reference-guide#7) adds @common/ @commonparams luadoc tags specifically to eliminate this: define the shared block once with @common, reference it from each widget with @commonparams, and the extractor splices it back in at build time -- so generated documentation is unchanged, but a future edit to a common property only needs to happen in one place. Verified: re-extracting and re-rendering this file's content with the new pipeline support produces output identical to before this refactor (only source line numbers and a generation timestamp differ, both expected side effects of inserting the new @common block). Comment-only change, no behavior change. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_015yCHydHbzZYCKpav38SonD --- radio/src/lua/api_colorlcd_lvgl.cpp | 279 ++++------------------------ 1 file changed, 38 insertions(+), 241 deletions(-) diff --git a/radio/src/lua/api_colorlcd_lvgl.cpp b/radio/src/lua/api_colorlcd_lvgl.cpp index bccba552bef..7293feb4027 100644 --- a/radio/src/lua/api_colorlcd_lvgl.cpp +++ b/radio/src/lua/api_colorlcd_lvgl.cpp @@ -604,15 +604,9 @@ LROT_BEGIN(lvgllib, NULL, 0) LROT_FUNCENTRY(isFullScreen, luaLvglIsFullscreen) LROT_FUNCENTRY(exitFullScreen, luaLvglExitFullscreen) LROT_FUNCENTRY(getContext, luaLvglGetContext) - // Objects - widgets and standalone scripts /*luadoc - @function lvgl.label([parent, ]params) - - Display a text label. + @common lvgl_object - @param parent (object) optional LVGL object to attach the new object to; if omitted the object is created in the top-level script window - - @param params (table): * `x` (number) position relative to the top-left of the parent * `y` (number) position relative to the top-left of the parent * `w` (number) width @@ -622,6 +616,17 @@ LROT_BEGIN(lvgllib, NULL, 0) * `size` (function) dynamic size callback returning `w, h` * `visible` (function) dynamic visibility callback * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.11.6, defaults to false + */ + // Objects - widgets and standalone scripts + /*luadoc + @function lvgl.label([parent, ]params) + + Display a text label. + + @param parent (object) optional LVGL object to attach the new object to; if omitted the object is created in the top-level script window + + @param params (table): + @commonparams lvgl_object * `text` (string or function) text to display, defaults to an empty string * `font` (font value or function) sets the font size, e.g. `MIDSIZE`, `DBLSIZE`; defaults to `STDSIZE` * `align` (text alignment value or function) sets the text justification, e.g. `RIGHT`, `VCENTER`; defaults to `LEFT`. `RIGHT`/`CENTER` require `w` to be set. `LEFT`/`RIGHT`/`CENTER` align text horizontally within the label's bounding box `(x,y,w,h)`; `VCENTER`/`VTOP`/`VBOTTOM` align the label's bounding box vertically within the parent object @@ -639,15 +644,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @param parent (object) optional LVGL object to attach the new object to; if omitted the object is created in the top-level script window @param params (table): - * `x` (number) position relative to the top-left of the parent - * `y` (number) position relative to the top-left of the parent - * `w` (number) width - * `h` (number) height - * `color` (color or function) primary color for the object - * `pos` (function) dynamic position callback returning `x, y` - * `size` (function) dynamic size callback returning `w, h` - * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.11.6, defaults to false + @commonparams lvgl_object * `thickness` (number) width of the border line, defaults to 1 * `filled` (boolean or function) if true the rectangle is filled with `color`, defaults to false (function support added in 2.11.4) * `rounded` (number) if greater than 0, rounds the corners with this radius; must be >= `thickness` if set, defaults to 0 @@ -670,15 +667,7 @@ LROT_BEGIN(lvgllib, NULL, 0) `w` sets the length of the line; `h` sets its thickness. @param params (table): - * `x` (number) position relative to the top-left of the parent - * `y` (number) position relative to the top-left of the parent - * `w` (number) width - * `h` (number) height - * `color` (color or function) primary color for the object - * `pos` (function) dynamic position callback returning `x, y` - * `size` (function) dynamic size callback returning `w, h` - * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.11.6, defaults to false + @commonparams lvgl_object * `rounded` (boolean) if true the line's end caps are rounded, defaults to false * `opacity` (number or function) opacity from 0 (transparent) to 255 (opaque), defaults to 255 * `dashGap` (number) gap size for dashed lines, defaults to 0 @@ -699,15 +688,7 @@ LROT_BEGIN(lvgllib, NULL, 0) `h` sets the length of the line; `w` sets its thickness. @param params (table): - * `x` (number) position relative to the top-left of the parent - * `y` (number) position relative to the top-left of the parent - * `w` (number) width - * `h` (number) height - * `color` (color or function) primary color for the object - * `pos` (function) dynamic position callback returning `x, y` - * `size` (function) dynamic size callback returning `w, h` - * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.11.6, defaults to false + @commonparams lvgl_object * `rounded` (boolean) if true the line's end caps are rounded, defaults to false * `opacity` (number or function) opacity from 0 (transparent) to 255 (opaque), defaults to 255 * `dashGap` (number) gap size for dashed lines, defaults to 0 @@ -728,15 +709,7 @@ LROT_BEGIN(lvgllib, NULL, 0) `x`, `y`, `w`, and `h` are not used. @param params (table): - * `x` (number) position relative to the top-left of the parent - * `y` (number) position relative to the top-left of the parent - * `w` (number) width - * `h` (number) height - * `color` (color or function) primary color for the object - * `pos` (function) dynamic position callback returning `x, y` - * `size` (function) dynamic size callback returning `w, h` - * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.11.6, defaults to false + @commonparams lvgl_object * `rounded` (boolean) if true the line's end caps are rounded, defaults to false * `thickness` (number) thickness of each line segment, defaults to 1 * `opacity` (number or function) opacity from 0 (transparent) to 255 (opaque), defaults to 255 @@ -757,15 +730,7 @@ LROT_BEGIN(lvgllib, NULL, 0) `x`, `y`, `w`, and `h` are not used. @param params (table): - * `x` (number) position relative to the top-left of the parent - * `y` (number) position relative to the top-left of the parent - * `w` (number) width - * `h` (number) height - * `color` (color or function) primary color for the object - * `pos` (function) dynamic position callback returning `x, y` - * `size` (function) dynamic size callback returning `w, h` - * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.11.6, defaults to false + @commonparams lvgl_object * `opacity` (number or function) opacity from 0 (transparent) to 255 (opaque), defaults to 255 * `pts` (table or function) table of exactly three points, each a `{x, y}` pair, defaults to nil @@ -786,15 +751,7 @@ LROT_BEGIN(lvgllib, NULL, 0) `w`, `h`, and `size` should not be used with `lvgl.circle` -- use `radius` instead. @param params (table): - * `x` (number) position relative to the top-left of the parent - * `y` (number) position relative to the top-left of the parent - * `w` (number) width - * `h` (number) height - * `color` (color or function) primary color for the object - * `pos` (function) dynamic position callback returning `x, y` - * `size` (function) dynamic size callback returning `w, h` - * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.11.6, defaults to false + @commonparams lvgl_object * `thickness` (number) width of the border line, defaults to 1 * `filled` (boolean) if true the circle is filled with `color`, defaults to false * `radius` (number or function) radius of the circle, defaults to 0 @@ -815,15 +772,7 @@ LROT_BEGIN(lvgllib, NULL, 0) `w`, `h`, and `size` should not be used with `lvgl.arc` -- use `radius` instead. @param params (table): - * `x` (number) position relative to the top-left of the parent - * `y` (number) position relative to the top-left of the parent - * `w` (number) width - * `h` (number) height - * `color` (color or function) primary color for the object - * `pos` (function) dynamic position callback returning `x, y` - * `size` (function) dynamic size callback returning `w, h` - * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.11.6, defaults to false + @commonparams lvgl_object * `thickness` (number) width of the arc's line, defaults to 1 * `radius` (number or function) radius of the arc, defaults to 0 * `startAngle` (number or function) starting angle in degrees (0-360), 0 is 3 o'clock, defaults to 0 @@ -848,15 +797,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @param parent (object) optional LVGL object to attach the new object to; if omitted the object is created in the top-level script window @param params (table): - * `x` (number) position relative to the top-left of the parent - * `y` (number) position relative to the top-left of the parent - * `w` (number) width - * `h` (number) height - * `color` (color or function) primary color for the object - * `pos` (function) dynamic position callback returning `x, y` - * `size` (function) dynamic size callback returning `w, h` - * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.11.6, defaults to false + @commonparams lvgl_object * `file` (string) full path to the image file on the SD card, defaults to an empty string * `fill` (boolean) if true the image is scaled to completely fill the frame (may be cropped); if false it is scaled to fit entirely within the frame (may have empty borders), defaults to false @@ -875,15 +816,7 @@ LROT_BEGIN(lvgllib, NULL, 0) `w` and `h` should be set to the same value for a QR code. @param params (table): - * `x` (number) position relative to the top-left of the parent - * `y` (number) position relative to the top-left of the parent - * `w` (number) width - * `h` (number) height - * `color` (color or function) primary color for the object - * `pos` (function) dynamic position callback returning `x, y` - * `size` (function) dynamic size callback returning `w, h` - * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.11.6, defaults to false + @commonparams lvgl_object * `data` (string) URL or other content to encode, defaults to an empty string * `bgColor` (color) background color for the QR code image, defaults to `COLOR_THEME_SECONDARY3` @@ -901,15 +834,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @param parent (object) optional LVGL object to attach the new object to; if omitted the object is created in the top-level script window @param params (table): - * `x` (number) position relative to the top-left of the parent - * `y` (number) position relative to the top-left of the parent - * `w` (number) width - * `h` (number) height - * `color` (color or function) primary color for the object - * `pos` (function) dynamic position callback returning `x, y` - * `size` (function) dynamic size callback returning `w, h` - * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.11.6, defaults to false + @commonparams lvgl_object * `text` (string or function) text displayed in the button, defaults to an empty string * `press` (function) called when the user taps the button, after releasing ENTER or the screen; may optionally return a non-zero integer to display the button in the checked state, defaults to nil * `longpress` (function) called on a long tap; may optionally return a non-zero integer to display the button in the checked state, defaults to nil @@ -933,15 +858,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @param parent (object) optional LVGL object to attach the new object to; if omitted the object is created in the top-level script window @param params (table): - * `x` (number) position relative to the top-left of the parent - * `y` (number) position relative to the top-left of the parent - * `w` (number) width - * `h` (number) height - * `color` (color or function) primary color for the object - * `pos` (function) dynamic position callback returning `x, y` - * `size` (function) dynamic size callback returning `w, h` - * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.11.6, defaults to false + @commonparams lvgl_object * `text` (string or function) text displayed in the button, defaults to an empty string * `press` (function) called immediately when the user first taps the button or presses ENTER, defaults to nil * `release` (function) called when the user releases ENTER or stops touching the screen, defaults to nil @@ -966,15 +883,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @param parent (object) optional LVGL object to attach the new object to; if omitted the object is created in the top-level script window @param params (table): - * `x` (number) position relative to the top-left of the parent - * `y` (number) position relative to the top-left of the parent - * `w` (number) width - * `h` (number) height - * `color` (color or function) primary color for the object - * `pos` (function) dynamic position callback returning `x, y` - * `size` (function) dynamic size callback returning `w, h` - * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.11.6, defaults to false + @commonparams lvgl_object * `get` (function) called to get the current state; must return a boolean or number (0/false = off, 1/true = on), defaults to nil * `set` (function) called when the user interacts with the switch; passed a single number, 0 = off, 1 = on, defaults to nil * `active` (function) sets the enabled/disabled state; must return a boolean, true to enable, defaults to nil @@ -992,15 +901,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @param parent (object) optional LVGL object to attach the new object to; if omitted the object is created in the top-level script window @param params (table): - * `x` (number) position relative to the top-left of the parent - * `y` (number) position relative to the top-left of the parent - * `w` (number) width - * `h` (number) height - * `color` (color or function) primary color for the object - * `pos` (function) dynamic position callback returning `x, y` - * `size` (function) dynamic size callback returning `w, h` - * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.11.6, defaults to false + @commonparams lvgl_object * `value` (string or function) text to edit; if a function, the text can be changed by both script and user, defaults to an empty string * `length` (number) maximum editable text length, 1 to 128, defaults to 32 * `set` (function) called when the user edits the text; passed the new string content, defaults to nil @@ -1019,15 +920,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @param parent (object) optional LVGL object to attach the new object to; if omitted the object is created in the top-level script window @param params (table): - * `x` (number) position relative to the top-left of the parent - * `y` (number) position relative to the top-left of the parent - * `w` (number) width - * `h` (number) height - * `color` (color or function) primary color for the object - * `pos` (function) dynamic position callback returning `x, y` - * `size` (function) dynamic size callback returning `w, h` - * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.11.6, defaults to false + @commonparams lvgl_object * `get` (function) called to get the current value to display, defaults to nil * `set` (function) called for every change to the number while editing; passed the new value, defaults to nil * `edited` (function) called after the user finishes editing; passed the final value (added in 2.11.5), defaults to nil @@ -1051,15 +944,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @param parent (object) optional LVGL object to attach the new object to; if omitted the object is created in the top-level script window @param params (table): - * `x` (number) position relative to the top-left of the parent - * `y` (number) position relative to the top-left of the parent - * `w` (number) width - * `h` (number) height - * `color` (color or function) primary color for the object - * `pos` (function) dynamic position callback returning `x, y` - * `size` (function) dynamic size callback returning `w, h` - * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.11.6, defaults to false + @commonparams lvgl_object * `title` (string) text displayed in the popup menu's header, defaults to an empty string * `values` (table) simple table of option strings shown in the popup; can be changed via `lvgl.set()` since 2.11.6, defaults to an empty list * `get` (function) called when the popup is opened, to get the index of the currently selected option (1..number of values), defaults to nil @@ -1086,15 +971,7 @@ LROT_BEGIN(lvgllib, NULL, 0) `w` sets the size of the slider; `h` is not used. @param params (table): - * `x` (number) position relative to the top-left of the parent - * `y` (number) position relative to the top-left of the parent - * `w` (number) width - * `h` (number) height - * `color` (color or function) primary color for the object - * `pos` (function) dynamic position callback returning `x, y` - * `size` (function) dynamic size callback returning `w, h` - * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.11.6, defaults to false + @commonparams lvgl_object * `min` (number) minimum value at the left end of the range, defaults to 0 * `max` (number) maximum value at the right end of the range, defaults to 100 * `get` (function) called to get the current knob value; should return a value between `min` and `max` inclusive, defaults to nil @@ -1116,15 +993,7 @@ LROT_BEGIN(lvgllib, NULL, 0) `h` sets the size of the slider; `w` is not used. @param params (table): - * `x` (number) position relative to the top-left of the parent - * `y` (number) position relative to the top-left of the parent - * `w` (number) width - * `h` (number) height - * `color` (color or function) primary color for the object - * `pos` (function) dynamic position callback returning `x, y` - * `size` (function) dynamic size callback returning `w, h` - * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.11.6, defaults to false + @commonparams lvgl_object * `min` (number) minimum value at the bottom end of the range, defaults to 0 * `max` (number) maximum value at the top end of the range, defaults to 100 * `get` (function) called to get the current knob value; should return a value between `min` and `max` inclusive, defaults to nil @@ -1144,15 +1013,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @param parent (object) optional LVGL object to attach the new object to; if omitted the object is created in the top-level script window @param params (table): - * `x` (number) position relative to the top-left of the parent - * `y` (number) position relative to the top-left of the parent - * `w` (number) width - * `h` (number) height - * `color` (color or function) primary color for the object - * `pos` (function) dynamic position callback returning `x, y` - * `size` (function) dynamic size callback returning `w, h` - * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.11.6, defaults to false + @commonparams lvgl_object * `get` (function) called when the popup opens, to get the currently selected font, defaults to nil * `set` (function) called when the user taps a font in the popup; passed the selected font value, defaults to nil * `active` (function) sets the enabled/disabled state; must return a boolean, true to enable, defaults to nil @@ -1173,15 +1034,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @param parent (object) optional LVGL object to attach the new object to; if omitted the object is created in the top-level script window @param params (table): - * `x` (number) position relative to the top-left of the parent - * `y` (number) position relative to the top-left of the parent - * `w` (number) width - * `h` (number) height - * `color` (color or function) primary color for the object - * `pos` (function) dynamic position callback returning `x, y` - * `size` (function) dynamic size callback returning `w, h` - * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.11.6, defaults to false + @commonparams lvgl_object * `get` (function) called when the popup opens, to get the currently selected alignment, defaults to nil * `set` (function) called when the user taps an alignment in the popup; passed the selected alignment value, defaults to nil @@ -1201,15 +1054,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @param parent (object) optional LVGL object to attach the new object to; if omitted the object is created in the top-level script window @param params (table): - * `x` (number) position relative to the top-left of the parent - * `y` (number) position relative to the top-left of the parent - * `w` (number) width - * `h` (number) height - * `color` (color or function) primary color for the object - * `pos` (function) dynamic position callback returning `x, y` - * `size` (function) dynamic size callback returning `w, h` - * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.11.6, defaults to false + @commonparams lvgl_object * `get` (function) called when the picker opens, to get the currently selected color, defaults to nil * `set` (function) called when the user picks a color; passed the selected color value, defaults to nil @@ -1229,15 +1074,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @param parent (object) optional LVGL object to attach the new object to; if omitted the object is created in the top-level script window @param params (table): - * `x` (number) position relative to the top-left of the parent - * `y` (number) position relative to the top-left of the parent - * `w` (number) width - * `h` (number) height - * `color` (color or function) primary color for the object - * `pos` (function) dynamic position callback returning `x, y` - * `size` (function) dynamic size callback returning `w, h` - * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.11.6, defaults to false + @commonparams lvgl_object * `get` (function) called when the popup opens, to get the currently selected timer, defaults to nil * `set` (function) called when the user taps a timer in the popup; passed the selected timer value, defaults to nil * `active` (function) sets the enabled/disabled state; must return a boolean, true to enable, defaults to nil @@ -1258,15 +1095,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @param parent (object) optional LVGL object to attach the new object to; if omitted the object is created in the top-level script window @param params (table): - * `x` (number) position relative to the top-left of the parent - * `y` (number) position relative to the top-left of the parent - * `w` (number) width - * `h` (number) height - * `color` (color or function) primary color for the object - * `pos` (function) dynamic position callback returning `x, y` - * `size` (function) dynamic size callback returning `w, h` - * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.11.6, defaults to false + @commonparams lvgl_object * `get` (function) called when the popup opens, to get the currently selected switch, defaults to nil * `set` (function) called when the user picks a switch; passed the selected switch value, defaults to nil * `active` (function) sets the enabled/disabled state; must return a boolean, true to enable, defaults to nil @@ -1287,15 +1116,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @param parent (object) optional LVGL object to attach the new object to; if omitted the object is created in the top-level script window @param params (table): - * `x` (number) position relative to the top-left of the parent - * `y` (number) position relative to the top-left of the parent - * `w` (number) width - * `h` (number) height - * `color` (color or function) primary color for the object - * `pos` (function) dynamic position callback returning `x, y` - * `size` (function) dynamic size callback returning `w, h` - * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.11.6, defaults to false + @commonparams lvgl_object * `get` (function) called when the popup opens, to get the currently selected source, defaults to nil * `set` (function) called when the user picks a source; passed the selected source value, defaults to nil * `filter` (number) controls which source types the user can pick; combine `lvgl.SRC_xxx` constants to build a custom filter, defaults to `lvgl.SRC_ALL` @@ -1316,15 +1137,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @param parent (object) optional LVGL object to attach the new object to; if omitted the object is created in the top-level script window @param params (table): - * `x` (number) position relative to the top-left of the parent - * `y` (number) position relative to the top-left of the parent - * `w` (number) width - * `h` (number) height - * `color` (color or function) primary color for the object - * `pos` (function) dynamic position callback returning `x, y` - * `size` (function) dynamic size callback returning `w, h` - * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.11.6, defaults to false + @commonparams lvgl_object * `title` (string) text displayed in the popup's header, defaults to an empty string * `get` (function) called when the popup opens, to get the currently selected filename; must return a string, defaults to nil * `set` (function) called when the user picks a file; passed the selected filename (without path), defaults to nil @@ -1351,15 +1164,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @param parent (object) optional LVGL object to attach the new object to; if omitted the object is created in the top-level script window @param params (table): - * `x` (number) position relative to the top-left of the parent - * `y` (number) position relative to the top-left of the parent - * `w` (number) width - * `h` (number) height - * `color` (color or function) primary color for the object - * `pos` (function) dynamic position callback returning `x, y` - * `size` (function) dynamic size callback returning `w, h` - * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.11.6, defaults to false + @commonparams lvgl_object * `flexFlow` (lvgl.FLOW_COLUMN or lvgl.FLOW_ROW) enables flex layout for this box, not used by default * `flexPad` (number) padding between rows/columns when flex layout is used; recommend using `lvgl.PAD_xxx` values, defaults to `PAD_OUTLINE` * `scrollBar` (boolean) enables/disables scroll bars, defaults to true @@ -1387,15 +1192,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @param parent (object) optional LVGL object to attach the new object to; if omitted the object is created in the top-level script window @param params (table): - * `x` (number) position relative to the top-left of the parent - * `y` (number) position relative to the top-left of the parent - * `w` (number) width - * `h` (number) height - * `color` (color or function) primary color for the object - * `pos` (function) dynamic position callback returning `x, y` - * `size` (function) dynamic size callback returning `w, h` - * `visible` (function) dynamic visibility callback - * `floating` (boolean) keep the object fixed inside a scrollable container, added in 2.11.6, defaults to false + @commonparams lvgl_object * `title` (string or function) text displayed on the left; function support added in 2.11.6, defaults to an empty string @retval table LVGL object From 2bcb79048b16e59f7016f8808a10f7bee14205c4 Mon Sep 17 00:00:00 2001 From: Peter Feerick <5500713+pfeerick@users.noreply.github.com> Date: Mon, 7 Sep 2026 22:34:11 +1000 Subject: [PATCH 5/6] fix(lua): correct 11 accuracy issues in LVGL luadoc found by review An independent accuracy review checked every annotated function against the actual C++ implementation and the live official guide, and found: - lvgl.enable/disable/close: "Introduced in current" -> 2.11.0 (all three registered in the lvgl table since v2.11.0; simply undocumented on the official guide, hence no version to port) - lvgl.message: `details` param retyped function -> string, matching luaL_checkstring in LvglWidgetMessageDialog::parseParam - lvgl.switch: added the missing `filter` param (parsed in LvglWidgetSwitchPicker::parseParam, mirrors lvgl.source's filter) - lvgl.dialog: `flexPad` default corrected 0 -> PAD_OUTLINE, matching the shared LvglWidgetObject base member's actual default - lvgl.file: `maxLen` behavior corrected -- files over the limit are excluded from the list, not truncated for display - lvgl.page: explained the backButton/back/menu button coupling (backButton=true moves `back` to a second top-right button and repurposes the original button to call `menu`), added the missing PAGE-key mapping note, and fixed align's stated default (TOP -> VTOP, matching the enumerated alignment list and lvgl.box's page) - lvgl.set: signature corrected -- `parent` is a required argument, not optional as `[parent, ]params` implied - lvgl.arc: restored two dropped @notice lines (background arc visibility requires both bgColor and bgOpacity; opacity/rounded interaction is an LVGL rendering limitation) - lvgl.image: restored the dropped note that w/h are required (PERCENT_SIZE doesn't work for images) - 18 functions gated on fullscreenOnly (verified directly against luaLvglObjEx/luaLvglObj call sites, not the review's stated list -- correctly includes `dialog`, which the review missed despite it passing fullscreenOnly=true, and correctly excludes `menu`, which the review incorrectly included despite using the ungated luaLvglPopup path): added a consistent nil-return notice and retval wording across all of them, replacing the one-off "or nil" suffix that only `align` previously had - 7 functions with a `get` callback (choice, font, align, timer, switch, source, file -- verified via the shared ChoiceBase-derived UI class hierarchy each one's build() actually instantiates): corrected "called when the popup opens" to reflect that `get` runs on every refresh cycle, not once. `color` was excluded after verification (ColorPicker calls getValue() exactly once, in its constructor -- genuinely a one-shot call, unlike the ChoiceBase-family widgets); `menu` was also excluded (its build() calls getFunction exactly once at popup-open time, no refresh loop) Comment-only change, no behavior change. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_015yCHydHbzZYCKpav38SonD --- radio/src/lua/api_colorlcd_lvgl.cpp | 103 +++++++++++++++++----------- 1 file changed, 64 insertions(+), 39 deletions(-) diff --git a/radio/src/lua/api_colorlcd_lvgl.cpp b/radio/src/lua/api_colorlcd_lvgl.cpp index 7293feb4027..8518a5226df 100644 --- a/radio/src/lua/api_colorlcd_lvgl.cpp +++ b/radio/src/lua/api_colorlcd_lvgl.cpp @@ -114,11 +114,11 @@ static int luaDestroyLvglWidget(lua_State *L) } /*luadoc -@function lvgl.set([parent, ]params) +@function lvgl.set(parent, params) -Update the settings of an existing LVGL object. Can also be used to change settings that have no dedicated update function (e.g. rectangle thickness). +Update the settings of an existing LVGL object. Can also be used to change settings that have no dedicated update function (e.g. rectangle thickness). Can also be called as `parent:set(params)`. -@param parent (object) LVGL object to update +@param parent (object) LVGL object to update; unlike the constructor functions, this parameter is required, not optional @param params (table) settings to update; use the same keys documented for the object's constructor function @@ -218,7 +218,7 @@ Enable interaction for an LVGL control object. @retval none -@status current Introduced in current +@status current Introduced in 2.11.0 */ static int luaLvglEnable(lua_State *L) { @@ -238,7 +238,7 @@ Disable interaction for an LVGL control object. @retval none -@status current Introduced in current +@status current Introduced in 2.11.0 */ static int luaLvglDisable(lua_State *L) { @@ -258,7 +258,7 @@ Close an LVGL object that represents a closable container or dialog. @retval none -@status current Introduced in current +@status current Introduced in 2.11.0 */ static int luaLvglClose(lua_State *L) { @@ -786,6 +786,9 @@ LROT_BEGIN(lvgllib, NULL, 0) @retval table LVGL object + @notice Arc objects have two elements, a foreground arc and a background arc. By default the background arc is not shown -- to show it, set both `bgColor` and `bgOpacity`. + @notice If `opacity` or `bgOpacity` is less than 255 and `rounded` is true, the ends of the arc will not draw correctly. This is an LVGL limitation. + @status current Introduced in 2.11.0, floating added in 2.11.6 */ LROT_FUNCENTRY(arc, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetArc(); }); }) @@ -803,6 +806,8 @@ LROT_BEGIN(lvgllib, NULL, 0) @retval table LVGL object + @notice `w` and `h` are required -- `lvgl.PERCENT_SIZE` does not work for images, unlike most other objects. + @status current Introduced in 2.11.0, floating added in 2.11.6 */ LROT_FUNCENTRY(image, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetImage(); }); }) @@ -845,8 +850,9 @@ LROT_BEGIN(lvgllib, NULL, 0) * `cornerRadius` (number) radius for the button's corners, defaults to the EdgeTX button style radius * `font` (font value or function) sets the font size, e.g. `MIDSIZE`, `DBLSIZE`; defaults to `STDSIZE` - @retval table LVGL object + @retval table LVGL object, or nil if not running as a One-Time script or fullscreen widget + @notice Only available for One-Time scripts and widgets running in full screen mode -- returns nil otherwise. @status current Introduced in 2.11.0, floating added in 2.11.6 */ LROT_FUNCENTRY(button, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetTextButton(); }, true); }) @@ -868,8 +874,9 @@ LROT_BEGIN(lvgllib, NULL, 0) * `cornerRadius` (number) radius for the button's corners, defaults to the EdgeTX button style radius * `font` (font value or function) sets the font size, e.g. `MIDSIZE`, `DBLSIZE`; defaults to `STDSIZE` - @retval table LVGL object + @retval table LVGL object, or nil if not running as a One-Time script or fullscreen widget + @notice Only available for One-Time scripts and widgets running in full screen mode -- returns nil otherwise. @notice Unlike `lvgl.button`, `press` fires immediately on tap/press rather than on release. The button shows the checked state until ENTER is released or the screen is no longer touched. @status current Introduced in 2.11.0, floating added in 2.11.6 @@ -888,8 +895,9 @@ LROT_BEGIN(lvgllib, NULL, 0) * `set` (function) called when the user interacts with the switch; passed a single number, 0 = off, 1 = on, defaults to nil * `active` (function) sets the enabled/disabled state; must return a boolean, true to enable, defaults to nil - @retval table LVGL object + @retval table LVGL object, or nil if not running as a One-Time script or fullscreen widget + @notice Only available for One-Time scripts and widgets running in full screen mode -- returns nil otherwise. @status current Introduced in 2.11.0, floating added in 2.11.6 */ LROT_FUNCENTRY(toggle, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetToggleSwitch(); }, true); }) @@ -907,8 +915,9 @@ LROT_BEGIN(lvgllib, NULL, 0) * `set` (function) called when the user edits the text; passed the new string content, defaults to nil * `active` (function) sets the enabled/disabled state; must return a boolean, true to enable, defaults to nil - @retval table LVGL object + @retval table LVGL object, or nil if not running as a One-Time script or fullscreen widget + @notice Only available for One-Time scripts and widgets running in full screen mode -- returns nil otherwise. @status current Introduced in 2.11.0, floating added in 2.11.6 */ LROT_FUNCENTRY(textEdit, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetTextEdit(); }, true); }) @@ -929,8 +938,9 @@ LROT_BEGIN(lvgllib, NULL, 0) * `max` (number) maximum allowed value, defaults to 1024 * `display` (function) overrides how the value is displayed; passed the current value, must return a string, defaults to nil - @retval table LVGL object + @retval table LVGL object, or nil if not running as a One-Time script or fullscreen widget + @notice Only available for One-Time scripts and widgets running in full screen mode -- returns nil otherwise. @notice Use `set` to react to every change during editing, or `edited` to only react to the final value once editing is complete. @status current Introduced in 2.11.0, edited added in 2.11.5, floating added in 2.11.6 @@ -947,14 +957,15 @@ LROT_BEGIN(lvgllib, NULL, 0) @commonparams lvgl_object * `title` (string) text displayed in the popup menu's header, defaults to an empty string * `values` (table) simple table of option strings shown in the popup; can be changed via `lvgl.set()` since 2.11.6, defaults to an empty list - * `get` (function) called when the popup is opened, to get the index of the currently selected option (1..number of values), defaults to nil + * `get` (function) called on every refresh cycle to keep the displayed value in sync, to get the index of the currently selected option (1..number of values), defaults to nil * `set` (function) called when the user taps a menu item; passed the selected item's index (1..number of values), defaults to nil * `active` (function) sets the enabled/disabled state; must return a boolean, true to enable, defaults to nil * `filter` (function) called for each option when the popup opens, passed the option's index; return true to show it, false to hide it, defaults to nil * `popupWidth` (number) width of the popup window, defaults to 0 (use default width) - @retval table LVGL object + @retval table LVGL object, or nil if not running as a One-Time script or fullscreen widget + @notice Only available for One-Time scripts and widgets running in full screen mode -- returns nil otherwise. @notice The popup closes and `set` is called when the user selects an item. @notice If the user taps outside the popup or presses RTN, the popup closes without calling `set`. @@ -978,8 +989,9 @@ LROT_BEGIN(lvgllib, NULL, 0) * `set` (function) called when the user moves the knob; passed the new value, defaults to nil * `active` (function) sets the enabled/disabled state; must return a boolean, true to enable, defaults to nil - @retval table LVGL object + @retval table LVGL object, or nil if not running as a One-Time script or fullscreen widget + @notice Only available for One-Time scripts and widgets running in full screen mode -- returns nil otherwise. @status current Introduced in 2.11.0, floating added in 2.11.6 */ LROT_FUNCENTRY(slider, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetSlider(); }, true); }) @@ -1000,8 +1012,9 @@ LROT_BEGIN(lvgllib, NULL, 0) * `set` (function) called when the user moves the knob; passed the new value, defaults to nil * `active` (function) sets the enabled/disabled state; must return a boolean, true to enable, defaults to nil - @retval table LVGL object + @retval table LVGL object, or nil if not running as a One-Time script or fullscreen widget + @notice Only available for One-Time scripts and widgets running in full screen mode -- returns nil otherwise. @status current Introduced in 2.11.0, floating added in 2.11.6 */ LROT_FUNCENTRY(verticalSlider, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetVerticalSlider(); }, true); }) @@ -1014,12 +1027,13 @@ LROT_BEGIN(lvgllib, NULL, 0) @param params (table): @commonparams lvgl_object - * `get` (function) called when the popup opens, to get the currently selected font, defaults to nil + * `get` (function) called on every refresh cycle to keep the displayed value in sync, to get the currently selected font, defaults to nil * `set` (function) called when the user taps a font in the popup; passed the selected font value, defaults to nil * `active` (function) sets the enabled/disabled state; must return a boolean, true to enable, defaults to nil - @retval table LVGL object + @retval table LVGL object, or nil if not running as a One-Time script or fullscreen widget + @notice Only available for One-Time scripts and widgets running in full screen mode -- returns nil otherwise. @notice The popup closes and `set` is called when the user selects an item. @notice If the user taps outside the popup or presses RTN, the popup closes without calling `set`. @@ -1035,11 +1049,12 @@ LROT_BEGIN(lvgllib, NULL, 0) @param params (table): @commonparams lvgl_object - * `get` (function) called when the popup opens, to get the currently selected alignment, defaults to nil + * `get` (function) called on every refresh cycle to keep the displayed value in sync, to get the currently selected alignment, defaults to nil * `set` (function) called when the user taps an alignment in the popup; passed the selected alignment value, defaults to nil - @retval table LVGL object, or nil + @retval table LVGL object, or nil if not running as a One-Time script or fullscreen widget + @notice Only available for One-Time scripts and widgets running in full screen mode -- returns nil otherwise. @notice The popup closes and `set` is called when the user selects an item. @notice If the user taps outside the popup or presses RTN, the popup closes without calling `set`. @@ -1058,8 +1073,9 @@ LROT_BEGIN(lvgllib, NULL, 0) * `get` (function) called when the picker opens, to get the currently selected color, defaults to nil * `set` (function) called when the user picks a color; passed the selected color value, defaults to nil - @retval table LVGL object + @retval table LVGL object, or nil if not running as a One-Time script or fullscreen widget + @notice Only available for One-Time scripts and widgets running in full screen mode -- returns nil otherwise. @notice The popup closes and `set` is called when the user selects a color. @notice If the user taps outside the popup or presses RTN, the popup closes without calling `set`. @@ -1075,12 +1091,13 @@ LROT_BEGIN(lvgllib, NULL, 0) @param params (table): @commonparams lvgl_object - * `get` (function) called when the popup opens, to get the currently selected timer, defaults to nil + * `get` (function) called on every refresh cycle to keep the displayed value in sync, to get the currently selected timer, defaults to nil * `set` (function) called when the user taps a timer in the popup; passed the selected timer value, defaults to nil * `active` (function) sets the enabled/disabled state; must return a boolean, true to enable, defaults to nil - @retval table LVGL object + @retval table LVGL object, or nil if not running as a One-Time script or fullscreen widget + @notice Only available for One-Time scripts and widgets running in full screen mode -- returns nil otherwise. @notice The popup closes and `set` is called when the user selects an item. @notice If the user taps outside the popup or presses RTN, the popup closes without calling `set`. @@ -1096,12 +1113,14 @@ LROT_BEGIN(lvgllib, NULL, 0) @param params (table): @commonparams lvgl_object - * `get` (function) called when the popup opens, to get the currently selected switch, defaults to nil + * `get` (function) called on every refresh cycle to keep the displayed value in sync, to get the currently selected switch, defaults to nil * `set` (function) called when the user picks a switch; passed the selected switch value, defaults to nil * `active` (function) sets the enabled/disabled state; must return a boolean, true to enable, defaults to nil + * `filter` (number) controls which switch types the user can pick; combine `lvgl.SW_xxx` constants to build a custom filter, defaults to `lvgl.SW_ALL` - @retval table LVGL object + @retval table LVGL object, or nil if not running as a One-Time script or fullscreen widget + @notice Only available for One-Time scripts and widgets running in full screen mode -- returns nil otherwise. @notice The popup closes and `set` is called when the user selects an item. @notice If the user taps outside the popup or presses RTN, the popup closes without calling `set`. @@ -1117,12 +1136,13 @@ LROT_BEGIN(lvgllib, NULL, 0) @param params (table): @commonparams lvgl_object - * `get` (function) called when the popup opens, to get the currently selected source, defaults to nil + * `get` (function) called on every refresh cycle to keep the displayed value in sync, to get the currently selected source, defaults to nil * `set` (function) called when the user picks a source; passed the selected source value, defaults to nil * `filter` (number) controls which source types the user can pick; combine `lvgl.SRC_xxx` constants to build a custom filter, defaults to `lvgl.SRC_ALL` - @retval table LVGL object + @retval table LVGL object, or nil if not running as a One-Time script or fullscreen widget + @notice Only available for One-Time scripts and widgets running in full screen mode -- returns nil otherwise. @notice The popup closes and `set` is called when the user selects an item. @notice If the user taps outside the popup or presses RTN, the popup closes without calling `set`. @@ -1139,16 +1159,17 @@ LROT_BEGIN(lvgllib, NULL, 0) @param params (table): @commonparams lvgl_object * `title` (string) text displayed in the popup's header, defaults to an empty string - * `get` (function) called when the popup opens, to get the currently selected filename; must return a string, defaults to nil + * `get` (function) called on every refresh cycle to keep the displayed value in sync, to get the currently selected filename; must return a string, defaults to nil * `set` (function) called when the user picks a file; passed the selected filename (without path), defaults to nil * `active` (function) sets the enabled/disabled state; must return a boolean, true to enable, defaults to nil * `folder` (string) SD card folder to browse for files, defaults to nil * `extension` (string) extension filter, e.g. `.png` or concatenated `.png.bmp` to match multiple, defaults to nil (no filter) * `hideExtension` (boolean) if true, the extension is stripped before `set` is called and hidden in the picker list, defaults to false - * `maxLen` (number) maximum filename length shown in the picker, defaults to 255 + * `maxLen` (number) maximum filename length (measured after `hideExtension` stripping, if set); files with longer names are not shown in the picker list, defaults to 255 - @retval table LVGL object + @retval table LVGL object, or nil if not running as a One-Time script or fullscreen widget + @notice Only available for One-Time scripts and widgets running in full screen mode -- returns nil otherwise. @notice The popup closes and `set` is called when the user picks a file. @notice If the user taps outside the popup or presses RTN, the popup closes without calling `set`. @@ -1195,8 +1216,9 @@ LROT_BEGIN(lvgllib, NULL, 0) @commonparams lvgl_object * `title` (string or function) text displayed on the left; function support added in 2.11.6, defaults to an empty string - @retval table LVGL object + @retval table LVGL object, or nil if not running as a One-Time script or fullscreen widget + @notice Only available for One-Time scripts and widgets running in full screen mode -- returns nil otherwise. @status current Introduced in 2.11.0, title function support added in 2.11.6, floating added in 2.11.6 */ LROT_FUNCENTRY(setting, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetSetting(); }, true); }) @@ -1209,8 +1231,8 @@ LROT_BEGIN(lvgllib, NULL, 0) * `title` (string or function) title text in the header; function support added in 2.11.4, defaults to an empty string * `subtitle` (string or function) sub-title text in the header; function support added in 2.11.4, defaults to an empty string * `icon` (string) full path to a 30x30 grey-scale mask image for the back button icon (white = transparent, black = opaque); defaults to the EdgeTX logo icon - * `back` (function) called when the user taps the back button or presses RTN, defaults to nil - * `menu` (function) called when the user taps the menu button (added in 2.11.4), defaults to nil + * `back` (function) called when the top-left header button is tapped or RTN is pressed; if `backButton` is not set this is the only header button, defaults to nil + * `menu` (function) called when the top-left header button is tapped, but only if `backButton` is set to true -- in that case `back` moves to a second button on the top-right, defaults to nil * `prevButton` (table) adds a prev navigation button; table has a `press` function and optional `active` function (added in 2.11.4), defaults to nil * `nextButton` (table) adds a next navigation button; table has a `press` function and optional `active` function (added in 2.11.4), defaults to nil * `flexFlow` (lvgl.FLOW_COLUMN or lvgl.FLOW_ROW) enables flex layout for this page, not used by default @@ -1219,15 +1241,17 @@ LROT_BEGIN(lvgllib, NULL, 0) * `scrollDir` (lvgl.SCROLL_xx) allowed scroll directions when child objects extend past the page bounds (stand alone scripts only), defaults to `lvgl.SCROLL_ALL` * `scrolled` (function) called when the page content is scrolled; passed `x`, `y` of the current scroll position, defaults to nil * `scrollTo` (function) overrides the page scroll position; must return `x`, `y` to scroll to, defaults to nil - * `align` (alignment type (LEFT, RIGHT, CENTER, VTOP, VBOTTOM, VCENTER)) alignment used with flex layouts (added in 2.11.4), defaults to `CENTER | TOP` - * `backButton` (boolean) if true, displays an exit/back button on the right of the header (added in 2.11.4), defaults to false + * `align` (alignment type (LEFT, RIGHT, CENTER, VTOP, VBOTTOM, VCENTER)) alignment used with flex layouts (added in 2.11.4), defaults to `CENTER | VTOP` + * `backButton` (boolean) if true, adds a second header button on the top-right calling `back`, and repurposes the top-left button to call `menu` instead (added in 2.11.4), defaults to false * `borderPad` (number or table) border padding around the container edges; a single number applies to all sides, or a table `{left=?, right=?, top=?, bottom=?}` (added in 2.11.5), defaults to `PAD_OUTLINE` if `flexFlow` is set, otherwise 0 - @retval table LVGL object + @retval table LVGL object, or nil if not running as a One-Time script or fullscreen widget + @notice Only available for One-Time scripts and widgets running in full screen mode -- returns nil otherwise. @notice The common object settings (x, y, w, h, color, etc.) are not used by `lvgl.page` -- only the settings listed above apply. @notice The page automatically adds scroll bars if child objects fall outside its boundaries. @notice `scrollBar`, `scrollDir`, `scrolled`, and `scrollTo` were added in 2.11.2. + @notice The PAGE keys are not automatically mapped to `prevButton`/`nextButton` -- the script's `run` function must detect and handle them itself. @status current Introduced in 2.11.0, title/subtitle function support, menu, prevButton, nextButton, align, and backButton added in 2.11.4, borderPad added in 2.11.5, scrollBar/scrollDir/scrolled/scrollTo added in 2.11.2 */ @@ -1241,10 +1265,11 @@ LROT_BEGIN(lvgllib, NULL, 0) * `title` (string) text displayed in the dialog's header, defaults to an empty string * `close` (function) called when the dialog is closed, defaults to nil * `flexFlow` (lvgl.FLOW_COLUMN or lvgl.FLOW_ROW) enables flex layout for this box, not used by default - * `flexPad` (number) padding between rows/columns when flex layout is used, defaults to 0 + * `flexPad` (number) padding between rows/columns when flex layout is used, defaults to `PAD_OUTLINE` - @retval table LVGL object + @retval table LVGL object, or nil if not running as a One-Time script or fullscreen widget + @notice Only available for One-Time scripts and widgets running in full screen mode -- returns nil otherwise. @notice The common object settings (x, y, w, h, color, etc.) are not used by `lvgl.dialog` -- only the settings listed above apply. @status current Introduced in 2.11.0 @@ -1277,7 +1302,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @param params (table): * `title` (string) text displayed in the dialog's header, defaults to an empty string * `message` (string) text displayed in the dialog's body, defaults to an empty string - * `details` (function) additional text displayed in the dialog's body, defaults to an empty string + * `details` (string) additional text displayed in the dialog's body, defaults to an empty string @retval none @@ -1294,7 +1319,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @param params (table): * `title` (string) text displayed in the popup's header, defaults to an empty string * `values` (table) simple table of option strings shown in the popup, defaults to an empty list - * `get` (function) called when the popup opens, to get the index of the currently selected option (1..number of values), defaults to nil + * `get` (function) called when the popup is opened, to get the index of the currently selected option (1..number of values), defaults to nil * `set` (function) called when the user taps a menu item; passed the selected item's index (1..number of values), defaults to nil @retval none From 310dc64bd45c15279ed0e7218dffb65036fb67d6 Mon Sep 17 00:00:00 2001 From: Peter Feerick <5500713+pfeerick@users.noreply.github.com> Date: Mon, 7 Sep 2026 22:49:00 +1000 Subject: [PATCH 6/6] fix(lua): address validation-pass findings on LVGL luadoc An independent validation pass on the previous accuracy-fix commit found one regression and some polish items: - lvgl.file's `get` callback: the previous fix wrongly generalized this to "every refresh cycle" (true for the plain Choice-based pickers) but FileChoice routes `get` through getLabelText(), which only runs when the selection changes or on first open -- reverted to popup-open semantics, closer to correct. - lvgl.color's `get` callback: ColorPicker calls getValue() exactly once in its constructor, not on each popup open -- corrected to "called once when the object is created". - lvgl.image's PERCENT_SIZE claim: unsourced inference not present in the original guide or confirmed directly in source -- trimmed back to the sourced part of the notice (w/h are required). - lvgl.page's `back` parameter description: was misleading on its own (says "top-left button" unconditionally, only true when `backButton` is unset) -- reworded to be accurate standalone. - Missing blank line between @notice and @status in 6 blocks (button, toggle, textEdit, slider, verticalSlider, setting) -- every other notice-then-status block in this file, and all 42 in the other api_*.cpp files, use a blank line there; restored for consistency. Comment-only change, no behavior change. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_015yCHydHbzZYCKpav38SonD --- radio/src/lua/api_colorlcd_lvgl.cpp | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/radio/src/lua/api_colorlcd_lvgl.cpp b/radio/src/lua/api_colorlcd_lvgl.cpp index 8518a5226df..cce961c6353 100644 --- a/radio/src/lua/api_colorlcd_lvgl.cpp +++ b/radio/src/lua/api_colorlcd_lvgl.cpp @@ -806,7 +806,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @retval table LVGL object - @notice `w` and `h` are required -- `lvgl.PERCENT_SIZE` does not work for images, unlike most other objects. + @notice `w` and `h` are required. @status current Introduced in 2.11.0, floating added in 2.11.6 */ @@ -853,6 +853,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @retval table LVGL object, or nil if not running as a One-Time script or fullscreen widget @notice Only available for One-Time scripts and widgets running in full screen mode -- returns nil otherwise. + @status current Introduced in 2.11.0, floating added in 2.11.6 */ LROT_FUNCENTRY(button, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetTextButton(); }, true); }) @@ -898,6 +899,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @retval table LVGL object, or nil if not running as a One-Time script or fullscreen widget @notice Only available for One-Time scripts and widgets running in full screen mode -- returns nil otherwise. + @status current Introduced in 2.11.0, floating added in 2.11.6 */ LROT_FUNCENTRY(toggle, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetToggleSwitch(); }, true); }) @@ -918,6 +920,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @retval table LVGL object, or nil if not running as a One-Time script or fullscreen widget @notice Only available for One-Time scripts and widgets running in full screen mode -- returns nil otherwise. + @status current Introduced in 2.11.0, floating added in 2.11.6 */ LROT_FUNCENTRY(textEdit, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetTextEdit(); }, true); }) @@ -992,6 +995,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @retval table LVGL object, or nil if not running as a One-Time script or fullscreen widget @notice Only available for One-Time scripts and widgets running in full screen mode -- returns nil otherwise. + @status current Introduced in 2.11.0, floating added in 2.11.6 */ LROT_FUNCENTRY(slider, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetSlider(); }, true); }) @@ -1015,6 +1019,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @retval table LVGL object, or nil if not running as a One-Time script or fullscreen widget @notice Only available for One-Time scripts and widgets running in full screen mode -- returns nil otherwise. + @status current Introduced in 2.11.0, floating added in 2.11.6 */ LROT_FUNCENTRY(verticalSlider, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetVerticalSlider(); }, true); }) @@ -1070,7 +1075,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @param params (table): @commonparams lvgl_object - * `get` (function) called when the picker opens, to get the currently selected color, defaults to nil + * `get` (function) called once when the object is created, to get the initial color, defaults to nil * `set` (function) called when the user picks a color; passed the selected color value, defaults to nil @retval table LVGL object, or nil if not running as a One-Time script or fullscreen widget @@ -1159,7 +1164,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @param params (table): @commonparams lvgl_object * `title` (string) text displayed in the popup's header, defaults to an empty string - * `get` (function) called on every refresh cycle to keep the displayed value in sync, to get the currently selected filename; must return a string, defaults to nil + * `get` (function) called when the popup is opened, and after the selection changes, to get the currently selected filename; must return a string, defaults to nil * `set` (function) called when the user picks a file; passed the selected filename (without path), defaults to nil * `active` (function) sets the enabled/disabled state; must return a boolean, true to enable, defaults to nil * `folder` (string) SD card folder to browse for files, defaults to nil @@ -1219,6 +1224,7 @@ LROT_BEGIN(lvgllib, NULL, 0) @retval table LVGL object, or nil if not running as a One-Time script or fullscreen widget @notice Only available for One-Time scripts and widgets running in full screen mode -- returns nil otherwise. + @status current Introduced in 2.11.0, title function support added in 2.11.6, floating added in 2.11.6 */ LROT_FUNCENTRY(setting, [](lua_State* L) { return luaLvglObjEx(L, []() { return new LvglWidgetSetting(); }, true); }) @@ -1231,7 +1237,7 @@ LROT_BEGIN(lvgllib, NULL, 0) * `title` (string or function) title text in the header; function support added in 2.11.4, defaults to an empty string * `subtitle` (string or function) sub-title text in the header; function support added in 2.11.4, defaults to an empty string * `icon` (string) full path to a 30x30 grey-scale mask image for the back button icon (white = transparent, black = opaque); defaults to the EdgeTX logo icon - * `back` (function) called when the top-left header button is tapped or RTN is pressed; if `backButton` is not set this is the only header button, defaults to nil + * `back` (function) called when RTN is pressed, or when the back button is tapped -- the top-left header button if `backButton` is not set, otherwise a second button on the top-right, defaults to nil * `menu` (function) called when the top-left header button is tapped, but only if `backButton` is set to true -- in that case `back` moves to a second button on the top-right, defaults to nil * `prevButton` (table) adds a prev navigation button; table has a `press` function and optional `active` function (added in 2.11.4), defaults to nil * `nextButton` (table) adds a next navigation button; table has a `press` function and optional `active` function (added in 2.11.4), defaults to nil