Lua Scripting

This is a complete listing of all available bindings that are available to Lua code running on Tangara.

This reference documentation is based on the stub modules in luals-stubs in the ESP32 firmware repository.

alerts

The alerts module contains functions for showing transient popups over the current screen.

alerts.hide

function alerts.hide()

Dismisses any visible alerts, removing them from the screen.

alerts.show

function alerts.show(constructor: function)

Shows a new alert, replacing any other alerts.

Arguments

• constructor: Called to create the UI for the alert. A new default root object and group will be set before calling this function.i Alerts are non-interactable; the group created for the constructor will not be granted focus.

backstack

The backstack module contains functions that can be used to implement a basic stack-based navigation hierarchy. See also the screen module, which provides a class prototype meant for use with this module.

backstack.pop

function backstack.pop()

Removes the current screen from the display, then replaces it with the screen that is at the top of the backstack. This function does nothing if there are no other screens in the stack.

backstack.push

function backstack.push(screen: screen)

Displays the given screen to the user. If there was already a screen being displayed, then the current screen is removed from the display, and added to the backstack.

Arguments

• screen: The screen to display.

backstack.reset

function backstack.reset(screen: screen)

Sets a new root screen, replacing any existing screens

Arguments

• screen: The new root screen

bluetooth

The 'bluetooth' module contains Properties and functions for interacting with the device's Bluetooth capabilities.

bluetooth.connected

Property

Whether or not there is an active connection to another Bluetooth device.

bluetooth.connecting

Property

Whether or not we are currently connecting to the paired device.

bluetooth.disable

function bluetooth.disable()

Disables Bluetooth, this is the same as bluetooth.enabled:set(false)

bluetooth.discovered_devices

Property

Devices nearby that have been discovered.

bluetooth.discovering

Property

Whether or not we are actively scanning for new devices.

bluetooth.enable

function bluetooth.enable()

Enables Bluetooth, this is the same as bluetooth.enabled:set(true)

bluetooth.enabled

Property

Whether or not the Bluetooth stack is currently enabled. This property is writeable, and can be used to enable or disable Bluetooth.

bluetooth.known_devices

Property

Devices that have previously been paired.

bluetooth.paired_device

Property

The device that is currently paired. The bluetooth stack will automatically connect to this device if possible.

controls

The controls module contains Properties relating to the device's physical controls. These controls include the touchwheel, the lock switch, and the side buttons.

controls.lock_switch

Property

The current state of the device's lock switch.

controls.scheme

Property

The currently configured control scheme

controls.scroll_sensitivity

Property

How much rotational motion is required on the touchwheel per scroll tick.

database

The database module contains Properties and functions for working with the device's LevelDB-backed track database.

database.indexes

function database.indexes() -> Index[]

Returns a list of all indexes in the database.

database.updating

Property

Whether or not a database re-index is currently in progress.

database.Index

An index is heirarchical, sorted, view of the tracks within the database. For example, the 'All Albums' index contains, first, a sorted list of every album name in the library. Then, at the second level of the index, a sorted list of every track within each album.

Index.iter

(method) Index:iter() -> it: Iterator

Returns a new iterator that can be used to access every record within the first level of this index.

Returns

An iterator that yields Records.

Index.name

(method) Index:name() -> string

Gets the human-readable name of this index. This is typically something like "All Albums", or "Albums by Artist". The __tostring metatable function is an alias of this function.

database.Iterator

An iterator is a userdata type that behaves like an ordinary Lua iterator.

database.Record

Gets the human-readable text representing this record. The __tostring metatable function is an alias of this function.

Record.contents

(method) Record:contents() -> r: Iterator|TrackId

Returns the value that this record represents. This may be either a track id, for records which uniquely identify a track, or it may be a new Iterator representing the next level of depth for the current index.

For example, each Record in the "All Albums" index corresponds to an entire album of tracks; the 'contents' of such a Record is an iterator returning each track in the album represented by the Record. The contents of each of the returned 'track' Records would be a full Track, as there is no further disambiguation needed.

Returns

A track id if this is a leaf record, otherwise a new iterator for the next level of this index.

database.TrackId

A TrackId is a unique identifier, representing a playable track in the user's library.

display

The display module contains Properties relating to the device's physical display.

display.brightness

Property

The screen's current brightness, as a gamma-corrected percentage value from 0 to 100.

lvgl

The lvgl module provides bindings to the LVGL graphics library. These bindings were originally based on luavgl, but have diverged somewhat. These bindings are also largely a very thin abstraction around LVGL's C API, so LVGL's documentation may also be useful to reference. This module is currently only available from the UI Lua context; i.e. the main.lua script run after boot on-device.

lvgl.Bar

function lvgl.Bar(parent?: Object, property?: BarStyle) -> Bar

Create a new Bar widget. See the LVGL docs for details about this widget.

Arguments

• parent: The parent for this object, or nil to add to the screen root.
• property: Style properties to apply to this object

lvgl.Button

function lvgl.Button(parent?: Object, property?: StyleProp) -> Button

Create a new Button widget. See the LVGL docs for details about this widget.

Arguments

• parent: The parent for this object, or nil to add to the screen root.
• property: Style properties to apply to this object

lvgl.Calendar

function lvgl.Calendar(parent?: Object, property?: CalendarStyle) -> Calendar

Create a new Calendar widget. See the LVGL docs for details about this widget.

Arguments

• parent: The parent for this object, or nil to add to the screen root.
• property: Style properties to apply to this object

lvgl.Checkbox

function lvgl.Checkbox(parent?: Object, property?: CheckboxStyle) -> Checkbox

Create a new Checkbox widget. See the LVGL docs for details about this widget.

Arguments

• parent: The parent for this object, or nil to add to the screen root.
• property: Style properties to apply to this object

