docs(xml): next set of XML-doc refinements (#8740)

Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>

docs/src/details/xml/build_ui/index.rst

@@ -1,8 +1,8 @@
-.. _xml_build_ui:
+.. _xml_building_uis:
 
-=========
+============
-Build UIs
+Building UIs
-=========
+============
 
 .. toctree::
     :class:    toctree-1-deep

docs/src/details/xml/build_ui/main_tags/api.rst

@@ -13,6 +13,8 @@ The only common point is that both Widgets and Components support having
 However, as Widgets and Components work very differently (Widgets have C code,
 but Components are pure XML), even properties are interpreted differently.
 
+
+
 Components
 **********
 
@@ -41,6 +43,7 @@ These properties are set once (at creation time), and there are no specific
 ``set`` functions to modify the property later. LVGL's general API can still be
 used to modify any widget in the component, but no dedicated API functions are generated.
 
+
 Referencing properties
 ----------------------
 
@@ -50,6 +53,7 @@ it can be used in a label as ``<lv_label text="$button_label"/>``.
 
 In the generated code, these are passed as arguments in create/set functions.
 
+
 Default values
 --------------
 
@@ -59,12 +63,14 @@ This can be ensured by:
 - Simply setting them in the XML instance
 - Providing a default value in the ``<api>``, e.g., ``<prop name="foo" type="string" default="bar"/>``
 
+
 Limitations
 -----------
 
 Note that none of the Widget API features such as ``<param>``, ``<enumdef>``, or ``<element>``
 can be used for Components. Only simple properties that are forwarded are supported.
 
+
 Example
 -------
 
@@ -92,9 +98,12 @@ Example
         </view>
     </component>
 
+
+
 Widgets
 *******
 
+
 Properties
 ----------
 
@@ -106,6 +115,7 @@ Properties are the core part of describing a Widget's API.
         <prop name="text" type="string" help="Text of the label."/>
     </api>
 
+
 Parameters
 ----------
 
@@ -137,6 +147,7 @@ Unset parameters fall back to:
 - Their default value (if defined)
 - Type-specific defaults (e.g., 0, false, NULL)
 
+
 Mapping
 -------
 
@@ -148,6 +159,7 @@ If ``<param>``s are used, they are passed to the same ``set`` function.
 If a property is not set on a Widget instance, it is skipped and the Widget's
 built-in default is used.
 
+
 <enumdef>
 ---------
 
@@ -168,6 +180,7 @@ Only used with Widgets, this tag defines enums for parameter values.
 Enum values are ignored in export; the names are used and resolved by the compiler.
 XML parsers must handle mapping enum names to C enums.
 
+
 .. _xml_widget_element:
 
 <element>

docs/src/details/xml/build_ui/main_tags/index.rst

@@ -1,11 +1,10 @@
 .. _xml_main_tags:
 
-=========
+=============
-Main tags
+Main XML Tags
-=========
+=============
 
 .. toctree::
-    :class:    toctree-1-deep
     :maxdepth: 2
 
     api

docs/src/details/xml/build_ui/main_tags/view.rst

@@ -7,12 +7,12 @@ View
 Overview
 ********
 
-The ``<view>`` tag can be used in:
+The ``<view>`` tag can be used as a child of the following tags:
 
-- ``<component>``\ s
+- ``<component>``
-- ``<widget>``\ s
+- ``<widget>``
-- ``<screen>``\ s
+- ``<screen>``
-- ``<test>``\ s
+- ``<test>``
 
 to describe how these items look. Inside ``<view>``, children can be added in a nested way
 using already defined ``widget``\ s and ``component``\ s. For example:
@@ -26,6 +26,8 @@ using already defined ``widget``\ s and ``component``\ s. For example:
         </lv_button>
     </view>
 
+
+
 Extends
 *******
 

docs/src/details/xml/build_ui/root_elements/components.rst

@@ -9,7 +9,7 @@ Overview
 
 Components are one of the main building blocks for creating new UI elements.
 
-``<component>``\ s support the following child XML tags:
+``<component>`` elements may contain the following child elements:
 
 - :ref:`<consts> <xml_consts>`
 - :ref:`<api> <xml_api>`
@@ -19,33 +19,38 @@ Components are one of the main building blocks for creating new UI elements.
 
 Although they can't contain C code, they are very powerful:
 
-- They can extend another Component or Widget (the base can be defined)
+- They can extend another Component or Widget (an "inherited" base Component or
-- Components can be built from Widgets and other Components
+  Widget can be specified).
-- A custom API can be defined
+- Components can be built from Widgets and/or other Components.
-- Local styles can be defined, and the global styles can be used
+- A custom API can be defined.
-- Local constants can be defined, and the global constants can be used
+- Local styles can be defined, and global styles can be referenced.
-- Function calls, subject changes, or screen load/create events can be added. See :ref:`XML Events <xml_events>`
+- Local constants can be defined, and global constants can be referenced.
-- Previews can be defined to preview the components in various settings
+- Events can be added as function calls, or responses to changes of Subject values,
+  or responses to Screens being created or loaded.  See :ref:`XML Events <xml_events>`.
+- Previews can be defined to preview the components in various settings.
 
 Unlike Widgets (which are always compiled into the application), Components can either:
 
 1. be loaded at runtime from XML, or
 2. be exported to C code and compiled with the application.
 
-Usage from XML
+
-**************
+
+Using Components from XML
+*************************
+
 
 In XML Files
 ------------
 
-Using Components in XMLs is very intuitive. The name of the components can be used as XML tag
+Using Components in XMLs is very intuitive. The name of the components can be used as
-in the ``<view>`` of other Components, Screens, and Widgets.
+the name of the XML tag in the ``<view>`` of other Components, Screens, and Widgets.
 
 The Component properties are just XML attributes.
 
 To load Components from file, it's assumed that the XML files are saved to the device
-either as data (byte array) or as file. Once the data is saved, each component
+either as data (byte array) or as a file. Once the data is saved, each component
-can be registered, and instances can be created after that.
+can be registered, after which instances of that Component can be created.
 
 .. code-block:: xml
 
@@ -57,8 +62,9 @@ can be registered, and instances can be created after that.
         </view>
     </component>
 
-:ref:`Styles <xml_styles>`, :ref:`Constants <xml_consts>`, and :ref:`custom API <component_custom_api>`
+:ref:`Styles <xml_styles>`, :ref:`Constants <xml_consts>`, and a
-can also be described in the XML files.
+:ref:`custom API <component_custom_properties>` can also be described in the XML files.
+
 
 Registration
 ------------
@@ -68,15 +74,18 @@ Once a Component is created (e.g., ``my_button``), it can be registered by calli
 - :cpp:expr:`lv_xml_component_register_from_file("A:lvgl/examples/others/xml/my_button.xml")`
 - :cpp:expr:`lv_xml_component_register_from_data("my_button", xml_data_of_my_button)`
 
-These registration functions process the XML data and store relevant information internally.
+These registration functions process the XML data and store relevant information
-This is required to make LVGL recognize the Component by name.
+internally by name.  When loaded from a file, the file name is used as the Component
+name.
 
-Note that the "A:" in the above path is a file system "driver identifier letter" from
+During registration, the ``<view>`` of the Component is saved in RAM as a template for
-:ref:`file_system` and used accordingly. See that documentation for details.
+creating instances of that Component.
 
-When loaded from a file, the file name is used as the Component name.
+.. note::
+
+    Note that the "A:" in the above path is a file system "driver identifier letter" from
+    :ref:`file_system` and used accordingly. See that documentation for details.
 
-During registration, the ``<view>`` of the Component is saved in RAM.
 
 Instantiation
 -------------
@@ -87,7 +96,7 @@ After registration, a new instance of any registered Component can be created wi
 
     lv_obj_t * obj = lv_xml_create(lv_screen_active(), "my_button", NULL);
 
-The created Widget is a normal LVGL Widget that can be used like any other manually-created Widget.
+The created Widget is a normal LVGL Widget that can be used like any other Widget.
 
 The last parameter can be ``NULL`` or an attribute list, like this:
 
@@ -103,8 +112,10 @@ The last parameter can be ``NULL`` or an attribute list, like this:
 
     lv_obj_t * btn1 = lv_xml_create(lv_screen_active(), "my_button", my_button_attrs);
 
-Usage from Exported Code
+
-************************
+
+Using Components from Exported C Code
+*************************************
 
 From each Component XML file, a C and H file is exported with a single function inside:
 
@@ -125,28 +136,31 @@ If the user needs to access or modify values dynamically, it is recommended to u
 The user can also call these ``..._create()`` functions at any time from application code
 to create new components on demand.
 
+
+
 Extending
 *********
 
-Additionally, when a Component is created, it can use the extended Widget's attributes
+When a Component is defined as "extending" a Widget, it effectively inherits that
-(see ``<view extends="...">`` in the code examples below).
+Widget's attributes, and they can be used with that Component.
+(See ``<view extends="...">`` in the code examples below.)
 
-This means that Components inherit the API of the extended Widget as well.
 
-.. _component_custom_api:
+
+.. _component_custom_properties:
 
 Custom Properties
 *****************
 
-The properties of child elements can be adjusted, such as:
+The properties of child elements can be set directly, such as:
 
 .. code-block:: xml
 
     <my_button x="10" width="200"/>
 
-However, it's also possible to define custom properties in the ``<api>`` tag.
+It is also possible to define custom properties in the ``<api>`` tag.
-The properties then can be passed to any properties of the children by
+Those properties then can thereafter be referenced in any properties of the children
-referencing them by ``$``. For example:
+by using a ``$`` prefix with its name.  Example:
 
 .. code-block:: xml
 
@@ -161,7 +175,7 @@ referencing them by ``$``. For example:
         </view>
     </component>
 
-And it can be used like
+And it can be used by other Components like this:
 
 .. code-block:: xml
 
@@ -175,19 +189,21 @@ And it can be used like
     </component>
 
 In this setup, the ``btn_text`` property is mandatory, however it can be made optional
-by setting a default value:
+by providing a default value like this:
 
 .. code-block:: xml
 
     <prop name="btn_text" type="string" default="Title"/>
 
-See :ref:`<api> <xml_api>` for more details and :ref:`XML Syntax <xml_syntax>` for all the supported types.
+See :ref:`<api> <xml_api>` for more details, and :ref:`XML Syntax <xml_syntax>` for all the supported types.
+
+
 
 Examples
 ********
 
 The following example demonstrates parameter passing and the use of the
-``text`` label property on a Component. Styles and Constants are also shown.
+``text`` label property in a Component. Styles and Constants are also shown.
 
 .. code-block:: xml
 
@@ -225,20 +241,28 @@ The following example demonstrates parameter passing and the use of the
     lv_xml_component_register_from_file("A:path/to/h3.xml");
     lv_xml_component_register_from_file("A:path/to/red_button.xml");
 
-    /* Creates a button with "None" text */
+    /* Create a button with "None" text. */
     lv_xml_create(lv_screen_active(), "red_button", NULL);
 
-    /* Use attributes to set the button text */
+    /* Use attributes to set the button text. */
     const char * attrs[] = {
         "btn_text", "Click here",
         NULL, NULL,
     };
     lv_xml_create(lv_screen_active(), "red_button", attrs);
 
+
+
 Live Example
 *************
 
 .. include:: ../../../../../../examples/others/xml/index.rst
 
+
+
 API
 ***
+
+.. API startswith:  lv_xml_component_
+
+.. API equals:  lv_xml_create

docs/src/details/xml/build_ui/root_elements/screens.rst

@@ -15,31 +15,34 @@ Screens work very similarly to Components. Both can be:
 - Loaded from XML
 - Contain Widgets and Components as children
 
-Screens are wrapped in the ``<screen>`` XML root element and used to organize
+Screens have ``<screen>`` as their root element and are used to organize
 the content of the UI.
 
-Screens can have only the following child XML tags:
+``<screen>`` elements may contain only the following child elements:
 
 - :ref:`<consts> <xml_consts>`
 - :ref:`<styles> <xml_styles>`, and
 - :ref:`<view> <xml_view>`
 
-That is, Screens **cannot** have an :ref:`<api> <xml_api>` or :ref:`<preview> <xml_preview>`.
+That is, Screens **cannot** have :ref:`<api> <xml_api>` or :ref:`<preview> <xml_preview>`
+elements.
+
+
 
 Usage
 *****
 
-Each XML file describes a :ref:`Screen <screens>`. The name of the XML file will
+Each Screen XML file defines a :ref:`Screen <screens>`. The name of the XML file will
-also be the name of the Screen.
+be the name of the Screen.
 
-This example illustrates a screen in XML. In the example, a ``<my_header>``
+This example illustrates a Screen in XML. In the example, a ``<my_header>``
 and a ``<my_main_cont>`` component is used to keep the screen simple.
 
 .. code-block:: xml
 
     <screen>
         <consts>
-            <string name="title" value="Main menu"/>
+            <string name="title" value="Main Menu"/>
         </consts>
 
         <styles>
@@ -59,31 +62,37 @@ and a ``<my_main_cont>`` component is used to keep the screen simple.
         </view>
     </screen>
 
-Code export
+
+
+Code Export
 ***********
 
-When the C code is exported from the UI |nbsp| Editor, ``screen_name_gen.c/h`` files are exported,
+When C code is exported from the UI |nbsp| Editor, ``screen_name_gen.c/h`` files are exported,
 containing only a single ``lv_obj_t * screen_name_create(void)`` create function.
 
 By using this function, any number of screen instances can be created and loaded as needed.
 
+
+
 Preview
 *******
 
 Screens don't support the :ref:`<preview> <xml_preview>` tag because it doesn't make
 sense to preview each screen in different resolutions.
 
-As Screens are related to the target hardware in the ``project.xml`` file, multiple
+Since Screens are related to target hardware specified in the ``project.xml`` file, multiple
 ``<display>`` elements can be defined. In the UI |nbsp| Editor, when a Screen is being developed,
 the user can select from all the defined displays in the Preview, and the Screen will be shown with
 the given resolution and color depth.
 
 This is useful for verifying responsive designs.
 
+
+
 Events
 ******
 
-It's very common to load or create Screens on a button click or other events.
+It is very common to load or create Screens from a button-click or other type of event.
 
 Both are supported by adding special XML tags as children of Components or Widgets:
 
@@ -93,15 +102,15 @@ Both are supported by adding special XML tags as children of Components or Widge
        <lv_button>
            <lv_label text="Click or Long press me"/>
 
-           <!-- Load an already created screen that has the name "first".
+           <!-- Load an already created screen named "first".
                 Note that here the name of the instance is used,
-                and not the name of the XML file. -->
+                not the name of the XML file. -->
            <screen_load_event screen="first" trigger="clicked" anim_type="fade"/>
 
-           <!-- Create an instance of "about" and load it.
+           <!-- Create an instance of "about" Screen and load it.
-                Note that here the name of the XML file is used. -->
+                Note that the name of the XML file is used. -->
            <screen_create_event screen="about" trigger="long_pressed"/>
        </lv_button>
    </view>
 
-Learn more on :ref:`XML Events <xml_events_screen>` page.
+Learn more on the :ref:`XML Events <xml_events_screen>` page.

docs/src/details/xml/build_ui/root_elements/widgets.rst

@@ -11,9 +11,9 @@ Overview
     :trim:
 
 Besides components and Screens, Widgets are the other main building blocks of UIs.
-The XML file of the Widgets is wrapped in a ``<widget>`` XML root element.
+XML files defining Widgets have ``<widget>`` as their XML root element.
 
-``<widget>``\ s support the following child XML tags:
+``<widget>`` elements may contain the following child elements:
 
 - :ref:`<consts> <xml_consts>`
 - :ref:`<api> <xml_api>`
@@ -21,23 +21,25 @@ The XML file of the Widgets is wrapped in a ``<widget>`` XML root element.
 - :ref:`<view> <xml_view>`
 - :ref:`<previews> <xml_preview>`
 
-Just like Components, Widgets also can be the children of other Widgets and Components.
+Just like Components, Widgets can also be the children of other Widgets and Components.
+
+The main difference is that Widgets are written in C and compiled into the
+application.  This means, unlike Components, Widgets can contain custom C code.  For
+example, when a property is set, any complex C code can run to set that value.
+
+To connect the C code to XML, XML parser functions need to be implemented and registered. It is
+pretty simple since LVGL already provides all the helper functions and the required libraries. Also there
+are `many XML parser examples here <https://github.com/lvgl/lvgl/tree/master/src/others/xml/parsers>`__.
 
-The main difference is that Widgets are written in C and compiled into the application.
-It means unlike Components, Widgets can contain custom C code. For example, when a property is set,
-any complex C code can run to set that value.
 
-To connect the C code to XML, XML parser functions need to be implemented and registered. It's
-pretty simple as LVGL already provides all the helper functions and the required libraries. Also there
-are `many XML parser examples here. <https://github.com/lvgl/lvgl/tree/master/src/others/xml/parsers>`__
 
 Built-in Widgets
 ****************
 
-The built-in LVGL widgets (e.g. :ref:`lv_slider`, :ref:`lv_label`, :ref:`lv_chart`, etc.) already
+LVGL already has XML parsers for LVGL's built-in widgets (e.g. :ref:`lv_slider`,
-have XML parsers and therefore are available in XML.
+:ref:`lv_label`, :ref:`lv_chart`, etc.), which makes them available in XML.
 
