Mirrors_UI_SDK/lvgl
1
0
Fork 0
mirror of https://github.com/lvgl/lvgl.git synced 2026-05-13 07:18:06 +08:00
Code Issues Actions 34 Packages Projects Releases Wiki Activity

docs(xml): results of minor amount of proofreading (#8604)

Browse Source 
Co-authored-by: Gabor Kiss-Vamosi <kisvegabor@gmail.com>
Co-authored-by: Liam Howatt <30486941+liamHowatt@users.noreply.github.com>
This commit is contained in:
Victor Wheeler
2025-08-15 13:13:41 -06:00
committed by GitHub
parent bc807250b4
commit 6e9fa152fe
6 changed files with 54 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/src/CHANGELOG.rst
+1 -1
View File
@@ -11,7 +11,7 @@ Summary
This is a significant release packed with exciting updates from both our community and internal team.
One of the most notable additions is **XML support**, enabling you to describe your UI in a declarative manner. This way LVGL UI can be loaded at runtime without recompiling and deploying the application. This feature is also a key requirement for the upcoming `UI Editor <https://docs.lvgl.io/master/details/auxiliary-modules/xml/intro.html>`_ we're developing.
One of the most notable additions is **XML support**, enabling you to describe your UI in a declarative manner. This way LVGL UI can be loaded at runtime without recompiling and deploying the application. This feature is also a key requirement for the upcoming `UI editor <https://docs.lvgl.io/master/details/auxiliary-modules/xml/intro.html>`_ we're developing.
The `documentation <https://docs.lvgl.io/master/>`_ has been thoroughly reorganized and proofread.
docs/src/details/xml/build_ui/assets/fonts.rst
+1 -1
View File
@@ -130,5 +130,5 @@ After calling this function, when ``"font_name"`` is used as a font in XML, ``&m
Notes for the UI Editor
-----------------------
For simplicity, in the UI |nbsp| Editor's preview, fonts are always loaded as tinyttf fonts.
For simplicity, in the UI editor's preview, fonts are always loaded as tinyttf fonts.
It makes the preview dynamic as no code export and compilation is needed when a font changes.
docs/src/details/xml/build_ui/assets/images.rst
+1 -1
View File
@@ -71,6 +71,6 @@ After calling this function, when ``"image_name"`` is used as an image source in
Notes for the UI Editor
-----------------------
For simplicity, in the UI |nbsp| Editor's preview, images are always loaded as files.
For simplicity, in the UI editor's preview, images are always loaded as files.
It makes the preview dynamic so no code export and compilation is needed when an image changes.
docs/src/details/xml/index.rst
+1
View File
@@ -4,6 +4,7 @@
XML - Declarative UI
====================
.. toctree::
:class: toctree-1-deep
:maxdepth: 2
docs/src/details/xml/license.rst
+2 -2
View File
@@ -29,7 +29,7 @@ You are permitted to:
- Use this Specification in **any firmware or embedded application** built on top of the official `LVGL library <https://github.com/lvgl/lvgl>`_ (MIT-licensed).
- Use the LVGL XML loader freely in accordance with its MIT license.
- Use the Specification with the **LVGL UI Editor** and **official LVGL tools such as the CLI or XML loader**.
- Use the Specification with the **LVGL UI editor** and **official LVGL tools such as the CLI or XML loader**.
- Write, load, edit, or generate user interfaces described in the LVGL XML Specification for **internal use** only, including automation or configuration tools used solely inside your organization.
- Create **internal scripts or plugins** that help your own developers use or manage this Specification, as long as these are **not shared outside your organization or made publicly available**.
- Share XML-based UI files within customer firmware or projects that target LVGL-based embedded systems.
@@ -55,7 +55,7 @@ You are **explicitly permitted** to:
- Use XML files with this Specification in your own projects.
- Load XMLs at runtime using LVGL’s XML loader.
- Generate XMLs using the LVGL UI Editor.
- Generate XMLs using the LVGL UI editor.
- Customize XMLs manually or with internal utilities.
- Share LVGL-based projects with XML files as part of a commercial product or firmware.
docs/src/details/xml/overview/intro.rst
+48 -31
View File
@@ -7,27 +7,38 @@ Introduction
.. |nbsp| unicode:: U+000A0 .. NO-BREAK SPACE
:trim:
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 <https://lvgl.io/editor>`__ to write the XML files. The UI |nbsp| Editor provides
features like:
The LVGL XML Module implements LVGL's Declarative UI by loading UI elements written in
XML. The XML file can be written by hand, but it's highly recommended to use `LVGL's
UI editor <https://lvgl.io/editor>`__ to write the XML files. This UI editor
provides features like:
- Instant preview of the XML files
- Autocomplete and Syntax highlighting
- Online preview for collaboration and testing
- `Figma <https://www.figma.com/>`__ integration to easily reimplement the designs
- `Figma <https://www.figma.com/>`__ integration to easily reimplement Figma designs
.. warning::
The UI |nbsp| Editor and the XML loader are still under development and not production-ready.
Consider them as an open beta, or experimental features.
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 files can be loaded at runtime (e.g. from an SD card) allowing you to change
the application's UI without changing the firmware.
- XML files can be loaded dynamically as well, which allows for things like creating
UIs from plugins or apps that are downloaded by the firmware.
- 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 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.
- The XML syntax uses the same properties as the C API, so it's easy to learn. E.g.
style properties like bg_color, line_width, or widget properties like width,
height, label text, etc.
- A powerful data binding engine allows you to easily bind the widgets to global data.
Concept
*******
@@ -39,35 +50,35 @@ For example, a company can have a Component Library for the basic Widgets for al
(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.
These Component Libraries are independent, can be reused across many products, and can
be independently 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 simply fix it in one place and
push it back to the git repository so that other projects can be updated from it.
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
The built-in Widgets of LVGL are considered ``the core Component Library`` which is
always available.
A UI |nbsp| Editor project can have any number of Component Libraries but will always have
at least 2:
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 :dfn:`Widgets`, :dfn:`Components`, and :dfn:`Screens`.
Widgets
-------
:dfn:`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:
but rather compiled into the application as C code. The main characteristics of Widgets are:
- In XML, they start with a ``<widget>`` root element.
- They are similar to LVGL's built-in Widgets.
@@ -75,7 +86,7 @@ but rather compiled into the application. The main characteristics of Widgets ar
- 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).
- They can themselves contain Widgets as children (e.g. ``Tabview``'s tabs, ``Dropdown``'s lists).
Any handwritten Widget can be accessed from XML by:
@@ -83,42 +94,46 @@ Any handwritten Widget can be accessed from XML by:
2. Writing and registering an XML parser for it.
`See some examples here. <https://github.com/lvgl/lvgl/tree/master/src/others/xml/parsers>`__
Components
----------
:dfn:`Components` are built from other Components and Widgets, and **can be loaded at runtime**.
:dfn:`Components` are built from Widgets and/or other Components, 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 are built from Widgets and/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).
- They can contain (as children) Widgets and/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 |nbsp| Editor, the XML files
of Components can be registered in LVGL, and after that, instances can be created.
Regardless of whether the XML was written manually or by the UI |nbsp| editor, the XML files
defining 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
-------
:dfn:`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 :ref:`Screen <screens>`.
- They are built from Widgets and/or other Components to describe the :ref:`Screen <screens>`.
- 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.
Syntax Teaser
*************
Each Widget, Component, or Screen XML file describes a single UI element. The root
element for Widgets, Components, and Screens is ``<widget>``, ``<component>``, and
``<screen>``, respectively. Other than that, the contained XML elements are almost
``<screen>`` respectively. Other than that, the contained XML elements are almost
identical. This is a high-level overview of the most important XML elements that
will be children of these root elements:
@@ -161,10 +176,12 @@ Note that only the basic features are shown here.
</view>
</component>
Usage Teaser
************
LVGL's UI |nbsp| Editor can be used in two different ways.
LVGL's UI editor can be used in two different ways.
Export C and H Files
--------------------