lvgl.Dropdown

function lvgl.Dropdown(parent?: Object, property?: DropdownStyle) -> Dropdown

Create a new Dropdown widget. See the LVGL docs for details about this widget.

Arguments

• parent: The parent for this object, or nil to add to the screen root.
• property: Style properties to apply to this object

lvgl.Font

function lvgl.Font(path: string) -> Font

Create a new a font. Fonts can be located on internal flash or the SD card, and must be in LVGL's binary font format.

Arguments

• path: location of the binary font file

lvgl.HOR_RES

function lvgl.HOR_RES() -> integer

Returns the horizontal resolution of the display.

lvgl.Image

function lvgl.Image(parent?: Object, property?: ImageStyle) -> Image

Create a new Image widget. See the LVGL docs for details about this widget.

Arguments

• parent: The parent for this object, or nil to add to the screen root.
• property: Style properties to apply to this object

lvgl.ImgData

function lvgl.ImgData(path?: string) -> ImgData

Decodes an image from the filesystem and pins it into RAM, returning a lightuserdata that can be passed to img:set_src.

Arguments

• path: path to the encoded image

lvgl.Keyboard

function lvgl.Keyboard(parent?: Object, property?: KeyboardStyle) -> Keyboard

Create a new Keyboard widget. See the LVGL docs for details about this widget.

Arguments

• parent: The parent for this object, or nil to add to the screen root.
• property: Style properties to apply to this object

lvgl.Label

function lvgl.Label(parent?: Object, property?: LabelStyle) -> Label

Create a new Label widget. See the LVGL docs for details about this widget.

Arguments

• parent: The parent for this object, or nil to add to the screen root.
• property: Style properties to apply to this object

lvgl.Led

function lvgl.Led(parent?: Object, property?: LedStyle) -> Led

Create a new LED widget. See the LVGL docs for details about this widget.

Arguments

• parent: The parent for this object, or nil to add to the screen root.
• property: Style properties to apply to this object

lvgl.List

function lvgl.List(parent?: Object, property?: ListStyle) -> List

Create a new List widget. See the LVGL docs for details about this widget.

Arguments

• parent: The parent for this object, or nil to add to the screen root.
• property: Style properties to apply to this object

lvgl.OPA

function lvgl.OPA(p: integer) -> opacity: integer

Converts an opacity value as a percentage into the LVGL opacity range of 0 to 255.

Arguments

• p: opacity value in range of 0..100

Returns

value in the range of 0..255

lvgl.Object

function lvgl.Object(parent?: Object, property?: StyleProp) -> Object

Creates a new base LVGL object. See the LVGL docs for details about this widget.

Arguments

• parent: The parent for this object, or nil to add to the screen root.
• property: Style properties to apply to this object

lvgl.PCT

function lvgl.PCT(p: integer) -> size: integer

Converts a size in percent into an LVGL size value.

Arguments

• p: size percentage

Returns

in LVGL units

lvgl.Roller

function lvgl.Roller(parent?: Object, property?: RollerStyle) -> Roller

Create a new Roller widget. See the LVGL docs for details about this widget.

Arguments

• parent: The parent for this object, or nil to add to the screen root.
• property: Style properties to apply to this object

lvgl.Slider

function lvgl.Slider(parent?: Object, property?: BarStyle) -> Slider

Create a new Slider widget. See the LVGL docs for details about this widget.

Arguments

• parent: The parent for this object, or nil to add to the screen root.
• property: Style properties to apply to this object. Sliders use the same style properties as Bars.

lvgl.Style

function lvgl.Style(p?: StyleProp) -> Style

Create a new style that can be applied to objects via obj:add_style.

Arguments

• p: Style properties that will be applied by this style.

lvgl.Switch

function lvgl.Switch(parent?: Object, property?: StyleProp) -> Switch

Create a new Switch widget. See the LVGL docs for details about this widget.

Arguments

• parent: The parent for this object, or nil to add to the screen root.
• property: Style properties to apply to this object

lvgl.Textarea

function lvgl.Textarea(parent?: Object, property?: TextareaStyle) -> Textarea

Create a new Text Area widget. See the LVGL docs for details about this widget.

Arguments

• parent: The parent for this object, or nil to add to the screen root.
• property: Style properties to apply to this object

lvgl.Timer

function lvgl.Timer(p: TimerPara) -> Timer

Create a new Timer. See the LVGL docs for more details on LVGL's Timers system.

Arguments

• p: Parameters to use for configuring the timer.

lvgl.VER_RES

function lvgl.VER_RES() -> integer

Returns the vertical resolution of the display.

lvgl.Align

Align parameter

Align.type

ObjAlignType

Enum for specifying what kind of alignment to use for an LVGL object. See the LVGL docs for an explanation of each value.

lvgl.AlignToPara

AlignTo parameter

AlignToPara.base

Object

Base LVGL object. See the LVGL docs for additional details.

AlignToPara.type

ObjAlignType

Enum for specifying what kind of alignment to use for an LVGL object. See the LVGL docs for an explanation of each value.

lvgl.Anim

Anim

Anim.delete

(method) Anim:delete() -> nil

delete animation

Anim.set

(method) Anim:set(para: AnimPara) -> nil

set animation new parameters

Arguments

• para: new animation parameters

Anim.start

(method) Anim:start() -> nil

start animation

Anim.stop

(method) Anim:stop() -> nil

stop animation

lvgl.AnimPara

AnimPara.delay

integer

Set a delay before starting the animation

AnimPara.duration

integer

Anim duration in milisecond

AnimPara.early_apply

boolean

set start_value right now or not. default: true

AnimPara.exec_cb

fun(obj: any, value: integer):nil

Anim(for object) parameter

AnimPara.repeat_count

integer