-For example:
+Example:
 
 .. code-block:: xml
 
@@ -45,20 +47,23 @@ For example:
         <lv_label x="10" text="Hello"/>
     </view>
 
-The built-in widgets are
+The built-in widgets are:
 
 - pure C code
   (e.g. `lv_slider.c <https://github.com/lvgl/lvgl/tree/master/src/widgets/slider/lv_slider.c>`__)
 - an XML file to define only the API
-  (e.g. `lv_slider.xml <https://github.com/lvgl/lvgl/blob/master/xmls/lv_slider.xml>`__).
+  (e.g. `lv_slider.xml <https://github.com/lvgl/lvgl/blob/master/xmls/lv_slider.xml>`__)
-  It is used only in the UI |nbsp| Editor to validate and autocomplete properties.
+  (used only in the UI |nbsp| Editor to validate and autocomplete properties)
 - an XML parser C file to map the XML attributes to C functions.
   (e.g. `lv_xml_slider_parser.c <https://github.com/lvgl/lvgl/blob/master/src/others/xml/parsers/lv_xml_slider_parser.c>`__)
 
+
+
 Creating New Widgets
 ********************
 
-It's possible to create new widgets in the same way as the built-in LVGL widgets are handled.
+It is possible to create new Widgets that can be treated in the same way as built-in
+LVGL Widgets.
 
 However, using the UI |nbsp| Editor it's much faster and simpler. When an XML file is created and
 the ``<widget>`` root element is used, the following .C/.H files are generated automatically:
