EdgeTX widgets and One-Time scipts can make use of LVGL controls and objects to create the script user interface. In addition to providing much better performance, this gives Lua scripts the same styles applied to firmware LVGL pages and controls.

The LVGL API can be used to add varios objects such as labels, rectangles, circles, buttons, toggle switches, sliders and more. Objects can be grouped, e.g. a rectangle can contain child labels or any other object. Objects can be moved, resized and updated as needed.

Many object properties can be set dynamically through functions in the Lua script - whenever the function returns a new value the objects property is automaticall changed. This removes the need for manually re-drawing the user interface.

Limitations:

• Direct drawing via the 'lcd' API is not available for scripts using LVGL to create the UI.

Activating the LVGL API

A script that wants to use LVGL to create the UI must return 'useLvgl = true' in the table returned by the script:

return {init = init, run = run, useLvgl=true}

Once activated a new 'lvgl' object will be available to use in the script. This is the primary interface to the LVGL API.

Scripts should check that 'lvgl' is not nil before use. If the 'lvgl' object is nil it is most likely the script is running on an earlier version of EdgeTX (prior to 2.11), or you forgot to set 'useLvgl = true'. Scripts should either display an error or fall back to using the lcd API in LVGL is not available.

Usage patterns

One-Time scripts

One-Time scripts have only two functions. Prior to the LVGL API, the 'init' function would be used to set up the initial state for the script and the 'run' function would re-draw the UI whenever called as well as process key and touch events.

With the LVGL API, the 'init' function should still set up the initial state for the script; but should also create the UI from LVGL objects. The 'run' function may handle key and touch events; but in most cases the LVGL objects themselves will do the heavy lifting. When set up correctly the LVGL UI will be automatically updated as the local state is changed, and the script will be automatically updated as the user interacts with the LVGL objects.

Widget scripts

Widget scripts using LVGL should create their UI in the 'update' function using the widget size to determine what elements to create and how to lay them out.

The 'background' and 'run' functions should just update essential state changes that are not being managed directly by the LVGL objects.

One-Time script

local exitTool = false

local function close()
  lvgl.confirm({title="Exit", message="Really exit?",
    confirm=(function() exitTool = true end)
  })
end

local function init()
  if lvgl == nil then return end

  lvgl.clear();

  local pg = lvgl.page({title="Test Tool", subtitle="Page 1", back=close})

  pg:label({x=70, y=16, color=BLACK, font=DBLSIZE, text="Test Page"})
  pg:button({x=200, y=150, text="CLOSE", press=close})
end

local function run(event, touchState)
  if lvgl == nil then
    lcd.drawText(0, 0, "LVGL support required", COLOR_THEME_WARNING)
  end

  if (exitTool) then return 2 end
  return 0
end

return {init = init, run = run, useLvgl=true}

When run this produces the page shown below.

The user can exit the script by tapping the 'CLOSE' button or tapping the 'EdgeTX' button in the top-left corner. In both cases a popup dialog will be shown - if the user selects 'Yes' the script will close.

Widget script

LVGL version of the 'Counter' script.

local options = {
  { "Color", COLOR, COLOR_THEME_SECONDARY1 },
  { "Shadow", BOOL, 0 }
}

local function create(zone, options)
  local wgt = { zone=zone, options=options, counter=0 }
  return wgt
end

local function update(wgt, options)
  wgt.options = options

  lvgl.clear()

  if wgt.options.Shadow ~= 0 then
    lvgl.label({x=wgt.zone.x+1, y=wgt.zone.y+1, color=BLACK, font=DBLSIZE, text=(function() return wgt.counter end)})
  end
  lvgl.label({x=wgt.zone.x, y=wgt.zone.y, color=wgt.options.Color, font=DBLSIZE, text=(function() return wgt.counter end)})
end

local function background(wgt)
  wgt.counter = wgt.counter + 1
end

function refresh(wgt)
  wgt.counter = wgt.counter + 1
end

return { name="CounterLVGL", options=options, create=create, update=update, refresh=refresh, background=background, useLvgl=true }

API Status

Change log

Syntax

lvgl.align([parent], {settings})

parent:align({settings})

Parameters

See the API page for parameter description and common settings.

Choice specific settings:

Notes

The popup menu is closed when the user selects an item, and the 'set' function is called.

If the user taps outside the menu or the RTN key is pressed, the popup menu is closed and the 'set' function is not called.

API Status

Change log

Syntax

lvgl.box([parent], {settings})

parent:box({settings})

Parameters

See the API page for parameter description and common settings.

Box specific settings:

Return values

LVGL object

API Status

Return values

LVGL object

Change log

Syntax

lvgl.arc([parent], {settings})

parent:arc({settings})

Parameters

See the API page for parameter description and common settings.

Note: 'w', 'h' and 'size' should not be used with lvgl.arc. Use 'radius' instead.