Anim repeat count, default: 1, set to 0 to disable repeat, set to lvgl.ANIM_REPEAT_INFINITE for infinite repeat, set to any other integer for specified repeate count

AnimPara.run

boolean

run this anim right now, or later using anim:start(). default: false

AnimPara.start_value

integer

start value

lvgl.Bar

Bar:Object

Bar widget

lvgl.BarRangePara

BarRange para

lvgl.BarStyle

BarStyle:StyleProp

Bar style

BarStyle.range

BarRangePara

BarRange para

lvgl.Button

Button:Object

Button widget

lvgl.ButtonStyle

ButtonStyle:StyleProp

Button style

lvgl.Calendar

Calendar:Object

Calendar widget

Calendar.Arrow

(method) Calendar:Arrow(p: any) -> Object

create a calendar header with drop-drowns to select the year and month.

Arguments

• p: nil

Calendar.get_btnm

(method) Calendar:get_btnm(p: any) -> Object

get the button matrix object of the calendar.

Arguments

• p: nil

Calendar.get_pressed

(method) Calendar:get_pressed(p: any) -> CalendarDatePara

get the currently pressed day

Arguments

• p: nil

Calendar.get_showed

(method) Calendar:get_showed(p: any) -> CalendarDatePara

get the currently showed date

Arguments

• p: nil

Calendar.get_today

(method) Calendar:get_today(p: any) -> CalendarDatePara

get today para setting from calendar widget

Arguments

• p: nil

lvgl.CalendarDatePara

CalendarToday para

lvgl.CalendarStyle

CalendarStyle:StyleProp

Checkbox style

CalendarStyle.showed

CalendarDatePara

CalendarToday para

CalendarStyle.today

CalendarDatePara

CalendarToday para

lvgl.Checkbox

Checkbox:Object

Checkbox widget

Checkbox.get_text

(method) Checkbox:get_text() -> string

Get the text of a label

lvgl.CheckboxStyle

CheckboxStyle:StyleProp

Checkbox style

lvgl.Coords

Coordinates

lvgl.Dir

Directions values for dropdown and scroll directions

Values

• Dir.ALL
• Dir.BOTTOM
• Dir.HOR
• Dir.LEFT
• Dir.NONE
• Dir.RIGHT
• Dir.TOP
• Dir.VER

lvgl.Dropdown

Dropdown:Object

Dropdown widget

Dropdown.add_option

(method) Dropdown:add_option(option: string, pos: integer)

Add an options to a drop-down list from a string

Arguments

• option: nil
• pos: nil

Dropdown.clear_option

(method) Dropdown:clear_option()

Tells whether the list is opened or not

Dropdown.close

(method) Dropdown:close()

Close (Collapse) the drop-down list

Dropdown.get

(method) Dropdown:get(which: string, arg?: string) -> string|Dir|Object

Gets an attribute of the dropdown.

Arguments

• which: Which property to retrieve. Valid values are "list", "options", "selected", "option_cnt", "selected_str", "option_index", "symbol", or "dir"
• arg: nil

Dropdown.is_open

(method) Dropdown:is_open()

Tells whether the list is opened or not

Dropdown.open

(method) Dropdown:open()

Open the drop down list

lvgl.DropdownStyle

DropdownStyle:StyleProp

Dropdown style

DropdownStyle.dir

Dir

Directions values for dropdown and scroll directions

lvgl.FlexAlign

Alignment values for flex layouts. See the LVGL docs for more details.

Values

• FlexAlign.CENTER
• FlexAlign.END
• FlexAlign.SPACE_AROUND
• FlexAlign.SPACE_BETWEEN
• FlexAlign.SPACE_EVENLY
• FlexAlign.START

lvgl.FlexFlow

Flow direction for flex layouts. See the LVGL docs for more details.

Values

• FlexFlow.COLUMN
• FlexFlow.COLUMN_REVERSE
• FlexFlow.COLUMN_WRAP
• FlexFlow.COLUMN_WRAP_REVERSE
• FlexFlow.ROW
• FlexFlow.ROW_REVERSE
• FlexFlow.ROW_WRAP
• FlexFlow.ROW_WRAP_REVERSE

lvgl.FlexLayoutPara

FlexLayoutPara.align_content

("center"|"flex-end"|"flex-start"|"space-around"|"space-between"...(+1))?

Alignment values for flex layouts. See the LVGL docs for more details.

FlexLayoutPara.align_items

("center"|"flex-end"|"flex-start"|"space-around"|"space-between"...(+1))?

Alignment values for flex layouts. See the LVGL docs for more details.

FlexLayoutPara.justify_content

("center"|"flex-end"|"flex-start"|"space-around"|"space-between"...(+1))?

Alignment values for flex layouts. See the LVGL docs for more details.

lvgl.Font

Font is a light userdata that can be used to set style text_font.

lvgl.GridAlign

Alignment values for grid layouts. See the LVGL docs for more details.

Values

• GridAlign.CENTER
• GridAlign.END
• GridAlign.SPACE_AROUND
• GridAlign.SPACE_BETWEEN
• GridAlign.SPACE_EVENLY
• GridAlign.START
• GridAlign.STRETCH

lvgl.Image

Image:Object

Image widget

Image.get_img_size

(method) Image:get_img_size(src?: string) -> integer 2. integer

get image size, return w,h w, h = img:get_img_size() w, h = img:get_img_size("/path/to/this/image.png")

Arguments

• src: nil

Image.set_offset

(method) Image:set_offset(p: table) -> nil

set image offset img:set_offset{x = 0, y = 100}

Arguments

• p: nil

Image.set_pivot

(method) Image:set_pivot(p: table) -> nil

set image pivot img:set_pivot{x = 0, y = 100}

Arguments

• p: nil

Image.set_src

(method) Image:set_src(src: string) -> nil