@@ -78,6 +83,8 @@ the ``<widget>`` root element is used, the following .C/.H files are generated a
                                 functions according to the set attributes. Only a
                                 skeleton is exported once.
 
+
+
 Usage
 *****
 
@@ -142,7 +149,7 @@ After registration, a Widget can be created like this from C code:
 
     lv_xml_create(lv_screen_active(), "lv_label", attrs);
 
-And in XML it can be used like
+And in XML it can be used like this:
 
 .. code-block:: xml
 
@@ -150,17 +157,18 @@ And in XML it can be used like
         <lv_label width="100" text="I'm a label!" wrap="scroll"/>
     </view>
 
+
 Adding Custom Code
 ------------------
 
 ``<widget_name>.c`` contains three hooks:
 
 - **Constructor hook**: Called when the Widget and all its children are created. Any
-  modifications can be done on the children here.
+  modifications to the children can be done here.
 - **Destructor hook**: Called when the Widget is deleted. All manually allocated
   memory needs to be freed here.
 - **Event hook**: Called at the beginning of the Widget's event callback to perform
-  any custom action.
+  any custom actions.
 
 In this C file, the ``set`` functions for each API ``<prop>`` also need to be
 implemented. The declaration of these functions is automatically exported in
@@ -168,13 +176,23 @@ implemented. The declaration of these functions is automatically exported in
 
 Besides these, any custom code and functions can be freely implemented in this file.
 
