Mirrors_UI_SDK/lvgl
1
0
Fork 0
mirror of https://github.com/lvgl/lvgl.git synced 2026-05-23 15:56:59 +08:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

docs(XML): proofread XML docs (batch 2 of 2) (#8185)
Arduino Lint / lint (push) Has been cancelled
Details
MicroPython CI / Build esp32 port (push) Has been cancelled
Details
MicroPython CI / Build rp2 port (push) Has been cancelled
Details
MicroPython CI / Build stm32 port (push) Has been cancelled
Details
MicroPython CI / Build unix port (push) Has been cancelled
Details
C/C++ CI / Build OPTIONS_16BIT - Ubuntu (push) Has been cancelled
Details
C/C++ CI / Build OPTIONS_24BIT - Ubuntu (push) Has been cancelled
Details
C/C++ CI / Build OPTIONS_FULL_32BIT - Ubuntu (push) Has been cancelled
Details
C/C++ CI / Build OPTIONS_NORMAL_8BIT - Ubuntu (push) Has been cancelled
Details
C/C++ CI / Build OPTIONS_SDL - Ubuntu (push) Has been cancelled
Details
C/C++ CI / Build OPTIONS_VG_LITE - Ubuntu (push) Has been cancelled
Details
C/C++ CI / Build OPTIONS_16BIT - cl - Windows (push) Has been cancelled
Details
C/C++ CI / Build OPTIONS_16BIT - gcc - Windows (push) Has been cancelled
Details
C/C++ CI / Build OPTIONS_24BIT - cl - Windows (push) Has been cancelled
Details
C/C++ CI / Build OPTIONS_24BIT - gcc - Windows (push) Has been cancelled
Details
C/C++ CI / Build OPTIONS_FULL_32BIT - cl - Windows (push) Has been cancelled
Details
C/C++ CI / Build OPTIONS_FULL_32BIT - gcc - Windows (push) Has been cancelled
Details
C/C++ CI / Build OPTIONS_VG_LITE - cl - Windows (push) Has been cancelled
Details
C/C++ CI / Build OPTIONS_VG_LITE - gcc - Windows (push) Has been cancelled
Details
C/C++ CI / Build ESP IDF ESP32S3 (push) Has been cancelled
Details
C/C++ CI / Run tests with 32bit build (push) Has been cancelled
Details
C/C++ CI / Run tests with 64bit build (push) Has been cancelled
Details
BOM Check / bom-check (push) Has been cancelled
Details
Verify that lv_conf_internal.h matches repository state / verify-conf-internal (push) Has been cancelled
Details
Verify the widget property name / verify-property-name (push) Has been cancelled
Details
Verify code formatting / verify-formatting (push) Has been cancelled
Details
Build docs / build-and-deploy (push) Has been cancelled
Details
Test API JSON generator / Test API JSON (push) Has been cancelled
Details
Check Makefile / Build using Makefile (push) Has been cancelled
Details
Check Makefile for UEFI / Build using Makefile for UEFI (push) Has been cancelled
Details
Port repo release update / run-release-branch-updater (push) Has been cancelled
Details
Verify Font License / verify-font-license (push) Has been cancelled
Details
Verify Kconfig / verify-kconfig (push) Has been cancelled
Details
Close stale issues and PRs / stale (push) Has been cancelled
Details

Browse Source
This commit is contained in:
Victor Wheeler
2025-05-13 03:10:11 -06:00
committed by GitHub
parent 7c57667b7a
commit 73925458fc
8 changed files with 343 additions and 298 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/src/details/auxiliary-modules/xml/animations.rst
+2 -1
View File
@@ -1,6 +1,7 @@
.. _xml_animation:
.. _xml_animations:
==========
Animations
==========
TODO
docs/src/details/auxiliary-modules/xml/api.rst
+138 -128
View File
@@ -4,182 +4,194 @@
API
===
The ``<api>`` tag can be used in ``<widget>``s and ``<components>``, although each supports slightly different features.
The ``<api>`` tag can be a child of ``<widget>`` and ``<components>`` tags, although
each supports slightly different features.
Properties
**********
Inside ``<prop>`` elements, ``<param>`` elements can be defined to describe the arguments.
For **widgets**, all properties are optional.
If a property is not set on an instance of a widget, it simply won't be applied,
and the created widget's default value will be used (e.g., ``text`` for a label's text).
For **Widgets**, all properties are optional.
If a property is not set on an instance of a Widget, it simply won't be applied,
and the created Widget's default value for that property will be used (e.g., ``text``
for a label's text).
For **components**, all properties are mandatory; however, default values can be defined
For **Components**, all properties are mandatory; however, default values can be defined
to be used when a property is not set.
If a property has only one parameter (which is usually the case), a shorthand can be applied as shown below.
If a property has only one parameter (which is usually the case), a shorthand syntax
can be applied as shown below.
For example:
.. code-block:: xml
<api>
<prop name="range" default="0 100" help="Set the range.">
<param name="range_min" type="int" help="Sets the minimum value."/>
<param name="range_max" type="int" help="Sets the maximum value."/>
</prop>
<prop name="title" type="string" help="The title of the slider"/>
</api>
<api>
<prop name="range" default="0 100" help="Set the range.">
<param name="range_min" type="int" help="Sets the minimum value."/>
<param name="range_max" type="int" help="Sets the maximum value."/>
</prop>
<prop name="title" type="string" help="The title of the slider"/>
</api>
When a property is used, all parameters are set as a single attribute value. For example:
When a property is used, all parameters are set as a single attribute value. For example:
.. code-block:: xml
<my_slider range="-100 100" title="Room 1"/>
<my_slider range="-100 100" title="Room 1"/>
For **widgets**, each property corresponds to a setter function.
For **Widgets**, each property corresponds to a setter function.
The ``name`` in ``<prop>`` is used to build the name of the setter function like this:
.. code-block:: c
<widget_name>_set_<prop_name>(lv_obj_t * obj, <param1_type> <param1_name>, <param2_type> <param2_name>, ...);
<widget_name>_set_<prop_name>(lv_obj_t * obj, <param1_type> <param1_name>, <param2_type> <param2_name>, ...);
For **components**, the exported code contains only a single ``create`` function
to which all the properties need to be passed:
For **Components**, the exported code contains only a single ``create`` function
to which all the properties are passed:
.. code-block:: c
<component_name>_create(lv_obj_t * parent, <param1_type> <param1_name>, <param2_type> <param2_name>, ...);
<component_name>_create(lv_obj_t * parent, <param1_type> <param1_name>, <param2_type> <param2_name>, ...);
``<prop>`` elements have an optional ``<postponed>`` boolean attribute.
By default, it is ``false``, but if set to ``true``, the given property will be applied after all children are created.
A practical example is setting the current tab of a tab view, which cannot be set before the tabs are created.
This feature is not supported yet.
By default, it is ``false``, but if set to ``true``, the given property will be
applied after all children are created. A practical example is setting the current
tab of a tab view, which cannot be set before the tabs are created. This feature is
not supported yet.
``<enumdef>``
*************
Can be used only for widgets.
Used to define new enum types for a given widget.
It should contain ``<enum>`` elements to define the possible options.
This tag is used only with Widgets. It is used to define new enum types for a given
Widget. It should contain ``<enum>`` elements to define possible options.
Example:
.. code-block:: xml
<!-- my_widget.xml -->
<api>
<enumdef name="my_widget_mode" help="Possible modes">
<enum name="normal" help="Normal mode" value="0x10"/>
<enum name="inverted" help="Inverted mode"/>
</enumdef>
<!-- my_widget.xml -->
<api>
<enumdef name="my_widget_mode" help="Possible modes">
<enum name="normal" help="Normal mode" value="0x10"/>
<enum name="inverted" help="Inverted mode"/>
</enumdef>
<prop name="mode" help="Set the widget mode">
<param name="mode" type="enum:my_widget_mode"/>
</prop>
</api>
<prop name="mode" help="Set Widget mode">
<param name="mode" type="enum:my_widget_mode"/>
</prop>
</api>
Note that the enum values are not important because:
1. When the code is exported, the enum names will be used, and the compiler will substitute the values.
2. When loaded from XML, the widget's XML parser should convert the enum names to C enum fields.
1. When the code is exported, the enum names will be used, and the compiler generates
its own value for each enumerator symbol.
2. When loaded from XML, the Widget's XML parser should convert the enum names to C
enum fields.
``<element>``
*************
Also applies only to widgets.
``<element>`` tags also apply only to Widgets. Elements are used to describe
sub-Widgets or internal parts of Widgets. Examples include the list of a dropdown,
the tabs of a tab view, or the data series of a chart.
Elements are used to describe sub-widgets or internal parts of widgets.
Examples include the list of a dropdown, the tabs of a tab view, or the series of a chart.
Elements can have ``<arg>`` and ``<prop>`` definitions. ``<arg>`` elements are
mandatory (default values are supported) as they are used to create the element,
whereas ``<prop>`` elements are optional as they are mapped to setter functions.
Elements can have ``<arg>`` and ``<prop>`` definitions. ``<arg>`` elements are mandatory (default values are supported)
as they are used to create the element, whereas ``<prop>`` elements are optional as they are mapped to setter functions.
An element in a ``<view>`` can be referenced like this: ``<widget_name-element_name>``.
The widget name and the element name are separated by a ``-``, so ``-`` is not allowed in widget and
element names (only ``_`` can be used).
An element in a ``<view>`` can be referenced like this: ``<widget_name-element_name>``.
Note that the ``-`` separates two names inside that tag name: the Widget name and the
element name. ``-`` is not allowed in Widget and element names. Only ``_`` can be
used to separate words in tag names.
Example:
.. code-block:: xml
<my_chart-super_series color="0xff0000"/>
<my_chart-super_series color="0xff0000"/>
An important attribute of elements is ``access``. The possible values are:
An important attribute of elements is ``access``. The possible values are:
- ``add``: Create any number of elements dynamically (e.g., chart series).
- ``get``: Get a pointer to an implicitly created widget or any data (e.g., list of the dropdown).
- ``set``: Select specific parts of the widget with indexes (e.g., table cells).
- ``get``: Get a pointer to an implicitly created Widget or any data (e.g., list of a Drop-Down List).
- ``set``: Select specific parts of the Widget with indexes (e.g., table cells).
Elements with ``access="add"`` or ``access="get"`` can have a custom data type defined using ``type="my_data"``.
In these cases, no children can be added. If the ``type`` is ``lv_obj``, the element can have children.
Elements with ``access="add"`` or ``access="get"`` can have a custom data type
defined using ``type="my_data"``. In these cases, no children can be added. If the
``type`` is ``lv_obj``, the element can have children.
It is not yet possible to describe the ``<view>`` of elements in XML; only the API can be defined.
The actual implementation needs to be done in C.
``access="add"``
----------------
The element is explicitly created with an ``add`` function, e.g., ``lv_tabview_add_tab(obj, "Title");``.
``<arg>`` elements defined directly inside the ``<element>`` are passed to the ``add`` function as arguments.
``<arg>`` elements defined as direct children of the ``<element>`` are passed to the
``add`` function as arguments.
Example:
.. code-block:: xml
<!-- my_widget.xml -->
<api>
<element name="indicator" type="obj" help="The indicator of my_widget" access="add">
<arg name="color" type="color" help="Help for color"/>
<arg name="max_value" type="int" help="Help for max_value"/>
<prop name="value" help="Set a new value for the indicator">
<param name="value" type="int" help="Help for value"/>
</prop>
</element>
</api>
<view extends="obj">
<button name="btn1"/>
</view>
<!-- my_widget.xml -->
<api>
<element name="indicator" type="obj" help="The indicator of my_widget" access="add">
<arg name="color" type="color" help="Help for color"/>
<arg name="max_value" type="int" help="Help for max_value"/>
<prop name="value" help="Set a new value for the indicator">
<param name="value" type="int" help="Help for value"/>
</prop>
</element>
</api>
<view extends="obj">
<button name="btn1"/>
</view>
In a view it can be used like this:
.. code-block:: xml
<!-- complex_widget.xml -->
<view>
<lv_label text="Title"/>
<my_widget width="100px" y="40px">
<my_widget-indicator name="indic1" color="0xff0000" max_value="120" value="30"/>
</my_widget>
</view>
<!-- complex_widget.xml -->
<view>
<lv_label text="Title"/>
<my_widget width="100px" y="40px">
<my_widget-indicator name="indic1" color="0xff0000" max_value="120" value="30"/>
</my_widget>
</view>
From the API definition the following functions are generated:
.. code-block:: c
lv_obj_t * my_widget_add_indicator(lv_obj_t * parent, lv_color_t color, int32_t max_value);
void my_widget_set_indicator_value(lv_obj_t * obj, int32_t value);
lv_obj_t * my_widget_add_indicator(lv_obj_t * parent, lv_color_t color, int32_t max_value);
void my_widget_set_indicator_value(lv_obj_t * obj, int32_t value);
And this is the related C file where the indicator is created:
.. code-block:: c
lv_obj_t * indic1 = my_widget_add_indicator(parent, color, max_value);
lv_my_widget_set_indicator_value(indic1, value);
lv_obj_t * indic1 = my_widget_add_indicator(parent, color, max_value);
lv_my_widget_set_indicator_value(indic1, value);
``access="get"``
----------------
If the element is created internally and implicitly, it can be retrieved with a function like ``lv_dropdown_get_list(obj);``.
If the element is created internally and implicitly, it can be retrieved with a
function like ``lv_dropdown_get_list(obj);``.
``<arg>`` elements are passed to the ``get`` function as arguments.
@@ -187,89 +199,87 @@ Example:
.. code-block:: xml
<!-- my_widget.xml -->
<api>
<element name="control_button" type="obj" help="A control button of my_widget" access="get">
<arg name="index" type="int" help="Zero-based index of the control button"/>
<prop name="title">
<param name="text" type="string"/>
</prop>
</element>
</api>
<!-- my_widget.xml -->
<api>
<element name="control_button" type="obj" help="A control button of my_widget" access="get">
<arg name="index" type="int" help="Zero-based index of the control button"/>
<prop name="title">
<param name="text" type="string"/>
</prop>
</element>
</api>
In a view:
.. code-block:: xml
<!-- complex_widget.xml -->
<view>
<my_widget width="100px">
<my_widget-control_button name="btn1" index="3" title="Hello"/>
</my_widget>
</view>
<!-- complex_widget.xml -->
<view>
<my_widget width="100px">
<my_widget-control_button name="btn1" index="3" title="Hello"/>
</my_widget>
</view>
Generated API:
.. code-block:: c
lv_obj_t * my_widget_get_control_button(lv_obj_t * parent, int32_t index);
void my_widget_set_control_button_title(lv_obj_t * obj, const char * text);
lv_obj_t * my_widget_get_control_button(lv_obj_t * parent, int32_t index);
void my_widget_set_control_button_title(lv_obj_t * obj, const char * text);
And this is a C file where the control button is retrieved:
.. code-block:: c
lv_obj_t * btn1 = lvmy_widget_get_control_button(parent, index);
my_widget_set_control_button_title(btn1, text);
lv_obj_t * btn1 = lvmy_widget_get_control_button(parent, index);
my_widget_set_control_button_title(btn1, text);
``access="set"``
----------------
Used when elements are created automatically but need to be selected in API calls,
The "set" value is used when elements are created automatically but need to be selected in API calls,
e.g., ``lv_table_set_cell_value(table, row, col, "text");``.
Example:
.. code-block:: xml
<!-- my_widget.xml -->
<api>
<element name="item" type="obj" help="An item on my_widget" access="set">
<arg name="index" type="int" help="The zero-based index of the item"/>
<prop name="icon" help="Set the icon of an item">
<param name="icon_src" type="img_src" help="The image to set as an icon."/>
</prop>
<prop name="color" help="Set the color">
<param name="color" type="color" help="The color to set for the item."/>
</prop>
</element>
</api>
<!-- my_widget.xml -->
<api>
<element name="item" type="obj" help="An item on my_widget" access="set">
<arg name="index" type="int" help="The zero-based index of the item"/>
<prop name="icon" help="Set the icon of an item">
<param name="icon_src" type="img_src" help="The image to set as an icon."/>
</prop>
<prop name="color" help="Set the color">
<param name="color" type="color" help="The color to set for the item."/>
</prop>
</element>
</api>
In a view:
.. code-block:: xml
<!-- complex_widget.xml -->
<view>
<my_widget width="100px">
<my_widget-item index="3" icon_src="image1" color="0xff0000"/>
</my_widget>
</view>
<!-- complex_widget.xml -->
<view>
<my_widget width="100px">
<my_widget-item index="3" icon_src="image1" color="0xff0000"/>
</my_widget>
</view>
This is the generated header file:
.. code-block:: c
void my_widget_set_item_icon(lv_obj_t * parent, int32_t index, const void * icon_src);
void my_widget_set_item_color(lv_obj_t * parent, int32_t index, lv_color_t color);
void my_widget_set_item_icon(lv_obj_t * parent, int32_t index, const void * icon_src);
void my_widget_set_item_color(lv_obj_t * parent, int32_t index, lv_color_t color);
And this is the related C file where the item properties are set:
.. code-block:: c
my_widget_set_item_icon(parent, index, image1);
my_widget_set_item_color(parent, index, color);
my_widget_set_item_icon(parent, index, image1);
my_widget_set_item_color(parent, index, color);
docs/src/details/auxiliary-modules/xml/consts.rst
+26 -22
View File
@@ -17,28 +17,32 @@ The supported types are:
- ``opa``
- ``bool``
Usage
*****
.. code-block:: xml
<consts>
<color name="color1" value="0xff0000" help="Primary color"/>
<px name="pad_xs" value="8" help="Small padding"/>
</consts>
<consts>
<color name="color1" value="0xff0000" help="Primary color"/>
<px name="pad_xs" value="8" help="Small padding"/>
</consts>
Constants can be used in:
- Style properties
- Widget and component properties
- Widget and Component properties
And they can be used like this:
.. code-block:: xml
<styles>
<style name="style1" bg_color="#color1"/>
</styles>
<styles>
<style name="style1" bg_color="#color1"/>
</styles>
Variants
********
@@ -47,23 +51,23 @@ Constants support a ``<variant>`` attribute to change the constants at compile t
.. code-block:: xml
<consts>
<px name="pad" value="8" help="General padding">
<variant name="size" case="small" value="4"/>
<variant name="size" case="large" value="12"/>
</px>
</consts>
<consts>
<px name="pad" value="8" help="General padding">
<variant name="size" case="small" value="4"/>
<variant name="size" case="large" value="12"/>
</px>
</consts>
From which the following C code can be exported:
from which the following C code can be exported:
.. code-block:: c
#if SIZE == SMALL
#define PAD 4
#elif SIZE == LARGE
#define PAD 12
#else
#define PAD 8
#endif
#if SIZE == SMALL
#define PAD 4
#elif SIZE == LARGE
#define PAD 12
#else
#define PAD 8
#endif
Where ``SMALL`` and ``LARGE`` are just preprocessor defines with incremental values.
docs/src/details/auxiliary-modules/xml/events.rst
+16 -10
View File
@@ -11,9 +11,12 @@ Overview
Right now, only a single event type is supported to call user-defined callbacks.
Usage
*****
Call function
-------------
@@ -22,20 +25,21 @@ User-defined functions can be called like this:
.. code-block:: xml
<view>
<lv_button width="200" height="100">
<lv_event-call_function callback="my_callback_1" trigger="clicked" user_data="some_text"/>
<lv_label text="Hello"/>
</lv_button>
<lv_button width="200" height="100">
<lv_event-call_function callback="my_callback_1" trigger="clicked" user_data="some_text"/>
<lv_label text="Hello"/>
</lv_button>
</view>
When the XML is loaded at runtime, the callback name needs to be mapped to a function by using:
``lv_xml_register_event_cb("my_callback_1", an_event_handler)``
:cpp:expr:`lv_xml_register_event_cb("my_callback_1", an_event_handler)`.
The callback should have the standard LVGL event callback signature:
``void an_event_handler(lv_event_t * e);``
In the exported C code, it is assumed that there is a function with the exact name specified as the callback name.
For example, ``callback="my_callback_1"`` will be exported as:
In the exported C code, it is assumed that there is a function with the exact name
specified as the callback name. For example, ``callback="my_callback_1"`` will be
exported as:
.. code-block:: c
@@ -45,9 +49,11 @@ For example, ``callback="my_callback_1"`` will be exported as:
For triggers, all LVGL event types are supported with straightforward mapping:
- :cpp:expr:`LV_EVENT_ALL`: ``"all"``
- :cpp:expr:`LV_EVENT_CLICKED`: ``"clicked"``
- :cpp:expr:`LV_EVENT_PRESSED`: ``"pressed"``
.. What is a trigger?
- :cpp:enumerator:`LV_EVENT_ALL`: ``"all"``
- :cpp:enumerator:`LV_EVENT_CLICKED`: ``"clicked"``
- :cpp:enumerator:`LV_EVENT_PRESSED`: ``"pressed"``
- etc.
The ``user_data`` is optional. If omitted, ``NULL`` will be passed.
docs/src/details/auxiliary-modules/xml/fonts.rst
+35 -25
View File
@@ -8,7 +8,10 @@ Overview
********
A ``<fonts>`` section can be added in ``globals.xml`` files.
Later, it might be supported in components and widgets to define local fonts and keep the global space cleaner.
Later, it might be supported in Components and Widgets to define local fonts and keep
the global space cleaner.
Usage
*****
@@ -17,13 +20,13 @@ The following section creates a mapping between font names and their paths with
.. code-block:: xml
<fonts>
<bin as_file="false" name="medium" src="path/to/file.ttf" range="0x20-0x7f" symbols="°" size="24"/>
<tiny_ttf as_file="true" name="big" src_path="path/to/file.ttf" range="0x20-0x7f" symbols="auto" size="48"/>
<freetype name="chinese" src_path="file.ttf" size="48" custom_freetype_attribute="abc"/>
</fonts>
<fonts>
<bin as_file="false" name="medium" src="path/to/file.ttf" range="0x20-0x7f" symbols="°" size="24"/>
<tiny_ttf as_file="true" name="big" src_path="path/to/file.ttf" range="0x20-0x7f" symbols="auto" size="48"/>
<freetype name="chinese" src_path="file.ttf" size="48" custom_freetype_attribute="abc"/>
</fonts>
In ``<styles>`` and ``<view>``, fonts can be referenced by their name, e.g.,
In ``<styles>`` and ``<view>``, fonts can then be referenced by their name, e.g.,
.. code-block:: xml
@@ -35,23 +38,24 @@ The tag name determines how the font is loaded. Currently, only ``tiny_ttf as_fi
- If ``as_file="true"``: Converts the font file to ``bin`` (see `lv_font_conv`)
which will be loaded by ``lv_binfont_create()``.
- If ``as_file="false"`` (default): On export, the font file will be converted to a C array LVGL font
that can be used directly by LVGL.
- If ``as_file="false"`` (default): On export, the font file will be converted to a
C array LVGL font that can be used directly by LVGL.
- ``tiny_ttf``:
- If ``as_file="true"``: Can be loaded directly by ``lv_tiny_ttf_create_file()``.
- If ``as_file="false"`` (default): The font file will be converted to a raw C array on export
that will be loaded by ``lv_tiny_ttf_create_data()``.
- If ``as_file="false"`` (default): The font file will be converted to a raw C
array on export that will be loaded by ``lv_tiny_ttf_create_data()``.
- ``freetype``: The file can be loaded directly by ``lv_freetype_font_create()``.
For simplicity, if ``as_file="false"``, fonts will be loaded as files in the preview.
Setting ``as_file="false"`` affects only the C export.
If the UI is created from XML at runtime and a ``globals.xml`` is parsed, the ``as_file="false"`` tags are skipped
because it is assumed that the user manually creates the mapping. This is because the XML parser cannot
automatically map an LVGL font definition like:
If the UI is created from XML at runtime and a ``globals.xml`` is parsed, the
``as_file="false"`` tags are skipped because it is assumed that the user manually
creates the mapping. This is because the XML parser cannot automatically map an LVGL
font definition like:
.. code-block:: c
@@ -63,19 +67,23 @@ to
<bin name="my_font_24"/>
Exported Code
-------------
When C code is exported, global ``const lv_font_t * <font_name>`` variables are created, and in the
initialization function of the component library (e.g., ``my_lib_init_gen()``), the actual font is assigned.
When C code is exported, global ``const lv_font_t * <font_name>`` variables are
created, and in the initialization function of the Component Library (e.g.,
``my_lib_init_gen()``), the actual font is assigned.
.. Note: :cpp:expr: role cannot be used here because it doesn't know how to parse
the ampersand and angle brackets. An alternate approach could be to make the
arguments "style1_p, font_name", but leaving the ampersand there seems more
appropriate due to that IS the normal way to pass a style as an argument.
So it was made into a literal string instead to avoid the parsing error.
In ``lv_style_set_text_font(&style1, <font_name>)``, the created font is referenced.
Constants
---------
@@ -83,17 +91,19 @@ Constants can also be used with fonts.
.. code-block:: xml
<consts>
<int name="font_size" value="32">
<variant name="size" case="small" value="24"/>
</int>
</consts>
<consts>
<int name="font_size" value="32">
<variant name="size" case="small" value="24"/>
</int>
</consts>
<fonts>
<bin name="medium" src_path="file.ttf" range="0x20-0x7f" symbols="°" size="#font_size"/>
</fonts>
<fonts>
<bin name="medium" src_path="file.ttf" range="0x20-0x7f" symbols="°" size="#font_size"/>
</fonts>
Default Font
------------
``"lv_font_default"`` can be used to access ``LV_FONT_DEFAULT``. Other built-in fonts are not exposed by default.
``"lv_font_default"`` can be used to access ``LV_FONT_DEFAULT``. Other built-in fonts
are not exposed by default.
docs/src/details/auxiliary-modules/xml/images.rst
+39 -29
View File
@@ -7,45 +7,51 @@ Images
Overview
********
An ``<images>`` section can be added to ``globals.xml`` files.
.. |nbsp| unicode:: U+000A0 .. NO-BREAK SPACE
:trim:
Later, it might also be supported in components and widgets to define local images and keep the global space cleaner.
An ``<images>`` section can be added to ``globals.xml`` files. If present, it
describes how to map images with names.
(Later, it might also be possible in Components and Widgets to define local images to
keep the global space cleaner.)
Currently ``<file>`` is the only supported child element, and ``<convert>`` is not
yet implemented.
This ``<images>`` section describes how to map images with names.
Only ``<file>`` is currently supported, and ``<convert>`` is not yet implemented.
Usage
*****
.. code-block:: xml
<images>
<file name="avatar" src_path="avatar1.png">
<convert path="raw/avatar.svg" width="100px" color_format="L8"/>
</file>
<images>
<file name="avatar" src_path="avatar1.png">
<convert path="raw/avatar.svg" width="100px" color_format="L8"/>
</file>
<data name="logo" src_path="logo1.png" color-format="rgb565" memory="RAM2">
<convert path="https://foo.com/image.png" width="50%" height="80%"
color_format="RGB565"/>
</data>
</images>
<data name="logo" src_path="logo1.png" color-format="rgb565" memory="RAM2">
<convert path="https://foo.com/image.png" width="50%" height="80%"
color_format="RGB565"/>
</data>
</images>
- ``<file>`` means that the image source is used as a file path:
- ``<data>`` means that the image is converted to a C array on export.
In both cases in the exported C code global ``const void * <image_name>`` variables are created and in the
initialization function of the component library (e.g. ``my_lib_init_gen()``) either the path or
the pointer to the converted :cpp:expr:`lv_image_dsc_t` pointers are assigned to that variable.
initialization function of the Component Library (e.g. ``my_lib_init_gen()``) either the path or
the pointer to the converted :cpp:type:`lv_image_dsc_t` pointers are assigned to that variable.
In :cpp:expr:`lv_image_set_src(image, image_name)` is used
instead of the path or :cpp:expr:`lv_image_dsc_t` pointer directly.
In :cpp:expr:`lv_image_set_src(image, image_name)` ``image_name`` is used
instead of the path or :cpp:type:`lv_image_dsc_t` pointer.
For simplicity, in the UI Editor preview, images are always loaded as files.
For simplicity, in the UI |nbsp| Editor preview, images are always loaded as files.
If the UI is created from XML at runtime and a ``globals.xml`` is parsed, the ``<data>`` tags are skipped
because it is assumed that the user manually creates the mapping. This is because the XML parser cannot
because it is assumed that the user manually created the mapping. This is because the XML parser cannot
automatically map an image like:
.. code-block:: c
@@ -58,6 +64,7 @@ to
<data name="my_logo"/>
Constants
---------
@@ -65,14 +72,17 @@ Constants can be used with images as well.
.. code-block:: xml
<consts>
<int name="icon_size" value="32">
<variant name="size" case="small" value="16"/>
</int>
</consts>
<consts>
<int name="icon_size" value="32">
<variant name="size" case="small" value="16"/>
</int>
</consts>
<images>
<data name="icon_apply" src_path="apply.png">
<convert path="raw/apply.png" width="#icon_size"/>
</data>
</images>
<images>
<data name="icon_apply" src_path="apply.png">
<convert path="raw/apply.png" width="#icon_size"/>
</data>
</images>
docs/src/details/auxiliary-modules/xml/styles.rst
+49 -58
View File
@@ -11,6 +11,8 @@ In XML files, both style sheets (:cpp:expr:`lv_style_t`) and local styles can be
Style variants are also supported to change style properties at runtime.
Style Sheets
************
@@ -18,119 +20,108 @@ In the ``<styles>`` section, styles and their properties can be defined like thi
.. code-block:: xml
<style name="red"
help="What is this style about?"
border_width="2px"
border_color="0xff0000"/>
<style name="red"
help="What is this style about?"
border_width="2px"
border_color="0xff0000"/>
Styles can be referenced like this in the ``<view>``:
.. code-block:: xml
<view>
<slider styles="main red:indicator red:knob:focused"/>
</view>
<view>
<slider styles="main red:indicator red:knob:focused"/>
</view>
As shown in the example, parts and states are appended after a ``:`` to the style's name.
Local Styles
************
Local styles can be used directly in a widget, for example:
Local styles can be used directly in a Widget, for example:
.. code-block:: xml
<lv_label style_bg_opa="200" style_bg_opa:disabled="100"/>
<lv_label style_bg_opa="200" style_bg_opa:disabled="100"/>
Style Variants
**************
The ``<style>`` tags can have ``<variant>`` child tags:
.. code-block:: xml
<styles>
<style name="big_button" bg_color="0xf00" border_width="1px" pad_left="10px">
<variant name="color" case="red" bg_color="0xf00"/>
<variant name="color" case="green" bg_color="0x0f0"/>
<variant name="color" case="blue" bg_color="0x00f"/>
</style>
</styles>
``<variant>`` elements allow altering styles at runtime.
The ``variant_<name>`` subjects of the component library are used for each setting, and an observer callback is generated with all the style properties valid for that variant. The observer callback first resets the style and then sets all the properties.
This feature is not supported yet.
Gradients
*********
Before the ``<styles>`` tag, the ``<gradients>`` tag can be used to describe various gradients, which can later be referenced in styles.
Before the ``<styles>`` tag, the ``<gradients>`` tag can be used to describe various
gradients, which can later be referenced in styles.
When a gradient is created, it can be referenced by its name, like:
.. code-block:: xml
<style bg_grad="grad1"/>
<style bg_grad="grad1"/>
or
.. code-block:: xml
<lv_button style_bg_grad="grad1"/>
<lv_button style_bg_grad="grad1"/>
Horizontal or Vertical Gradient
-------------------------------
Define simple ``<horizontal>`` or ``<vertical>`` gradients:
To define a simple ``<horizontal>`` or ``<vertical>`` gradients:
.. code-block:: xml
<gradients>
<horizontal name="grad1">
<stop color="#ff0000" offset="20%" opa="40%"/>
<stop color="#00ff00" offset="128" opa="100%"/>
</horizontal>
</gradients>
<gradients>
<horizontal name="grad1">
<stop color="#ff0000" offset="20%" opa="40%"/>
<stop color="#00ff00" offset="128" opa="100%"/>
</horizontal>
</gradients>
Linear Gradient
---------------
Define a skewed gradient from two points:
To define a skewed gradient from two points:
.. code-block:: xml
<gradients>
<linear name="grad1" start="50 50" end="100 80">
<stop color="#ff0000" offset="20%" opa="100%"/>
<stop color="#00ff00" offset="240" opa="100%"/>
</linear>
</gradients>
<gradients>
<linear name="grad1" start="50 50" end="100 80">
<stop color="#ff0000" offset="20%" opa="100%"/>
<stop color="#00ff00" offset="240" opa="100%"/>
</linear>
</gradients>
Radial Gradient
---------------
Define a radial gradient:
To define a radial gradient:
.. code-block:: xml
<gradients>
<radial name="grad1" center="100 50%" edge="200 50" focal_center="50 80%" focal_edge="55 80%">
<stop color="#ff0000" opa="100%"/>
<stop color="#00ff00" opa="100%"/>
</radial>
</gradients>
<gradients>
<radial name="grad1" center="100 50%" edge="200 50" focal_center="50 80%" focal_edge="55 80%">
<stop color="#ff0000" opa="100%"/>
<stop color="#00ff00" opa="100%"/>
</radial>
</gradients>
Conical Gradient
----------------
Define a conical gradient:
To define a conical gradient:
.. code-block:: xml
<gradients>
<conical name="grad1" center="80 50%" angle="45 270">
<stop color="#ff0000" opa="100%"/>
<stop color="#00ff00" opa="100%"/>
</conical>
</gradients>
<gradients>
<conical name="grad1" center="80 50%" angle="45 270">
<stop color="#ff0000" opa="100%"/>
<stop color="#00ff00" opa="100%"/>
</conical>
</gradients>
docs/src/details/auxiliary-modules/xml/subjects.rst
+38 -25
View File
@@ -4,37 +4,50 @@
Subjects
========
To connect values of the widget internally or to external data, subjects can be used. For example, an internally connected value could be a slider's value mapped to a label. Externally connected data could be the current number of users shown on a label.
To connect values of the Widget internally or to external data, :ref:`Subjects
<observer_subject>` can be used. For example, an internally connected value could be
a slider's value mapped to a label. Externally connected data could be the current
number of users shown on a label.
To handle internal connections, local subjects can be created like this:
To handle internal connections, local Subjects can be created like this:
<subjects>
<int name="a" value="20"/>
<string name="b" value="Hello"/>
<group name="a_and_b" value="a b"/>
</subjects>
.. code-block:: xml
These subjects can be used in widget APIs like:
<subjects>
<int name="a" value="20"/>
<string name="b" value="Hello"/>
<group name="a_and_b" value="a b"/>
</subjects>
<view>
<label bind_text="a 'Progress: %d'"/>
</view>
When generating code, the subjects are saved in the widget's data and are used like this:
These Subjects can be used in Widget APIs like:
lv_subject_init_int(&my_widget->subject_a, 20);
lv_subject_init_string(&my_widget->subject_b, "Hello");
.. code-block:: xml
<view>
<label bind_text="a 'Progress: %d'"/>
</view>
When generating code, the Subjects are saved in the Widget's data and are used like this:
.. code-block:: c
lv_subject_init_int(&my_widget->subject_a, 20);
lv_subject_init_string(&my_widget->subject_b, "Hello");
my_widget->subject_a_and_b_list = lv_malloc(sizeof(lv_subject_t *) * 2);
my_widget->subject_a_and_b_list[0] = &my_widget->subject_a;
my_widget->subject_a_and_b_list[1] = &my_widget->subject_b;
lv_subject_init_group(&my_widget->subject_a_and_b, my_widget->subject_a_and_b_list);
my_widget->subject_a_and_b_list = lv_malloc(sizeof(lv_subject_t *) * 2);
my_widget->subject_a_and_b_list[0] = &my_widget->subject_a;
my_widget->subject_a_and_b_list[1] = &my_widget->subject_b;
lv_subject_init_group(&my_widget->subject_a_and_b, my_widget->subject_a_and_b_list);
If the connection is more complex and not supported out of the box, it can be handled from code.
External subjects are defined in the API of the widget:
External Subjects are defined in the API of the Widget:
<api>
<prop name="bind_value" help="">
<param name="subject" type="subject" help=""/>
<param name="max_value" type="int" help="Just another parameter, e.g., to limit the value"/>
</prop>
</api>
.. code-block:: xml
<api>
<prop name="bind_value" help="">
<param name="subject" type="subject" help=""/>
<param name="max_value" type="int" help="Just another parameter, e.g., to limit the value"/>
</prop>
</api>