set image source

Arguments

• src: image source path

lvgl.ImageStyle

ImageStyle:StyleProp

Image style

ImageStyle.offset_x

integer

offset of image

lvgl.ImgData

Decoded image data that is pinned to memory.

lvgl.KEY

Values for KEY events.

Values

• KEY.BACKSPACE
• KEY.DEL
• KEY.DOWN
• KEY.END
• KEY.ENTER
• KEY.ESC
• KEY.HOME
• KEY.LEFT
• KEY.NEXT
• KEY.PREV
• KEY.RIGHT
• KEY.UP

lvgl.Keyboard

Keyboard:Object

Keyboard widget

lvgl.KeyboardMode

Keyboard modes

Values

• KeyboardMode.NUMBER
• KeyboardMode.SPECIAL
• KeyboardMode.TEXT_ARABIC
• KeyboardMode.TEXT_LOWER
• KeyboardMode.TEXT_UPPER
• KeyboardMode.USER_1
• KeyboardMode.USER_2
• KeyboardMode.USER_3
• KeyboardMode.USER_4

lvgl.KeyboardStyle

KeyboardStyle:StyleProp

Keyboard style

KeyboardStyle.mode

KeyboardMode

Keyboard modes

KeyboardStyle.popovers

boolean

Show the button title in a popover when pressed.

KeyboardStyle.textarea

Textarea

textarea object

lvgl.LABEL

Long modes for use with labels.

Values

• LABEL.LONG_CLIP
• LABEL.LONG_DOT
• LABEL.LONG_SCROLL
• LABEL.LONG_SCROLL_CIRCULAR
• LABEL.LONG_WRAP

lvgl.Label

Label:Object

Label widget

Label.cut_text

(method) Label:cut_text(pos: integer, cnt: integer) -> nil

Delete characters from a label.

Arguments

• pos: nil
• cnt: nil

Label.get_long_mode

(method) Label:get_long_mode() -> string

Get the long mode of a label

Label.get_recolor

(method) Label:get_recolor() -> string

Get the recoloring attribute

Label.get_text

(method) Label:get_text() -> string

Get the text of a label

Label.ins_text

(method) Label:ins_text(pos: integer, txt: string) -> nil

Insert a text to a label.

Arguments

• pos: nil
• txt: nil

lvgl.LabelStyle

LabelStyle:StyleProp

Label style

lvgl.Led

Led:Object

LED widget

Led.get_brightness

(method) Led:get_brightness() -> integer

get LED brightness

Led.off

(method) Led:off() -> nil

LED set to OFF

Led.on

(method) Led:on() -> nil

LED set to ON

Led.toggle

(method) Led:toggle() -> nil

toggle LED status

lvgl.LedStyle

LedStyle:StyleProp

Led style

LedStyle.brightness

integer

brightness in range of 0..255

LedStyle.color

string|integer

color of led

lvgl.List

List:Object

List widget

List.add_btn

(method) List:add_btn(icon: string|lightuserdata|nil, text?: string) -> a: Object

add button to list

Arguments

• icon:
• text: nil

Returns

button object

List.add_text

(method) List:add_text(text: string) -> Label

add text to list

Arguments

• text: nil

List.get_btn_text

(method) List:get_btn_text(btn: Object) -> string

get list button text

Arguments

• btn: Base LVGL object. See the LVGL docs for additional details.

lvgl.ListStyle

ListStyle:StyleProp

List style

lvgl.ObjAlignType

Enum for specifying what kind of alignment to use for an LVGL object. See the LVGL docs for an explanation of each value.

Values

• ObjAlignType.BOTTOM_LEFT
• ObjAlignType.BOTTOM_MID
• ObjAlignType.BOTTOM_RIGHT
• ObjAlignType.CENTER
• ObjAlignType.DEFAULT
• ObjAlignType.LEFT_MID
• ObjAlignType.OUT_BOTTOM_LEFT
• ObjAlignType.OUT_BOTTOM_MID
• ObjAlignType.OUT_BOTTOM_RIGHT
• ObjAlignType.OUT_LEFT_BOTTOM
• ObjAlignType.OUT_LEFT_MID
• ObjAlignType.OUT_LEFT_TOP
• ObjAlignType.OUT_RIGHT_BOTTOM
• ObjAlignType.OUT_RIGHT_MID
• ObjAlignType.OUT_RIGHT_TOP
• ObjAlignType.OUT_TOP_LEFT
• ObjAlignType.OUT_TOP_MID
• ObjAlignType.OUT_TOP_RIGHT
• ObjAlignType.RIGHT_MID
• ObjAlignType.TOP_LEFT
• ObjAlignType.TOP_MID
• ObjAlignType.TOP_RIGHT

lvgl.ObjEventCode

Event codes for use with obj:onevent. See the LVGL docs for a description of each event type.

Values

