diff --git a/docs/src/details/auxiliary-modules/xml/animations.rst b/docs/src/details/auxiliary-modules/xml/animations.rst index 949dc7c633..5b61b67a07 100644 --- a/docs/src/details/auxiliary-modules/xml/animations.rst +++ b/docs/src/details/auxiliary-modules/xml/animations.rst @@ -1,6 +1,7 @@ -.. _xml_animation: +.. _xml_animations: ========== Animations ========== +TODO diff --git a/docs/src/details/auxiliary-modules/xml/api.rst b/docs/src/details/auxiliary-modules/xml/api.rst index ec1846ad18..ada453420c 100644 --- a/docs/src/details/auxiliary-modules/xml/api.rst +++ b/docs/src/details/auxiliary-modules/xml/api.rst @@ -4,182 +4,194 @@ API === -The ```` tag can be used in ````s and ````, although each supports slightly different features. +The ```` tag can be a child of ```` and ```` tags, although +each supports slightly different features. + + Properties ********** Inside ```` elements, ```` 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 - - - - - - - + + + + + + + -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 - + -For **widgets**, each property corresponds to a setter function. +For **Widgets**, each property corresponds to a setter function. The ``name`` in ```` is used to build the name of the setter function like this: .. code-block:: c - _set_(lv_obj_t * obj, , , ...); + _set_(lv_obj_t * obj, , , ...); -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 - _create(lv_obj_t * parent, , , ...); + _create(lv_obj_t * parent, , , ...); ```` elements have an optional ```` 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. + + ```` ************* -Can be used only for widgets. - -Used to define new enum types for a given widget. - -It should contain ```` 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 ```` elements to define possible options. Example: .. code-block:: xml - - - - - - + + + + + + - - - - + + + + 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. + + ```` ************* -Also applies only to widgets. +```` 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 ```` and ```` definitions. ```` elements are +mandatory (default values are supported) as they are used to create the element, +whereas ```` elements are optional as they are mapped to setter functions. -Elements can have ```` and ```` definitions. ```` elements are mandatory (default values are supported) -as they are used to create the element, whereas ```` elements are optional as they are mapped to setter functions. - -An element in a ```` can be referenced like this: ````. -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 ```` can be referenced like this: ````. +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 - + -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 ```` 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");``. -```` elements defined directly inside the ```` are passed to the ``add`` function as arguments. +```` elements defined as direct children of the ```` are passed to the +``add`` function as arguments. Example: .. code-block:: xml - - - - - - - - - - - - -