+
 Elements
 --------
 
 Elements are internal parts of the widget that can be accessed and/or created dynamically.
-For example, tabs of a tabview, list of a dropdown, series of a chart, etc.
+For example, tabs of a tabview, list of a dropdown, series of a chart, etc..
 
-Just like any other Widget API properties, Elements also can be defined in the ``<api>``
+Just like any other Widget API properties, Elements also can be defined within the
-tag of the Widget's XML.
+``<api>`` element of the Widget's XML.
 
-Learn more about the Elements in the documentation page of :ref:`<api> <xml_widget_element>`.
+Learn more about Elements under the :ref:`<api> element documentation <xml_widget_element>`.
+
+
+
+API
+***
+
+.. API startswith:  lv_xml_widget_
+
+.. API equals:  lv_xml_create

docs/src/details/xml/build_ui/translation.rst

@@ -1,8 +1,8 @@
 .. _xml_translation:
 
-============
+=====================
-Translations
+Language Translations
-============
+=====================
 
 Overview
 ********
@@ -10,7 +10,10 @@ Overview
 The XML translation module allows defining and using translated strings directly within XML files.
 
 It's built on top of :ref:`LVGL's translation module <translation>`.
-Check it out to learn more about selecting the active language, retrieving translations, and fallback behavior.
+
+Check it out to learn more about selecting the active language, retrieving
+translations, and fallback behavior.
+
 
 
 Usage

docs/src/details/xml/overview/component_library.rst

@@ -13,17 +13,18 @@ Overview
 The collection of Components, Widgets, Screens, Images, Fonts, etc., is called a
 Component Library.
 
-A Component Library can be fully self-sufficient, but it can also reference data from
+A Component Library can be fully self-contained, or it can also reference data from
 other Component Libraries.
 
 LVGL itself is a Component Library that supplies the built-in Widgets, data types,
-etc. You can
+etc.  You can find the XML files that describe the LVGL Widgets
-find the XML files that describe the LVGL Widgets
 `here <https://github.com/lvgl/lvgl/tree/master/xmls>`__.
 