• ObjEventCode.ALL
• ObjEventCode.CANCEL
• ObjEventCode.CHILD_CHANGED
• ObjEventCode.CHILD_CREATED
• ObjEventCode.CHILD_DELETED
• ObjEventCode.CLICKED
• ObjEventCode.COVER_CHECK
• ObjEventCode.DEFOCUSED
• ObjEventCode.DELETE
• ObjEventCode.DRAW_MAIN
• ObjEventCode.DRAW_MAIN_BEGIN
• ObjEventCode.DRAW_MAIN_END
• ObjEventCode.DRAW_PART_BEGIN
• ObjEventCode.DRAW_PART_END
• ObjEventCode.DRAW_POST
• ObjEventCode.DRAW_POST_BEGIN
• ObjEventCode.DRAW_POST_END
• ObjEventCode.FOCUSED
• ObjEventCode.GESTURE
• ObjEventCode.GET_SELF_SIZE
• ObjEventCode.HIT_TEST
• ObjEventCode.INSERT
• ObjEventCode.KEY
• ObjEventCode.LAYOUT_CHANGED
• ObjEventCode.LEAVE
• ObjEventCode.LONG_PRESSED
• ObjEventCode.LONG_PRESSED_REPEAT
• ObjEventCode.PRESSED
• ObjEventCode.PRESSING
• ObjEventCode.PRESS_LOST
• ObjEventCode.READY
• ObjEventCode.REFRESH
• ObjEventCode.REFR_EXT_DRAW_SIZE
• ObjEventCode.RELEASED
• ObjEventCode.SCREEN_LOADED
• ObjEventCode.SCREEN_LOAD_START
• ObjEventCode.SCREEN_UNLOADED
• ObjEventCode.SCREEN_UNLOAD_START
• ObjEventCode.SCROLL
• ObjEventCode.SCROLL_BEGIN
• ObjEventCode.SCROLL_END
• ObjEventCode.SHORT_CLICKED
• ObjEventCode.SIZE_CHANGED
• ObjEventCode.STYLE_CHANGED
• ObjEventCode.VALUE_CHANGED

lvgl.ObjFlag

Flags that can be set for each LVGL object.

Values

• ObjFlag.ADV_HITTEST
• ObjFlag.CHECKABLE
• ObjFlag.CLICKABLE
• ObjFlag.CLICK_FOCUSABLE
• ObjFlag.EVENT_BUBBLE
• ObjFlag.FLOATING
• ObjFlag.GESTURE_BUBBLE
• ObjFlag.HIDDEN
• ObjFlag.IGNORE_LAYOUT
• ObjFlag.LAYOUT_1
• ObjFlag.LAYOUT_2
• ObjFlag.OVERFLOW_VISIBLE
• ObjFlag.PRESSED
• ObjFlag.PRESS_LOCK
• ObjFlag.SCROLLABLE
• ObjFlag.SCROLL_CHAIN
• ObjFlag.SCROLL_CHAIN_HOR
• ObjFlag.SCROLL_CHAIN_VER
• ObjFlag.SCROLL_ELASTIC
• ObjFlag.SCROLL_MOMENTUM
• ObjFlag.SCROLL_ONE
• ObjFlag.SCROLL_ON_FOCUS
• ObjFlag.SCROLL_WITH_ARROW
• ObjFlag.SNAPPABLE
• ObjFlag.USER_1
• ObjFlag.USER_2
• ObjFlag.USER_3
• ObjFlag.USER_4
• ObjFlag.WIDGET_1
• ObjFlag.WIDGET_2

lvgl.ObjState

States that can be set on each LVGL object. See the LVGL docs for an explanation of what each state means.

Values

• ObjState.ANY
• ObjState.CHECKED
• ObjState.DEFAULT
• ObjState.DISABLED
• ObjState.EDITED
• ObjState.FOCUSED
• ObjState.FOCUS_KEY
• ObjState.HOVERED
• ObjState.PRESSED
• ObjState.SCROLLED
• ObjState.USER_1
• ObjState.USER_2
• ObjState.USER_3
• ObjState.USER_4

lvgl.Object

Base LVGL object. See the LVGL docs for additional details.

Object.Anim

(method) obj:Anim(p: AnimPara) -> Anim

Create anim for object

Arguments

• p: nil

Object.Bar

(method) obj:Bar(property?: BarStyle) -> Bar

Create a new Bar widget as a child of this object. See the LVGL docs for details about this widget.

Arguments

• property: Style properties to apply to this object

Object.Button

(method) obj:Button(property?: StyleProp) -> Button

Create a new Button widget as a child of this object. See the LVGL docs for details about this widget.

Arguments

• property: Style properties to apply to this object

Object.Calendar

(method) obj:Calendar(property?: CalendarStyle) -> Calendar

Create a new Calendar widget as a child of this object. See the LVGL docs for details about this widget.

Arguments

• property: Style properties to apply to this object

Object.Checkbox

(method) obj:Checkbox(property?: CheckboxStyle) -> Checkbox

Create a new Checkbox widget as a child of this object. See the LVGL docs for details about this widget.

Arguments

• property: Style properties to apply to this object

Object.Dropdown

(method) obj:Dropdown(parent: any, property?: DropdownStyle) -> Dropdown

Create a new Dropdown widget as a child of this object. See the LVGL docs for details about this widget.

Arguments

• parent: nil
• property: Style properties to apply to this object

Object.Image

(method) obj:Image(property?: ImageStyle) -> Image

Create a new Image widget as a child of this object. See the LVGL docs for details about this widget.

Arguments

• property: Style properties to apply to this object

Object.Keyboard

(method) obj:Keyboard(property?: KeyboardStyle) -> Keyboard

Create a new Keyboard widget as a child of this object. See the LVGL docs for details about this widget.

Arguments

• property: Style properties to apply to this object

Object.Label

(method) obj:Label(property?: LabelStyle) -> Label

Create a new Label widget as a child of this object. See the LVGL docs for details about this widget.

Arguments

• property: Style properties to apply to this object

Object.Led

(method) obj:Led(property?: LedStyle) -> Led

Create a new LED widget as a child of this object. See the LVGL docs for details about this widget.

Arguments

• property: Style properties to apply to this object

Object.List

(method) obj:List(property?: ListStyle) -> List

Create a new List widget as a child of this object. See the LVGL docs for details about this widget.

Arguments

• property: Style properties to apply to this object

Object.Object

(method) obj:Object(property?: StyleProp) -> Object

Creates a new base LVGL object as a child of this object. See the LVGL docs for details about this widget.

Arguments

• property: Style properties to apply to this object

Object.Roller

(method) obj:Roller(parent: any, property?: RollerStyle) -> Roller

