API

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.

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

Parameter	Notes	Description
parent	Optional (with some exceptions) If present must be an LVGL object	Parent object. If set then whatever LVGL objects are created by the function are set as children of 'parent'. If not set then objects are created in the top level script window.
settings	Mandatory (with some exceptions) Must be a table	Contains all of the settings required to create the LVGL object.

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.

lvgl.show(parent)
parent:show()

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

Name	Type	Description	Default if not set
x	Number	Horizontal position of the object relative to the top left corner of the parent object.	0
y	Number	Vertical position of the object relative to the top left corner of the parent object.	0
w	Number	Width of the object	Auto size to fit content
h	Number	Height of the object	Auto size to fit content
color	Color or Function	Primary color for the object.	COLOR_THEME_SECONDARY1
pos	Function	Position of the object relative to the top left corner of the parent object. Must return two values - x, y.	nil
size	Function	Size of the object. Must return two values - width, height.	nil
visible	Function	Controls visibility of the object. Must return a boolean - true if the object is shown, false to hide it.	nil

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.

Dynamically managing object size and position for different screens

EdgeTx supports both landscape and portrait orientation displays in a variety of resolutions (480x272, 480x320, 320x480, 320x240, 800x480, etc). Managing all these in a Lua script dynamically can be challenging.

To assist with this there are a number of things that can be used:

• Flex layouts can be used; but care should be taken as they are noticeably slower than using absolution position and size.

• When using the 'page' object the lvgl.PAGE_BODY_HEIGHT contant will give the size of the page body (minus the header). This can be used to manage the layout for the page content.

• The lvgl.UI_ELEMENT_HEIGHT constant defines the default height for buttons, toggles, sliders etc.

• The lvgl.LCD_SCALE constant can be used to scale values for the current LCD size, when compared to the default 480x272 size. For example if a button needs to be 80 pixels wide on a 480x272 display then setting the width to 80 * lvgl.LCD_SCALE will ensure the size is adusted for the actual LCD size.

• The lvgl.PERCENT_SIZE value can be used to set the size and position of an object as a percentage of the parent size. For example setting width to lvgl.PERCENT_SIZE+80 will size the object to 80% of the parent width. Setting x = lvgl.PERCENT_SIZE+50 will set the X position to ½ of the parent width.

  • NOTE: this requires that the parent container has a defined size. If the parent size is the default auto size base on content then percentage sizing will fail. This results in a catch-22 where the parent need the child size; but the child first needs the parent size.

  • NOTE: PERCENT_SIZE does not work for all objects. For example, images require a fixed width and height.