276 lines
8.0 KiB
ReStructuredText
276 lines
8.0 KiB
ReStructuredText
.. _xml_api:
|
|
|
|
===
|
|
API
|
|
===
|
|
|
|
The ``<api>`` tag can be used in ``<widget>``s and ``<components>``, 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 **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.
|
|
|
|
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>
|
|
|
|
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"/>
|
|
|
|
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>, ...);
|
|
|
|
For **components**, the exported code contains only a single ``create`` function
|
|
to which all the properties need to be passed:
|
|
|
|
.. code-block:: c
|
|
|
|
<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.
|
|
|
|
``<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.
|
|
|
|
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>
|
|
|
|
<prop name="mode" help="Set the 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.
|
|
|
|
``<element>``
|
|
*************
|
|
|
|
Also applies 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 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.
|
|
|
|
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).
|
|
|
|
Example:
|
|
|
|
.. code-block:: xml
|
|
|
|
<my_chart-super_series color="0xff0000"/>
|
|
|
|
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).
|
|
|
|
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.
|
|
|
|
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>
|
|
|
|
|
|
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>
|
|
|
|
|
|
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);
|
|
|
|
|
|
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);
|
|
|
|
``access="get"``
|
|
----------------
|
|
|
|
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.
|
|
|
|
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>
|
|
|
|
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>
|
|
|
|
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);
|
|
|
|
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);
|
|
|
|
|
|
``access="set"``
|
|
----------------
|
|
|
|
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>
|
|
|
|
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>
|
|
|
|
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);
|
|
|
|
|
|
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);
|