Create a new Roller widget as a child of this object. See the LVGL docs for details about this widget.

Arguments

• parent: nil
• property: Style properties to apply to this object

Object.Slider

(method) obj:Slider(property?: BarStyle) -> Slider

Create a new Slider widget as a child of this object. See the LVGL docs for details about this widget.

Arguments

• property: Style properties to apply to this object. Sliders use the same style properties as Bars.

Object.Switch

(method) obj:Switch(property?: StyleProp) -> Switch

Create a new Switch widget as a child of this object. See the LVGL docs for details about this widget.

Arguments

• property: Style properties to apply to this object

Object.Textarea

(method) obj:Textarea(property?: TextareaStyle) -> Textarea

Create a new Text Area widget as a child of this object. See the LVGL docs for details about this widget.

Arguments

• property: Style properties to apply to this object

Object.add_flag

(method) obj:add_flag(p: ObjFlag) -> nil

add flag to object

Arguments

• p: Flags that can be set for each LVGL object.

Object.add_state

(method) obj:add_state(p: ObjState) -> nil

add state to object

Arguments

• p: States that can be set on each LVGL object. See the LVGL docs for an explanation of what each state means.

Object.add_style

(method) obj:add_style(s: Style, selector?: integer) -> nil

add style to object

Arguments

• s:
• selector: nil

Object.align_to

(method) obj:align_to(p: AlignToPara)

Sets this object's position relative to another object.

Arguments

• p: AlignTo parameter

Object.center

(method) obj:center() -> nil

Align an object to the center on its parent. same as obj:set{align={type = lvgl.ALIGN.CENTER}}

Object.clean

(method) obj:clean()

Delete all children of this object

Object.clear_flag

(method) obj:clear_flag(p: ObjFlag) -> nil

clear object flag

Arguments

• p: Flags that can be set for each LVGL object.

Object.clear_state

(method) obj:clear_state(p: ObjState) -> nil

clear object state

Arguments

• p: States that can be set on each LVGL object. See the LVGL docs for an explanation of what each state means.

Object.delete

(method) obj:delete()

Deletes this object, removing it from the view hierarchy.

Object.focus

(method) obj:focus() -> nil

Sets this object as the current selection of the object's group.

Object.get_child

(method) obj:get_child(id: integer) -> Object

get child object

Arguments

• id: 0 the first child, -1 the lastly created child

Object.get_child_cnt

(method) obj:get_child_cnt() -> integer

get object children count

Object.get_coords

(method) obj:get_coords() -> coords: Coords

Get coords of object

Object.get_parent

(method) obj:get_parent() -> Parent: Object

Gets this object's parent

Object.get_pos

(method) obj:get_pos() -> coords: Coords

Get real postion of object relative to its parent

Object.get_state

(method) obj:get_state(p: any) -> ObjState

get the state of this object

Arguments

• p: nil

Object.invalidate

(method) obj:invalidate() -> nil

Align an object to the center on its parent. same as obj:set{align={type = lvgl.ALIGN.CENTER}}

Object.is_editable

(method) obj:is_editable() -> boolean

If object is editable

Object.is_group_def

(method) obj:is_group_def() -> boolean

class group def

Object.is_layout_positioned

(method) obj:is_layout_positioned() -> boolean

Test whether the and object is positioned by a layout or not

Object.is_scrolling

(method) obj:is_scrolling() -> boolean

Tell whether an object is being scrolled or not at this moment

Object.is_visible

(method) obj:is_visible() -> boolean

Tell whether an object is visible (even partially) now or not

Object.mark_layout_as_dirty

(method) obj:mark_layout_as_dirty() -> nil

Mark the object for layout update.

Object.onClicked

(method) obj:onClicked(cb: fun(obj: Object, code: ObjEventCode):nil) -> nil

set object clicked event callback, same as obj:onevent(lvgl.EVENT.CLICKED, cb)

Arguments

• cb: Object event callback. para is not used for now.

Object.onPressed

(method) obj:onPressed(cb: fun(obj: Object, code: ObjEventCode):nil) -> nil

set object pressed event callback, same as obj:onevent(lvgl.EVENT.PRESSED, cb)

Arguments

• cb: Object event callback. para is not used for now.

Object.onShortClicked

(method) obj:onShortClicked(cb: fun(obj: Object, code: ObjEventCode):nil) -> nil

set object short clicked event callback, same as obj:onevent(lvgl.EVENT.SHORT_CLICKED, cb)

Arguments

• cb: Object event callback. para is not used for now.

Object.onevent

(method) obj:onevent(code: ObjEventCode, cb: fun(obj: Object, code: ObjEventCode):nil) -> nil

set object event callback

Arguments

• code: Event codes for use with obj:onevent. See the LVGL docs for a description of each event type.
• cb: Object event callback. para is not used for now.

Object.parent

(method) obj:parent(p: Object) -> Object

set and/or get object's parent

Arguments

• p: Base LVGL object. See the LVGL docs for additional details.

Object.readjust_scroll

(method) obj:readjust_scroll(anim_en: boolean)

Checked if the content is scrolled "in" and adjusts it to a normal position.

Arguments

• anim_en: nil

Object.remove_style

(method) obj:remove_style(s: Style, selector?: integer) -> nil

remove style from object

Arguments

• s:
• selector: nil

Object.remove_style_all

(method) obj:remove_style_all() -> nil

remove all style from object

Object.scroll_by

(method) obj:scroll_by(x: integer, y: integer, anim_en?: boolean)

scroll obj by x,y

Arguments

• x: nil
• y: nil
• anim_en: nil

Object.scroll_by_bounded

(method) obj:scroll_by_bounded(x: integer, y: integer, anim_en: boolean)

scroll obj by x,y

Arguments

• x: nil
• y: nil
• anim_en: nil