Arc specific settings:

Return values

LVGL object

API Status

Change log

LVGL objects are created and manipulated using the 'lvgl' functions.

Most of these functions follow the syntax below. A few function have only the optional 'parent' parameter.

Most of the functions return an LVGL object that can be used to update the UI or in other API calls.

API functions can also be called using Lua OO syntax.

For example the following two lines are equivalent.

There are a number of settings that are common to all of the LVGL functions that take a 'settings' table parameter.

The functions associated with settings are called periodically by the firmware. Where a setting is defined using a function, the UI will automatically update whenever the function returns a different value.

A note on object width and height

Although width and height, and the size function, can be defined for all objects they may not be used in some cases. For example when creating a circle or arc object the radius property should be used instead.

Syntax

lvgl.choice([parent], {settings})

parent:choice({settings})

Parameters

See the API page for parameter description and common settings.

Choice specific settings:

Return values

LVGL object

Notes

The popup menu is closed when the user selects an item, and the 'set' function is called.

If the user taps outside the menu or the RTN key is pressed, the popup menu is closed and the 'set' function is not called.

API Status

Change log

Syntax

lvgl.clear([parent])

parentclear()

Parameters

See the API page for parameter description and common settings.

The 'settings' parameter is not used.

Notes

If 'parent' is not set then the entire script UI is deleted. Use this when the UI changes dramatically (e.g. widget size changes).

When the 'parent' parameter is defined, only the child LVGL objects within the parent are deleted. Use this to remove and replace a specific set of objects.

API Status

Change log

Syntax

lvgl.color([parent], {settings})

parent:color({settings})

Parameters

See the API page for parameter description and common settings.

Choice specific settings:

Return values

LVGL object

Notes

The popup menu is closed when the user selects an item, and the 'set' function is called.

If the user taps outside the menu or the RTN key is pressed, the popup menu is closed and the 'set' function is not called.

API Status

Change log

Syntax

lvgl.confirm({settings})

Parameters

The lvgl.confirm function uses only the settings shown below. The common settings shown on the API page are not used.

API Status

Change log

Syntax

lvgl.circle([parent], {settings})

parent:circle({settings})

Parameters

See the API page for parameter description and common settings.

Note: 'w', 'h' and 'size' should not be used with lvgl.circle. Use 'radius' instead.

Circle specific settings:

Return values

LVGL object

API Status

Change log

Syntax

lvgl.build([parent], {{settings}})

parent:build({{settings}})

Parameters

See the API page for parameter description and common settings.

Build specific settings:

Return values

Table of named LVGL objects.

Notes

The 'settings' parameter to lvgl.build should be a table of tables. Each inner table creates a separate LVGL object based on the 'type' value.

For example the code below creates two object, a label and a rectangle.

Objects can be nested by using the 'children' setting, this should be another table of tables just like the build settings.

For example this code creates another label as a child of the rectangle object. The x & y co-ordinates for the second label are relative to the top left corner of the parent rectangle.

The lvgl.build function will return a table of LVGL objects. This table will contain named references to any objects created that have the 'name' setting, Only references to named objects are returned.

For example this code assigns a name to the inner label and then updates the color.

Warning

Very large nested tables or very deeply nested tables may not work when compiled to a .luac script. If your script works when run from the .lua file; but fails when run from .luac, try breaking the lvgl.build call into multiple calls with smaller tables.

API Status

Change log

Syntax

lvgl.choice([parent], {settings})

parent:choice({settings})

Parameters

See the API page for parameter description and common settings.

Button specific settings:

Return values

LVGL object

API Status

Change log

Syntax

lvgl.hline([parent], {settings})

parent:hline({settings})

Parameters

See the API page for parameter description and common settings.

The 'w' setting determinse the length of the line.

The 'h' setting determines the thickness of the line.

Hline specific settings:

Return values

LVGL object

API Status

Change log

Syntax

lvgl.hide(parent)

parent:hide()

Parameters

See the API page for parameter description and common settings.

The 'parent' parameter is mandatory.

The 'settings' parameter is not used.

Notes

The 'visible' setting function can also be used to dynamically show and hide objects.

API Status

Change log

Syntax

lvgl.dialog({settings})

Parameters

The lvgl.confirm function uses only the settings shown below. The common settings shown on the API page are not used.

API Status

Change log

Syntax

lvgl.label([parent], {settings})

parent:label({settings})

Parameters

See the API page for parameter description and common settings.

Label specific settings:

Return values

LVGL object

API Status

Change log

Syntax

lvgl.image([parent], {settings})

parent:image({settings})

Parameters

See the API page for parameter description and common settings.

Image specific settings:

Return values

LVGL object

API Status

Change log

Syntax

lvgl.line([parent], {settings})

parent:line({settings})

Parameters

See the API page for parameter description and common settings.

