Lua Scripting

Tangara's firmware includes extensive support for the Lua programming language. Lua is a small but very expressive scripting language, and is very easy to learn. If this is your first time encountering Lua, then the online version of Programming in Lua is an excellent read.

All of Tangara's UI is written in Lua, using bindings to the LVGL graphics library, as well as a small two-way data binding framework implemented in the C++ firmware.

Developing in Lua

Tangara's default Lua UI is located in the lua/ subdirectory of the ESP32 firmware repository. This directory is assembled into an SPIFFS filesystem image, and then flashed onto your device as a part of a standard idf.py flash.

If your editor supports LSP, then you may want to consider installing an configuring lua-language-server for completions, formatting, and diagnostics. A configuration file, .luarc.json, is already provided in the root of the ESP32 repository. This file configures the language server to use the stub modules in luals-stubs/ to generate completions for modules that are provided by the C++ firmware.

Interactive REPL

When using the USB serial console on your device, you can access a basic Lua REPL environment for interactive testing. You can access this environment by entering lua into the console.

At time of writing, the REPL environment is somewhat limited, as it is missing a number of bindings that are available to the Lua scripts responsible for the UI.

The REPL is built using lua-term and lua-repl, which are flashed to the 'repl' partition on your device as a part of a standard build (although you will not usually ever need to modify this partition).

API Reference

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.

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.devices

Property

Devices nearby that have been discovered.

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.paired_device

Property

The device that is currently paired. The bluetooth stack will automatically connected 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.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

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

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

Arguments
  • option: nil
  • pos: nil

(method) Dropdown:clear_option()

Tells whether the list is opened or not

(method) Dropdown:close()

Close (Collapse) the drop-down list

(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

(method) Dropdown:is_open()

Tells whether the list is opened or not

(method) Dropdown:open()

Open the drop down list

lvgl.DropdownStyle

DropdownStyle:StyleProp

Dropdown style

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 uset 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.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

(BuiltinFont|Font)?

Font is a light userdata that can be uset 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.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.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: Iterator|TrackId)

Adds the given track or database iterator 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.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.createUi

(method) screen:createUi()

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.onHidden

(method) screen:onHidden()

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.onShown

(method) screen:onShown()

Called whenever this screen is displayed to the user.

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)