Object.scroll_by_raw

(method) obj:scroll_by_raw(x: integer, y: integer, anim_en: boolean)

scroll obj by x,y, low level APIs

Arguments

• x: nil
• y: nil
• anim_en: nil

Object.scroll_to

(method) obj:scroll_to(p: ScrollToPara) -> ObjState

Scroll to a given coordinate on an object.

Arguments

• p: Scroll to a given coordinate on an object.

Object.scroll_to_view

(method) obj:scroll_to_view(anim_en?: boolean)

Scroll to an object until it becomes visible on its parent

Arguments

• anim_en: nil

Object.scroll_to_view_recursive

(method) obj:scroll_to_view_recursive(anim_en?: boolean)

Scroll to an object until it becomes visible on its parent Do the same on the parent's parent, and so on. Therefore the object will be scrolled into view even it has nested scrollable parents

Arguments

• anim_en: nil

Object.scrollbar_invalidate

(method) obj:scrollbar_invalidate()

Invalidate the area of the scrollbars

Object.set

(method) obj:set(p: StyleProp)

Sets new style properties on this object.

Arguments

• p: Style properties to be applied.

Object.set_parent

(method) obj:set_parent(p: Object)

Sets the parent of this object, detaching it from any existing parent.

Arguments

• p: The new parent object

Object.set_style

(method) obj:set_style(p: StyleProp, selector: integer)

Sets new style properties on this object.

Arguments

• p: Style properties to be applied.
• selector: Selector to detemine when the style is used

lvgl.ObjectStyle

ObjectStyle:StyleProp

Object style

ObjectStyle.align_to

AlignToPara

AlignTo parameter

ObjectStyle.scroll_dir

Dir

Directions values for dropdown and scroll directions

ObjectStyle.scrollbar_mode

ScrollbarMode

Scroll modes

lvgl.Roller

Roller:Object

Roller widget

Roller.get_options

(method) Roller:get_options() -> string

Get the options of a roller

Roller.get_options_cnt

(method) Roller:get_options_cnt() -> integer

Get the total number of options

Roller.get_selected

(method) Roller:get_selected() -> integer

Get the index of the selected option

Roller.get_selected_str

(method) Roller:get_selected_str() -> string

Get the current selected option as a string.

lvgl.RollerStyle

RollerStyle:StyleProp

Roller style

lvgl.ScrollToPara

Scroll to a given coordinate on an object.

ScrollToPara.x

integer

position x

lvgl.ScrollbarMode

Scroll modes

Values

• ScrollbarMode.ACTIVE
• ScrollbarMode.AUTO
• ScrollbarMode.OFF
• ScrollbarMode.ON

lvgl.Slider

Slider:Object

Slider widget

Slider.is_dragged

(method) Slider:is_dragged() -> boolean

get whether slider is dragged or not

Slider.value

(method) Slider:value() -> integer

get value of slider

lvgl.Style

Style:lightuserdata

Style.delete

(method) Style:delete() -> nil

delete style, only delted style could be gc'ed

Style.remove_prop

(method) Style:remove_prop(p: string) -> nil

remove specified property from style

Arguments

• p: property name from field of StyleProp

Style.set

(method) Style:set(p: StyleProp) -> nil

update style properties

Arguments

• p: Style properties

lvgl.StyleProp

Style properties

StyleProp.align

(Align|ObjAlignType)?

Align parameter

StyleProp.bg_color

string|integer

text color in hex integer or #RGB or #RRGGBB format

StyleProp.flex_cross_place

FlexAlign?

Alignment values for flex layouts. See the LVGL docs for more details.

StyleProp.flex_flow

FlexFlow?

Flow direction for flex layouts. See the LVGL docs for more details.

StyleProp.flex_grow

integer

0..255

StyleProp.flex_main_place

FlexAlign?

Alignment values for flex layouts. See the LVGL docs for more details.

StyleProp.size

integer

set size is equivalent to set w/h to same value

StyleProp.text_decor

integer

@field text_line_space/ integer

StyleProp.text_font

Font?

Font is a light userdata that can be used to set style text_font.

lvgl.Switch

Switch:Object

Switch widget

Switch.enabled

(method) Switch:enabled() -> boolean

get checked state of switch

lvgl.Textarea

Textarea:Object

Textarea widget

Textarea.get_text

(method) Textarea:get_text(p: any) -> string

get textarea text

Arguments

• p: nil

lvgl.TextareaStyle

TextareaStyle:StyleProp

Textarea style

TextareaStyle.accepted_chars

string

DO NOT USE. Set a list of characters. Only these characters will be accepted by the text area E.g. "+-.,0123456789"

TextareaStyle.cursor

integer

cursor position

TextareaStyle.max_length

integer

Set max length of a Text Area.

TextareaStyle.one_line

boolean

enable one line mode

TextareaStyle.password_bullet

string

Set the replacement characters to show in password mode

TextareaStyle.password_mode

boolean

enable password

TextareaStyle.password_show_time

integer

Set how long show the password before changing it to '*'

lvgl.Timer

Timer

Timer.delete

(method) Timer:delete() -> nil

delete timer

Timer.pause

(method) Timer:pause() -> nil

pause timer

Timer.ready

(method) Timer:ready() -> nil

make timer ready now, cb will be made soon on next loop

Timer.resume

(method) Timer:resume() -> nil

resume timer

Timer.set

(method) Timer:set(p: TimerPara) -> nil

set timer property

Arguments

• p: nil

lvgl.TimerPara

TimerPara.cb

fun(t: Timer):nil

Timer para

TimerPara.paused

boolean

Do not start timer immediaely

TimerPara.period

integer

timer period in ms unit

playback

The playback module contains Properties and functions for interacting the device's audio pipeline.

playback.is_playable