-A project always has at least 2 Component Libraries:  that of LVGL as mentioned
+An LVGL firmware project that uses external XML files to define part (or all) of its
-above, and its own where the Screens, Components, and Widgets of the project are
+user interface (UI) always has at least 2 Component Libraries:  that of LVGL as
-defined.  A project may include additional Component Libraries.
+mentioned above, and at least 1 Component Library where a related set of Screens,
+Components, and Widgets of the project are defined.  A project may include additional
+Component Libraries.
 
 
 Structure
@@ -63,33 +64,30 @@ A typical structure for a Component Library looks like this:
       └── image2.png
 
 
-Visibility
+Name Visibility
-**********
+***************
 
-The content of all ``globals.xml`` files is part of a common global scope, and
+In the context of UI components defined in XML files, there are two namespaces:
-any Components, Widgets or Screens defined therein can be used in all .XML files.
 
-Styles, constants, and other data defined in the XML file of Components, Widgets, or Screens
+:global namespace:
-are local to that XML file.
 
-Thus, there are two namespaces:
+    Created from the combined data from the ``globals.xml`` file from each included
+    Component Library, the names of :ref:`Subjects <observer_subject>`, enumerations,
+    constants, styles, fonts and images defined therein can be referenced from all
+    XML files used in a project.
 
-1. **local namespace** within the given XML file of Components, Widgets and Screens.
+:local namespace:
-2. **global namespace** created from the data in the ``globals.xml`` file from each
-   Component Library included.
 
-To find names referenced in XML files, the local namespace is checked first, and if
+    Names created within all other XML files can only be referenced from within those
-a name is not found there, then the global namespace is checked.
+    XML files.  Exception:  names of defined Components, Widgets and Screens become
-
+    part of the global namespace, and therefore must be unique within the global
-The names of defined Components, Widgets and Screens become part of the global
+    namespace.  This ensures each Component has a unique name.
-namespace and must be unique therein.  This ensures that each Component has a unique
-name.
 
 All data belonging to the LVGL core Component Library is prefixed by ``lv_``
 (e.g., ``lv_label``, ``lv_font_default``).
 
 A custom Component can be prefixed with ``watch_``, ``small_``, ``light_``, or
-anything else the developer deems appropriate.
+anything else the development team deems appropriate.
 
 LVGL's UI |nbsp| Editor will show an error if there is a name conflict.
 
@@ -105,7 +103,7 @@ in it are:
 
 :<config>:          Can specify name and help.
 :<api>:             Used with ``<enumdefs>`` to show possible values for Widget or Component attributes.
-:<subjects>:        List of :ref:`Subjects <observer_subject>`. Can be considered the API of a Component Library.
+:<subjects>:        List of :ref:`Subjects <observer_subject>`; can be considered the API of a Component Library.
 :<consts>:          Globally available constants.
 :<styles>:          Globally available styles.
 :<fonts>:           Globally available fonts.

