Skip to main content

LVGL UI API

ElenixOS provides rich UI components and interfaces based on the LVGL (LittlevGL) graphics library, allowing developers to create and manage user interfaces in JavaScript. This document will detail the LVGL UI API exposed by ElenixOS to the script runtime, based on the usage in actual project engineering.

Basic Concepts​

Introduction to LVGL​

LVGL is a lightweight embedded graphics library designed for resource-constrained devices such as microcontrollers. It provides rich UI components and features, including:

  • Various UI controls (buttons, labels, input fields, etc.)
  • Layout system
  • Style system
  • Animation effects
  • Event handling

API Namespace​

In ElenixOS, the LVGL API is exposed to JavaScript scripts through the lv namespace:

// Create a label
const label = new lv.label(eos.view.active());
label.setText("Hello, ElenixOS!");

Component Creation and Layout​

Component Creation​

Create UI components using constructor methods:

// Create a button
const button = new lv.button(eos.view.active());

// Create a label
const label = new lv.label(button);
label.setText("Click Me");

Layout System​

LVGL provides multiple layout methods, including:

Absolute Layout​

// Set component position
button.setPos(10, 10);

// Set component size
button.setSize(100, 50);

Flex Layout​

// Create a flex layout container
const container = new lv.obj(eos.view.active());
container.setSize(lv.pct(100), 50);
container.align(lv.ALIGN_CENTER, 0, 0);
container.setFlexFlow(lv.FLEX_FLOW_ROW);

// Add child components
const button1 = new lv.button(container);
const label1 = new lv.label(button1);
label1.setText("Button 1");

const button2 = new lv.button(container);
const label2 = new lv.label(button2);
label2.setText("Button 2");

Grid Layout​

// Create a grid layout container
const container = new lv.obj(eos.view.active());
container.setSize(lv.pct(100), 100);
container.align(lv.ALIGN_CENTER, 0, 0);

// Add child components
const button1 = new lv.button(container);
button1.setSize(100, 50);
button1.align(lv.ALIGN_TOP_LEFT, 10, 10);

const button2 = new lv.button(container);
button2.setSize(100, 50);
button2.align(lv.ALIGN_TOP_RIGHT, -10, 10);

const button3 = new lv.button(container);
button3.setSize(100, 50);
button3.align(lv.ALIGN_BOTTOM_LEFT, 10, -10);

const button4 = new lv.button(container);
button4.setSize(100, 50);
button4.align(lv.ALIGN_BOTTOM_RIGHT, -10, -10);

Event Binding Methods​

Event Types​

LVGL supports multiple event types, such as click, release, long press, etc.:

Event TypeDescription
lv.EVENT_CLICKEDComponent is clicked
lv.EVENT_PRESSEDComponent is pressed
lv.EVENT_RELEASEDComponent is released
lv.EVENT_LONG_PRESSEDComponent is long pressed
lv.EVENT_VALUE_CHANGEDComponent value changes

Binding Events​

Use the addEventCb method to bind events:

// Bind click event
button.addEventCb((e) => {
    console.log("Button clicked!");
}, lv.EVENT_CLICKED, null);

// Bind value change event
const slider = new lv.slider(eos.view.active());
slider.addEventCb((e) => {
    const value = slider.getValue();
    console.log("Slider value:", value);
}, lv.EVENT_VALUE_CHANGED, null);

Event Handling​

const container = new lv.obj(eos.view.active());
const button = new lv.button(container);

// Bind container click event
container.addEventCb((e) => {
    console.log("Container clicked!");
}, lv.EVENT_CLICKED, null);

// Bind button click event
button.addEventCb((e) => {
    console.log("Button clicked!");
}, lv.EVENT_CLICKED, null);

Styles and Themes​

Style Settings​

// Set button style
const button = new lv.button(eos.view.active());
button.setSize(180, 64);
button.align(lv.ALIGN_CENTER, 0, 20);

// Set label style
const label = new lv.label(button);
label.setText("Click Me");
label.center();

Component States​

// Set component flags
button.addFlag(lv.OBJ_FLAG_CLICKABLE);
button.addFlag(lv.OBJ_FLAG_CHECKABLE);

// Check component flags
if (button.hasFlag(lv.OBJ_FLAG_CLICKABLE)) {
    console.log("Button is clickable");
}

if (button.hasFlag(lv.OBJ_FLAG_CHECKABLE)) {
    console.log("Button is checkable");
}

Common Control Examples​

Button​

// Create button
const button = new lv.button(eos.view.active());
button.setSize(180, 64);
button.align(lv.ALIGN_CENTER, 0, 20);

// Add label
const label = new lv.label(button);
label.setText("Click Me");
label.center();

// Set flags
button.addFlag(lv.OBJ_FLAG_CLICKABLE);
button.addFlag(lv.OBJ_FLAG_CHECKABLE);

// Bind event
let cbFired = false;
button.addEventCb((e) => {
    cbFired = true;
    console.log("Button clicked!");
}, lv.EVENT_CLICKED, null);

// Send event
button.sendEvent(lv.EVENT_CLICKED, null);

Label​

// Create label
const label = new lv.label(eos.view.active());
label.setText("Hello, ElenixOS!");
label.align(lv.ALIGN_TOP_MID, 0, 10);

Slider​

// Create slider
const slider = new lv.slider(eos.view.active());
slider.setSize(200, 20);
slider.align(lv.ALIGN_CENTER, 0, 0);
slider.setRange(0, 100);
slider.setValue(50, false);

// Bind event
slider.addEventCb((e) => {
    const value = slider.getValue();
    console.log("Slider value:", value);
}, lv.EVENT_VALUE_CHANGED, null);

Screen​

// Get current active screen
const scr = eos.view.active();

// Create component on screen
const button = new lv.button(scr);
button.setSize(180, 64);
button.align(lv.ALIGN_CENTER, 0, 0);

Animation Effects​

Create Animation​

// Create an object
const obj = new lv.obj(eos.view.active());
obj.setSize(100, 100);
obj.setPos(50, 50);

// Create animation
const anim = new lv.anim();
anim.setVar(obj);
anim.setValues(50, 200);
anim.setDuration(1000);
anim.setExecCb((varObj, value) => {
    varObj.setX(value);
});
anim.start();