function playback.is_playable(filepath: string) -> boolean

Returns whether or not this file can be played (i.e. is this an audio track)

Arguments

• filepath: nil

playback.playing

Property

Whether or not audio is allowed to be played. if there is a current track, then this indicated whether playback is paused or unpaused. If there is no current track, this determines what will happen when the first track is added to the queue.

playback.position

Property

The current playback position within the current track, in seconds.

playback.track

Property

The currently playing track.

power

The power module contains properties and functions that relate to the device's battery and charging state.

power.battery_millivolts

Property

The battery's current voltage, in millivolts.

power.battery_pct

Property

The battery's current charge, as a percentage of the maximum charge.

power.charge_state

Property

a string property describing the current charging state. May be one of "no_battery", "critical", "discharging", "charge_regular", "charge_fast", "full_charge", "fault", or "unknown".

power.fast_charge

Property

Whether or not fast charging is enabled. Fast charging can fully recharge the battery up to two times faster than regular charging, but will have a small negative impact on the lifetime of the battery.

power.plugged_in

Property

Whether or not the device is currently receiving external power.

queue

The queue module contains Properties and functions that relate to the device's playback queue. This is a persistent, disk-backed list of TrackIds that includes the currently playing track, tracks that have been played, and tracks that are scheduled to be played after the current track has finished.

queue.add

function queue.add(val: string|Iterator|TrackId)

Adds the given track, database iterator, or file to the end of the queue. Database iterators passed to this method will be unnested and expanded into the track ids they contain.

Arguments

• val: A TrackId is a unique identifier, representing a playable track in the user's library.

queue.clear

function queue.clear()

Removes all tracks from the queue.

queue.next

function queue.next()

Moves forward in the play queue, looping back around to the beginning if repeat is on.

queue.open_playlist

function queue.open_playlist(filepath: string)

Opens a playlist file from a filepath This will replace the existing queue

Arguments

• filepath: nil

queue.position

Property

The index in the queue of the currently playing track. This may be zero if the queue is empty. Writeable.

queue.previous

function queue.previous()

Moves backward in the play queue, looping back around to the end if repeat is on.

queue.random

Property

Determines whether, when progressing to the next track in the queue, the next track will be chosen randomly. The random selection algorithm used is a Miller Shuffle, which guarantees that no repeat selections will be made until every item in the queue has been played. Writeable.

queue.repeat_track

Property

Whether or not the current track will repeat indefinitely. Writeable.

queue.replay

Property

Whether or not the queue will be restarted after the final track is played. Writeable.

queue.size

Property

The total number of tracks in the queue, including tracks which have already been played.

screen

A distinct full-screen UI. Each screen has an associated LVGL UI tree and group, and can be shown on-screen using the 'backstack' module. Screens make use of prototype inheritance in order to provide a consistent interface for the C++ firmware to work with. See Programming in Lua, chapter 16.

screen.can_pop

(method) screen:can_pop()

Called when this screen is about to be popped off of the stack. If this returns false, it will not be popped. May be a function, or any boolean convertable value.

screen.create_ui

(method) screen:create_ui()

Called just before this screen is first displayed to the user.

screen.new

(method) screen:new(params: any)

Creates a new screen instance.

Arguments

• params: nil

screen.on_hide

(method) screen:on_hide()

Called whenever this screen is being hidden by the user; either because a new screen is being pushed on top of this way, or because this screen has been popped off of the stack.

screen.on_show

(method) screen:on_show()

Called whenever this screen is displayed to the user.

theme

theme.load_theme

function theme.load_theme(filename: string) -> boolean

Loads a theme from a filename, this can be either builtin (ie, located in "/lua/") or on the sdcard (in, '/sdcard/.themes/') If successful, the filename will be saved to non-volatile storage. Returns whether the theme was successfully loaded

Arguments

• filename: nil

theme.set

function theme.set(theme: any)

Sets a theme directly from a table. Does not persist between restarts.

Arguments

• theme: nil

theme.set_style

function theme.set_style(obj: Object, style: string)

Set the style name (similar in concept to a css selector) for an object This will set any styles associated with that style name on the object

Arguments

• obj: The object to set a particular style on
• style: The name of the style to apply to this object

theme.theme_filename

function theme.theme_filename() -> string

Returns the filename of the saved theme

time

The time module contains functions for dealing with the current time since boot.

time.ticks

function time.ticks() -> integer

Returns the time in milliseconds since the device booted.

types

types.Property

A observable value, owned by the C++ firmware.

Property.bind

(method) Property:bind(fn: function)

Invokes the given function once immediately with the current value, and then again whenever the value changes. The function is invoked for all changes; both from the underlying C++ data, and from calls to set (if this is a Lua-writeable property). The binding will be active only so long as the given function remains in scope.

Arguments

• fn: callback to apply property values. Must accept one argument; the updated value.

Property.get

(method) Property:get() -> val: boolean|string|integer|table

Returns

Returns the property's current value

Property.set

(method) Property:set(val?: boolean|string|integer|table) -> success: boolean

Sets a new value. Not all properties may be set from within Lua code. For example, it makes little sense to attempt to override the current battery level.

Arguments

• val: The new value. Optional; if not argument is passed, the property will be set to 'nil'.

Returns

whether or not the new value was accepted

volume

Module for interacting with playback volume. The Bluetooth and wired outputs store their current volume separately; this API only allows interacting with the volume of the currently used output device.

volume.current_db

Property

The current volume in terms of decibels relative to line level (only applicable to headphone output)

volume.current_pct

Property

The current volume as a percentage of the current volume limit.

volume.left_bias

Property

An additional modifier in decibels to apply to the left channel (only applicable to headphone output)

volume.limit_db

Property

The maximum allowed output volume, in terms of decibels relative to line level (only applicable to headphone output)