docs/src/details/xml/overview/intro.rst

@@ -7,15 +7,33 @@ Introduction
 .. |nbsp|   unicode:: U+000A0 .. NO-BREAK SPACE
     :trim:
 
-The LVGL XML Module implements LVGL's Declarative UI by loading UI elements written in
+.. glossary::
-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
+    Declarative UI
-- Autocomplete and Syntax highlighting
+
-- Online preview for collaboration and testing
+        Declarative UI (user interface) is an approach to UI creation in which the
-- `Figma <https://www.figma.com/>`__ integration to easily reimplement Figma designs
+        creator describes *what* elements are needed in the UI, what data they are
+        bound to, and to some degree, what they should look like, but can leave out
+        details such as their exact position or in what sequence they should be
+        created at run time.
+
+    Imperative UI
+
+        Imperative UI is an approach to UI creation in which the creator describes
+        every detail of how the UI is created at run time.  Imperative UI is the
+        UI-building approach you use when you build your LVGL UI in C code.
+
+The LVGL XML Module implements LVGL's :term:`Declarative UI` by loading UI elements
+written in XML.  The XML file can be written by hand, but it is considerably more
+efficient to write the XML files using `LVGL's UI Editor  <https://lvgl.io/editor>`__
+and thus highly recommended.  This UI Editor provides features like:
+
+- instant preview of the XML files,
+- auto-complete,
+- syntax highlighting,
+- online preview for collaboration and testing,
+- `Figma <https://www.figma.com/>`__ integration to efficiently implement Figma
+  designs in LVGL.
 
 .. warning::
 
@@ -60,7 +78,7 @@ push it back to the git repository so that other projects can be updated from it
 The built-in Widgets of LVGL are considered ``the core Component Library`` which is
 always available.
 
-A UI editor project can have any number of Component Libraries but will always
+A UI Editor project can have any number of Component Libraries but will always
 have at least 2:
 
 - LVGL's built-in Widgets, and
@@ -88,11 +106,11 @@ but rather compiled into the application as C code.  The main characteristics of
 - 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).
 
-Any handwritten Widget can be accessed from XML by:
+Any custom Widgets you create can be accessed from XML by:
 
 1. Defining its API in an XML file.
 2. Writing and registering an XML parser for it.
-   `See some examples here. <https://github.com/lvgl/lvgl/tree/master/src/others/xml/parsers>`__
+   `See examples here. <https://github.com/lvgl/lvgl/tree/master/src/others/xml/parsers>`__
 
 
 Components
@@ -109,10 +127,11 @@ The main characteristics of Components are:
 - 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
+Regardless of whether the XML was written manually or by the UI |nbsp| Editor, the XML
-defining Components can be registered in LVGL, and after that, instances can be created.
+files defining Components can be registered in LVGL, and after that, instances can be
-In other words, LVGL can just read the XML files, "learn" the Components from them, and
+created.  In other words, LVGL can just read the XML files, "learn" the Components
-thereafter create children as part of Screens and other Components.
+from them, and thereafter create those components as children of Screens and/or other
+Components.
 
 
 Screens
@@ -124,7 +143,7 @@ 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.
+- They can be referenced in Screen-load events.
 
 
 
@@ -148,7 +167,7 @@ will be children of these root elements:
             children and their properties.
 
 This is a simple example illustrating what an LVGL XML Component looks like.
-Note that only the basic features are shown here.
+Only basic features are shown.
 
 .. code-block:: xml
 
@@ -183,34 +202,36 @@ Usage Teaser
 
 LVGL's UI editor can be used in two different ways.
 
+
 Export C and H Files
 --------------------
 
 The Widgets, Components, Screens, images, fonts, etc., can be converted to .C/.H files having
-plain LVGL code. The exported code works the same way as if it was written by the
+code that accesses the LVGL API in the same way user-written code does.
-user.
 
-In this case, the XML files are not required anymore to run the C code (unless modifications may
+In this case, the XML files are not required anymore to run the C code (unless modifications
-be made later and code is exported again).
+are made later and code is exported again).
+
+The XML files were used only during Widget and Component creation to save
+recompilation time and optionally to take advantage of other useful UI editor features.
 
-The XML files were used only during editing/implementing the Widgets and Components to save
-recompilation time and optionally leverage other useful UI |nbsp| Editor features.
 
 Load the UI from XML
 --------------------
 
-Although the Widgets' code always needs to be exported in C and compiled into the
+Although Widgets' XML always needs to be exported in C and compiled into the
-application (just like the built-in LVGL Widgets are also part of the application), the Components'
+application (just like the built-in LVGL Widgets' C code is compiled into the
-XML can be loaded and any number of instances can be created at runtime.
+application), the XML for Components can be loaded (learned) at runtime, and
+thereafter any number of instances of them can be created.
 
 In the simplest case, a Component can be registered with
 :cpp:expr:`lv_xml_component_register_from_file(path)` and an instance can be created with
 :cpp:expr:`lv_obj_t * obj = lv_xml_create(parent, "my_button", NULL)`.
 