The 'x, 'y, 'w' and 'h' settings are not used.

Line specific settings:

Return values

LVGL object

API Status

Change log

Syntax

lvgl.font([parent], {settings})

parent:font({settings})

Parameters

See the API page for parameter description and common settings.

Choice specific settings:

Return values

LVGL object

Notes

The popup menu is closed when the user selects an item, and the 'set' function is called.

If the user taps outside the menu or the RTN key is pressed, the popup menu is closed and the 'set' function is not called.

API Status

Change log

Syntax

lvgl.message({settings})

Parameters

The lvgl.confirm function uses only the settings shown below. The common settings shown on the API page are not used.

API Status

Change log

Syntax

lvgl.set([parent], {settings})

parent:set({settings})

Parameters

See the API page for parameter description and common settings.

See the function description pages for settings specific to each LVGL object type.

Notes

This can be used to update one or more settings for an existing LVGL object. The 'settings' parameter should contain values relevant to the type of object being created.

This can be used to update settings that do not support being controlled by functions (e.g. rectangle thickness).

API Status

Change log

Syntax

lvgl.qrcode([parent], {settings})

parent:qrcode({settings})

Parameters

See the API page for parameter description and common settings.

Note: 'w' and 'h' should be set to the same value for a QR code.

QR code specific settings:

Return values

LVGL object

API Status

Change log

Syntax

lvgl.page({settings})

Parameters

The lvgl.page function uses only the settings shown below. The common settings shown on the API page are not used.

Return values

LVGL object

Notes

The 'page' object should be created as the top level LVGL object in the script window, and all other LVGL objects added as children of the 'page' object.

API Status

Change log

Return values

LVGL object

API Status

Change log

Syntax

lvgl.isAppMode()

Parameters

The function has no parameters.

Return values

True if the widget is running in App Mode, false otherwise.

API Status

Change log

Syntax

lvgl.rectangle([parent], {settings})

parent:rectangle({settings})

Parameters

See the API page for parameter description and common settings.

Rectangle specific settings:

Return values

LVGL object

API Status

Change log

Syntax

lvgl.setting([parent], {settings})

parent:setting({settings})

Parameters

See the API page for parameter description and common settings.

Setting specific settings:

Return values

LVGL object

API Status

Change log

Syntax

lvgl.source([parent], {settings})

parent:source({settings})

Parameters

See the API page for parameter description and common settings.

Source specific settings:

Return values

LVGL object

Notes

The popup menu is closed when the user selects an item, and the 'set' function is called.

If the user taps outside the menu or the RTN key is pressed, the popup menu is closed and the 'set' function is not called.

API Status

Change log

Syntax

lvgl.switch([parent], {settings})

parent:switch({settings})

Parameters

See the API page for parameter description and common settings.

Switch specific settings:

Return values

LVGL object

Notes

The popup menu is closed when the user selects an item, and the 'set' function is called.

If the user taps outside the menu or the RTN key is pressed, the popup menu is closed and the 'set' function is not called.

API Status

Change log

Return values

LVGL object

API Status

Change log

Syntax

lvgl.slider([parent], {settings})

parent:slider({settings})

Parameters

See the API page for parameter description and common settings.

Slider specific settings:

Return values

LVGL object

API Status

Change log

Syntax

lvgl.vline([parent], {settings})

parent:hline({settings})

Parameters

See the API page for parameter description and common settings.

The 'h' setting determinse the length of the line.

The 'w' setting determines the thickness of the line.

Vline specific settings:

Return values

LVGL object

API Status

Change log

Syntax

lvgl.show(parent)

parent:show()

Parameters

See the API page for parameter description and common settings.

The 'parent' parameter is mandatory.

The 'settings' parameter is not used.

Notes

The 'visible' setting function can also be used to dynamically show and hide objects.

API Status

Change log

Syntax

lvgl.toggle([parent], {settings})

parent:toggle({settings})

Parameters

See the API page for parameter description and common settings.

Toggle specific settings:

Return values

LVGL object

API Status

Change log

Syntax

lvgl.timer([parent], {settings})

parent:timer({settings})

Parameters

See the API page for parameter description and common settings.

Timer specific settings:

Return values

LVGL object

Notes

The popup menu is closed when the user selects an item, and the 'set' function is called.

If the user taps outside the menu or the RTN key is pressed, the popup menu is closed and the 'set' function is not called.

API Status

Change log

Syntax

lvgl.triangle([parent], {settings})

parent:triangle({settings})

Parameters

See the API page for parameter description and common settings.

The 'x, 'y, 'w' and 'h' settings are not used.

Triangle specific settings:

Return values

LVGL object

Notes

Unlike the line drawing objects, there is no built in triangle drawing in LVGL. The method used to draw triangles is quite simple and does not do any anti-aliasing.

API Status

Change log