Introduction¶
LVGL is capable of loading UI elements written in XML. The XML file can be written by hand, but it's highly recommended to use LVGL's UI |nbsp| Editor to write the XML files. The UI Editor provides features like:
Instant preview of the XML files
Autocomplete and Syntax highlighting
Online preview for collaboration and testing
Figma integration to easily reimplement the designs
Warning
The UI Editor and the XML loader are still under development and not production-ready. Consider them as an open beta, or experimental features.
Describing the UI in XML in a declarative manner offers several advantages:
XML files can be loaded at runtime (e.g., from an SD card) to change the application build.
XML is simpler to write than C, enabling people with different skill sets to create LVGL UIs.
XML is textual data, making it easy to parse and manipulate with a large number of programming and scripting languages.
XML can be used to generate LVGL code in any language.
XML helps to separate the view from the internal logic.
Concept¶
The XML files are Component-oriented. To be more specific, they are Component-Library
oriented.
That is, they are structured in a way to make it easy to create reusable Component Libraries.
For example, a company can have a Component Library for the basic Widgets for all its products (generic widgets for all smart devices), and create other industry-specific Libraries (smart-home specific, smart-watch specific, etc.) containing only a few extra Widgets and Components.
These Component Libraries are independent, can be reused across many products, and can be freely versioned and managed.
Imagine a Component Library as a collection of XML files that describe Widgets, Components, Screens, images, fonts, and other assets stored in a git repository, which can be a submodule in many projects.
If someone finds a bug in the Component Library, they can just fix it in one place and push it back to the git repository so that other projects can be updated from it.
The built-in Widgets of LVGL are also considered a Component Library
which is
always available.
A UI Editor project can have any number of Component Libraries but will always have at least 2:
LVGL's built-in Widgets, and
XML-based definitions of Screen contents, along with other project-specific Components.
Widgets, Components, and Screens¶
It is important to distinguish between Widgets, Components, and Screens.
Widgets¶
Widgets are the core building blocks of the UI and are not meant to be loaded at runtime but rather compiled into the application. The main characteristics of Widgets are:
In XML, they start with a
<widget>
root element.They are similar to LVGL's built-in Widgets.
They are built using
lv_obj_class
objects.They have custom and complex logic inside.
They cannot be loaded from XML at runtime because the custom code cannot be loaded.
They can have a large API with
set/get/add
functions.They can themselves contain Widgets as children (e.g.,
Tabview
's tabs,Dropdown
's lists).
Any handwritten Widget can be accessed from XML by:
Defining its API in an XML file.
Writing and registering an XML parser for it. See some examples here.
Components¶
Components are built from other Components and Widgets, and can be loaded at runtime. The main characteristics of Components are:
In XML, they start with a
<component>
root element.They are built in XML only and cannot have custom C code.
They can be loaded from XML as they don't contain custom C code, only XML.
They are built from Widgets or other Components.
They can be used for styling Widgets and other Components.
They can contain (as children) Widgets or other Components.
They can have a simple API to pass properties to their children (e.g.,
btn_text
to a Label's text).
Regardless of whether the XML was written manually or by the UI Editor, the XML files of Components can be registered in LVGL, and after that, instances can be created. In other words, LVGL can just read the XML files, "learn" the Components from them, and thereafter create children as part of Screens and other Components.
Screens¶
Screens are similar to Components:
In XML, they start with a
<screen>
root element.They are built from Widgets or other Components to describe the Screen.
They can be loaded from XML at runtime as they describe only visual aspects of the UI.
They do not have an API.
They can be referenced in Screen load events.