-Note that loading the UI from XML practically has no impact on performance.
+Note that loading UI components from XML has virtually no impact on performance.
-Once the XML files are registered and the UI is created, it behaves the same way
+Once the XML files are registered and the UI is created, the performance, appearance
-as if it were created from C code.
+and behavior are exactly the same as if it were created from C code.
 
-Registering XMLs and creating instances is not memory hungry nor slow. The biggest
+Registering XML Components and creating instances are neither memory hungry nor slow.
-memory overhead is that the ``<view>`` of the Components is saved in RAM (typically
+The biggest memory overhead is that the ``<view>`` of the Components is saved in RAM
-1–2 kB/component).
+(typically 1–2 kB/component).

docs/src/details/xml/overview/project.rst

@@ -13,8 +13,9 @@ Overview
 A single ``project.xml`` file should be created for each project where the following
 content is specified:
 
-:<folders>: Specifies the path to Component Libraries. LVGL's base Widgets are
+:<folders>: Specifies the list of paths to Component Libraries. LVGL's base Widgets are
-            always loaded automatically.
+            always loaded automatically, and therefore do not need to be specified
+            in this list.
 :<targets>: Describes various hardware configurations, allowing the UI |nbsp| Editor
             to check if the UI is out of resources and to select different previews
             for each Screen according to the specified displays.

docs/src/details/xml/overview/syntax.rst

@@ -11,15 +11,15 @@ Naming conventions
     :trim:
 
 - A standard XML syntax is used.
-- Lowercase letters with ``_`` separation are used for attribute names.
+- Lowercase letters with ``'_'`` separators are used for attribute names.
-- Tag names follow the usual variable-name rules: they must start with a letter or
+- Tag names follow the usual C variable-name rules: they must start with a letter or
   ``'_'`` and the rest of the name may be comprised of letters, ``'_'`` and digits.
 - The LVGL API is followed as much as possible, e.g., ``align="center"``, ``bg_color="0xff0000"``.
 - For colors, all these syntaxes are supported (similar to CSS colors): ``0x112233``,
   ``#112233``, ``112233``, ``0x123``, ``#123``, ``123``.  Note that like CSS,
   ``0x123``, ``#123`` and ``123`` all mean ``#112233``.
-- ``params`` can be referenced with ``$``.
+- ``params`` can be referenced using ``$`` as a name prefix.
-- ``consts`` can be referenced with ``#``.
+- ``consts`` can be referenced using ``#`` as a name prefix.
 - ``styles`` can be attached to states and/or parts like this:
   ``styles="style1 style2:pressed style3:focused:scrollbar"``.
 - Local styles (i.e. styles that are stored within the Component and thus not shared
@@ -28,10 +28,10 @@ Naming conventions
 
 
 
-Types
+Data Types
-*****
+**********
 
-All of the types can be used as API property types, but only a subset of them can be
+All of the data types can be used as API property types, but only a subset of them can be
 used as constant and :ref:`Subject <observer_subject>` types.
 
 
@@ -42,10 +42,10 @@ The following simple built-in types are supported:
 
 :bool:      a ``true`` or ``false``.
 
-:int:       Integer number in the range of roughly -2B to 2B by default.
+:int:       Integer number in the range of roughly -2 billion to 2 billion by default.
             (Same as ``int32_t`` in C.)
 
-:px:        Simple pixel units.  The unit ``px`` can be omitted.
+:px:        Simple pixel units.  The unit suffix ``px`` can be omitted from the numeric value.
 
 :%:         Percentage.  ``%`` must be appended to the value as the unit.
             (Means the same as :cpp:expr:`lv_pct()`.)
@@ -53,7 +53,8 @@ The following simple built-in types are supported:
 :content:   Means ``LV_SIZE_CONTENT``.
 
 :string:    Simple NUL-terminated string.  When multiple strings are used in a
-            property or string array, ``'`` should be used.  E.g. ``foo="'a' 'b'"``.
+            property or string array, ``'`` should be used.  E.g. ``foo="'a' 'b'"``
+            represents an array of 2 strings.
 
 :color:     A color stored as 24-bit RGB (:cpp:expr:`lv_color_t`).
 
@@ -64,47 +65,50 @@ The following simple built-in types are supported:
 
 :screen:    Pointer to a screen (also :cpp:expr:`lv_obj_t *`).
 
-:time_ms:   Means some time in milliseconds unit
+:time_ms:   Means some time in milliseconds
 
 :deg_0.1:   Degrees with 0.1 resolution
 
 :scale_1/256:   Scale/Zoom, where 256 means 100%, 128 means 50%, 512 means 200% etc.
 
+
 Name-based types
 ----------------
 
-In XML files, fonts, images, styles, etc., are not used by pointer but by string
+In XML files, fonts, images, styles, etc., are used by their names, rather than by
-names.  For example, a style is defined like ``<style name="red" bg_color="0xff0000"/>``.
+pointers as they are in C.  For example, a style is defined like ``<style name="red"
-Later, they can be referenced by their names.
+bg_color="0xff0000"/>``.  Later, it can be referenced by its name:  "red".
 
-This means that the actual values need to be bound to the names when the UI is loaded
+This means that the actual objects need to be bound to the names when the UI is loaded
-from XML, otherwise, LVGL wouldn't know what a name means.
+from XML files so LVGL knows what each name means.
 
 Most of these connections are done automatically (e.g., for styles, fonts, images,
-animations, gradients, etc.), but others need to be connected manually (e.g., event
+animations, gradients, etc.), but others need to be connected manually in C code
-callbacks where the callback itself is available only in the code).
+(e.g., event callbacks where the callback itself is available only in C code).
 
