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.