diff --git a/Kconfig b/Kconfig index 903a2dce1..d274fcc97 100644 --- a/Kconfig +++ b/Kconfig @@ -1390,7 +1390,7 @@ menu "LVGL configuration" default n help You won't be able to open URLs after enabling this feature. - Note that FFmpeg image decoder will always use lvgl file system. + Note that FFmpeg image decoder will always use lvgl file system. endmenu menu "Others" @@ -1591,7 +1591,8 @@ menu "LVGL configuration" int "Font manager name max length" depends on LV_USE_FONT_MANAGER default 32 - + config LV_USE_XML + bool "Enable loading XML UIs runtime" config LVGL_VERSION_MAJOR int default 9 # LVGL_VERSION_MAJOR diff --git a/docs/details/other-components/index.rst b/docs/details/other-components/index.rst index 769703559..45789cd15 100644 --- a/docs/details/other-components/index.rst +++ b/docs/details/other-components/index.rst @@ -18,3 +18,4 @@ Other Components obj_property observer snapshot + xml diff --git a/docs/details/other-components/xml.rst b/docs/details/other-components/xml.rst new file mode 100644 index 000000000..1937beb74 --- /dev/null +++ b/docs/details/other-components/xml.rst @@ -0,0 +1,301 @@ +.. _xml: + +==================== +XML - Declarative UI +==================== + +Introduction +------------ + +LVGL is capable of loading UI elements written in XML. +Although still under development, the basics are already functional, serving as a preview. + +This declarative language serves as the backend for LVGL's UI editor (currently under development), +which enables faster and more maintainable UI implementation. + +Note that, the UI editor is not required to utilize LVGL's XML loading capabilities. + +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 scripts. +- XML can be used to generate LVGL code in any language. +- XML helps to separate the view from the logic. + +Currently supported features: + +- Load XML components at runtime from file or data +- Nest components and widgets any deep +- Dynamically create instances of XML components in C +- Register images and font that can be accessed by name later in the XMLs +- Constants are working for widget and style properties +- Parameters can be defined and passed and used for components +- Basic built in widgets (label, slider, bar, button, etc) +- Style sheets and local styles that can be assigned to parts and states support the basic style properties + +Limitations: + +- Only basic widgets are supported with limited functionality. +- Only a few style properties are supported. +- Events are not supported yet. +- Animations are not supported yet. +- Subjects are not supported yet. +- The documentation is not complete yet. + +Main Concept +~~~~~~~~~~~~ + +It's important to distinguish between widgets and components: + +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: + +- Similar to LVGL's built-in widgets. +- Built from classes. +- Have a large API with set/get/add/etc. functions. +- Support "internal widgets" (e.g., tabview's tabs, dropdown's list). +- Have custom and complex logic inside. +- Cannot be loaded from XML at runtime because custom code cannot be loaded. + +Components are built from other components and widgets and can be loaded at runtime. +The main characteristics of components are: + +- Built from widgets or other components. +- Can be used for styling widgets. +- Can contain widgets or other components. +- Cannot have custom C code. +- Can be loaded from XML at runtime as they describe only the visuals. + +Components +---------- + +Overview +~~~~~~~~ + +In light of the above, only components can be loaded from XML. +An example of a ``my_button`` component looks like this: + +.. code-block:: xml + + + + + + + + + + + + +