-For fonts and images, the connections are created automatically if the source is a file.
+For fonts and images, the connections are created automatically if the source is an
-If the font or image is compiled into the application (as a C array), the user needs
+XML file.  If the font or image is compiled into the application (as a C array), the
-to specify which variable a given name refers to.
+user needs to specify which variable a given name refers to.
 
 To create these connections, functions like
 
-- ``lv_xml_register_image(scope, name, pointer)``
+- :cpp:expr:`lv_xml_register_image(scope, name, pointer)`
-- ``lv_xml_register_font(scope, name, pointer)``
+- :cpp:expr:`lv_xml_register_font(scope, name, pointer)`
-- ``lv_xml_register_event_cb(scope, name, callback)``
+- :cpp:expr:`lv_xml_register_event_cb(scope, name, callback)`
 - etc.
 
 can be used.  Later, a pointer to the object can be retrieved by
 
-- ``lv_xml_get_image(scope, name)``
+- :cpp:expr:`lv_xml_get_image(scope, name)`
-- ``lv_xml_get_font(scope, name)``
+- :cpp:expr:`lv_xml_get_font(scope, name)`
-- ``lv_xml_get_event_cb(scope, name)``
+- :cpp:expr:`lv_xml_get_event_cb(scope, name)`
 - etc.
 
 ``scope`` can be ``NULL`` to use the global scope or :cpp:expr:`lv_xml_component_get_scope("my_component")`
 returns the a component's local scope.
 
+The passed ``name`` strings can be bound to:
+
 :style:     Name of a style. :cpp:expr:`lv_xml_get_style_by_name(&ctx, name)` returns an :cpp:expr:`lv_style_t *`.
 :font:      Name of a font. :cpp:expr:`lv_xml_get_font(&ctx, name)` returns an :cpp:expr:`lv_font_t *`.
 :image:     Name of an image. :cpp:expr:`lv_xml_get_image(&ctx, name)` returns an :cpp:expr:`const void *`,
@@ -113,7 +117,8 @@ returns the a component's local scope.
 :subject:   Name of a :ref:`Subject <observer_subject>`. :cpp:expr:`lv_xml_get_subject(&ctx, name)` returns an :cpp:expr:`lv_subject_t *`.
 :grad:      Name of a gradient. :cpp:expr:`lv_xml_get_grad(&ctx, name)` returns an :cpp:expr:`lv_grad_dsc_t *`.
 :event_cb:  Name of an event callback. :cpp:expr:`lv_xml_get_event_cb(&ctx, name)` returns an :cpp:expr:`lv_event_cb_t`.
-:screen_create_cb:  In XML it's the name of a screen XML file. In exported code it's a function like ``lv_obj_t * my_screen_create(void)``
+:screen_create_cb:  In XML it's the name of a screen's XML file. In exported code it's a function like ``lv_obj_t * my_screen_create(void)``
+
 
 Arrays
 ------
@@ -121,7 +126,7 @@ Arrays
 An array of any type can be defined in four ways:
 
 :int[N]:            An integer array with ``N`` elements.
-                    In the exported code ``N`` is passed a parameter after the array.
+                    In the exported code ``N`` is passed as a parameter after the array.
 :string[...NULL]:   An array terminated with a ``NULL`` element. ``NULL`` can be
                     replaced by any value.
 :string[5]:         An array that must have exactly 5 elements. In the exported code only the array will be passed
@@ -146,7 +151,7 @@ For example:
             <enum name="inverted" help="Inverted mode"/>
         </enumdef>
 
-        <prop name="mode" help="help"type="enum:my_widget_mode" help="help"/>
+        <prop name="mode" help="help" type="enum:my_widget_mode" help="help"/>
     </api>
 
 When used as a type, a ``+`` suffix means multiple values can be selected and ORed.
@@ -157,7 +162,7 @@ For example: ``type="axis+"``.  In this case, the options should be separated by
 Compound types
 --------------
 
-Types can be compound, meaning multiple options/types are possible.  For example, for
+Types can be compound, meaning multiple options/types are possible.  Example for
 width: ``type="px|%|content"``.
 
 
@@ -169,7 +174,7 @@ For example:
 
 - Enums: ``type="dir(top bottom)"``
 - Colors: ``type="color(0xff0000 0x00ff00 0x0000ff)"``
-- Strings: ``type="string('Ok' 'Cancel')``
+- Strings: ``type="string('Ok' 'Cancel')"``
 
 Limiting accepted values is not supported yet, however in the UI |nbsp| Editor if
 an invalid option is selected, it will be highlighted as an error.