[LVGL] documentation for gradients and meter parts. (#4236)

2024-09-21 03:21:20 +02:00 · 2024-09-10 11:24:21 +10:00 · 2024-09-10 11:24:21 +10:00 · d1eb610d81
commit d1eb610d81
parent 81f838f0af
2 changed files with 91 additions and 12 deletions
--- a/components/lvgl/index.rst
+++ b/components/lvgl/index.rst
@ -113,6 +113,7 @@ The following configuration variables apply to the main ``lvgl`` component, in o
 - **disp_bg_image** (*Optional*, :ref:`image <display-image>`):  The ID of an existing image configuration, to be used as background wallpaper. To change the image at runtime use the ``lvgl.update`` action. Also see :ref:`lvgl-widget-image` for a note regarding supported image formats.
 - **default_font** (*Optional*, ID): The ID of the :ref:`font <lvgl-fonts>` used by default to render the text or symbols. Defaults to LVGL's internal ``montserrat_14`` if not specified.
 - **style_definitions** (*Optional*, list): A batch of style definitions to use in LVGL widget's ``styles`` configuration. See :ref:`below <lvgl-theme>` for more details.
+- **gradients** (*Optional*, list): A list of gradient definitions to use in *bg_grad* styles. See :ref:`below <lvgl-gradients>` for more details.
 - **theme** (*Optional*, list): A list of styles to be applied to all widgets. See :ref:`below <lvgl-theme>` for more details.
 - **widgets** (*Optional*, list): A list of :doc:`/components/lvgl/widgets` to be drawn on the root display. May not be used if ``pages`` (below) is configured.
 - **pages** (*Optional*, list): A list of page IDs. Each page acts as a parent for widgets placed on it. May not be used with ``widgets`` (above). Options for each page:
@ -243,6 +244,7 @@ You can adjust the appearance of widgets by changing their foreground, backgroun
 **Styling variables:**

 - **bg_color** (*Optional*, :ref:`color <lvgl-color>`): Color for the background of the widget. Defaults to ``0xFFFFFF`` (white).
+- **bg_grad** (*Optional*, :ref:`gradient <lvgl-gradients>`): A gradient to apply to the background.
 - **bg_grad_color** (*Optional*, :ref:`color <lvgl-color>`): Color to make the background gradually fade to. Defaults to ``0`` (black).
 - **bg_dither_mode** (*Optional*, dict): Set dithering of the background gradient. One of ``NONE``, ``ORDERED``, ``ERR_DIFF``. Defaults to ``NONE``.
 - **bg_grad_dir** (*Optional*, dict): Choose the direction of the background gradient: ``NONE``, ``HOR``, ``VER``. Defaults to ``NONE``.
@ -519,6 +521,46 @@ Values for use with ``grid_column_align``, ``grid_row_align``, ``grid_cell_x_ali

    To visualize real, calculated sizes of transparent widgets you can temporarily set ``outline_width: 1`` on them.

+.. _lvgl-gradients:
+
+Gradients
+*********
+
+A gradient is a sequence of colors which can be applied to an object using the ``bg_grad`` style option. Gradients are defined in the *gradients* section of the LVGL configuration by providing two or more color stop points.
+ Each entry has the following options:
+
+- **id** (**Required**, :ref:`config-id`): The ID with which you will be able to reference the gradient later.
+- **direction** (*Optional*, string): The direction of the gradient. Possible options are ``none`` (the default) ``hor`` or ``ver``.
+- **dither** (*Optional*, string): A dithering selection. Possible options are ``none`` (the default) ``err_diff`` or ``ordered``.
+- **stops** (**Required**, list): A list of at least 2 color stop points. Each stop point has the following options:
+    - **color** (**Required**, :ref:`Color <lvgl-color>`): The color of the stop point.
+    - **position** (**Required**, float): The position of the stop point. Must be a float between 0.0 and 1.0, a percentage between 0% and 100%, or an integer between 0 and 255.
+
+.. code-block:: yaml
+
+    # Example gradient showing full hue range.
+
+      gradients:
+        - id: color_bar
+          direction: hor
+          dither: none
+          stops:
+            - color: 0xFF0000
+              position: 0
+            - color: 0xFFFF00
+              position: 42
+            - color: 0x00FF00
+              position: 84
+            - color: 0x00FFFF
+              position: 127
+            - color: 0x0000FF
+              position: 169
+            - color: 0xFF00FF
+              position: 212
+            - color: 0xFF0000
+              position: 255
+
+
 Widgets
 *******

--- a/components/lvgl/widgets.rst
+++ b/components/lvgl/widgets.rst
@ -40,7 +40,7 @@ The properties below are common to all widgets.
    - ``"ACTIVE"``: Show scroll bars while a widget is being scrolled.
    - ``"AUTO"``: Show scroll bars when the content is large enough to be scrolled (default).

- **align** (*Optional*, dict): Alignment of the of the widget relative to the parent. A child widget is clipped to its parent boundaries. One of the values *not* starting with ``OUT_`` (see picture below).
+- **align** (*Optional*, enum): Alignment of the of the widget relative to the parent. A child widget is clipped to its parent boundaries. One of the values *not* starting with ``OUT_`` (see picture below).
 - **align_to** (*Optional*, list): Alignment of the of the widget relative to another widget on the same level:
    - **id** (**Required**): The ID of a widget *to* which you want to align.
    - **align** (**Required**, string): Desired alignment (one of the values starting with ``OUT_``).
@ -116,6 +116,40 @@ In addition to visual styling, each widget supports some boolean **flags** to in

    LVGL only supports **integers** for numeric ``value``. Visualizer widgets can't display floats directly, but they allow scaling by 10s.

+.. _lvgl-widget-parts:
+
+Widget parts
+------------
+
+Widgets can have multiple parts, each of which can be styled independently. For example, a checkbox has a *main* part that styles the background and text label, and an *indicator* part that styles the tick box. All widgets have a *main* part, the available parts for other widgets are specified in the widget description.
+
+The possible parts are:
+
+- **main** (*Optional*, dict): The main part of the widget, i.e. the background. Any style properties applied at the top level of the widget are assumed to apply to this part, but may also be specified under the *main* config key.
+- **scrollbar** (*Optional*, dict): The scrollbar styles.
+- **indicator** (*Optional*, dict): The indicator part of the widget. The indicator part may be used to show tick boxes or other visual indicators in slider, bar or arc.
+- **knob** (*Optional*, dict): The knob part of the widget e.g. a draggable item in slider, bar or arc.
+- **selected** (*Optional*, dict): The currently selected part of the widget, e.g. text or the selected item in a roller.
+- **items** (*Optional*, dict): The items part of the widget, e.g. the items in a roller.
+- **ticks** (*Optional*, dict): Ticks on scales for a meter.
+- **cursor** (*Optional*, dict): The cursor part of the widget, e.g. the cursor in a spinbox.
+
+.. code-block:: yaml
+
+    # Example slider with knob and indicator styling
+    - slider:
+        # main (background) styles
+        bg_opa: cover
+        bg_grad: color_bar
+        radius: 0
+        indicator:
+          bg_opa: transp    # Makes the indicator part invisible
+        knob:
+          radius: 1
+          width: 4
+          height: 10%
+          bg_color: 0x000000
+
 Widget-specific properties
 --------------------------

@ -776,8 +810,8 @@ For styling, the ``keyboard`` widget uses the same settings as :ref:`lvgl-widget

 **Configuration variables:**

- **textarea** (*Optional*): The ID of the ``textarea`` from which to receive the keystrokes.
- **mode** (*Optional*, dict): Keyboard layout to use. Each ``TEXT_`` layout contains a button to allow the user to iterate through the ``TEXT_`` layouts.
+- **textarea** (*Optional*): The ID of a ``textarea`` to associate with the keyboard. If provided, all key entries are recorded in the ``textarea``.
+- **mode** (*Optional*, enum): Keyboard layout to use. Each ``TEXT_`` layout contains a button to allow the user to iterate through the ``TEXT_`` layouts.
    - ``TEXT_LOWER``: Display lower case letters (default).
    - ``TEXT_UPPER``: Display upper case letters.
    - ``TEXT_SPECIAL``: Display special characters.
@ -785,9 +819,9 @@ For styling, the ``keyboard`` widget uses the same settings as :ref:`lvgl-widget

 **Actions:**

- ``lvgl.keyboard.update`` :ref:`action <actions-action>` updates the widget styles and properties from the specific options above, just like the :ref:`lvgl.widget.update <lvgl-automation-actions>` action is used for the common styles, states or flags.
-    - **id** (**Required**): The ID or a list of IDs of keyboard widgets which you want update.
-    - Widget styles or properties from the specific options above, which you want update.
+- ``lvgl.keyboard.update`` :ref:`action <actions-action>` updates the properties from the specific options above, plus any from :ref:`lvgl.widget.update <lvgl-automation-actions>`.
+    - **id** (**Required**): The ID or a list of IDs of keyboard widgets which you want to update.
+    - Styles or properties to be updated.

 **Triggers:**

@ -851,7 +885,7 @@ A label is the basic widget type that is used to display text.
 - **recolor** (*Optional*, boolean): Enable recoloring of button text with ``#``. This makes it possible to set the color of characters in the text individually by prefixing the text to be re-colored with a ``#RRGGBB`` hexadecimal color code followed by a *space*, and finally closed with a single hash ``#`` tag. For example: ``Write a #FF0000 red# word``.
 - **scrollbar** (*Optional*, list): Settings for the indicator *part* to show the value. Supports a list of :ref:`styles <lvgl-styling>` and state-based styles to customize. The scroll bar that is shown when the text is larger than the widget's size.
 - **selected** (*Optional*, list): Settings for the the style of the selected text. Only ``text_color`` and ``bg_color`` style properties can be used.
- **text_align** (*Optional*, dict): Alignment of the text in the widget - it doesn't align the object itself, only the lines inside the object. One of ``LEFT``, ``CENTER``, ``RIGHT``, ``AUTO``. Inherited from parent. Defaults to ``AUTO``, which detects the text base direction and uses left or right alignment accordingly.
+- **text_align** (*Optional*, enum): Alignment of the text in the widget - it doesn't align the object itself, only the lines inside the object. One of ``LEFT``, ``CENTER``, ``RIGHT``, ``AUTO``. Inherited from parent. Defaults to ``AUTO``, which detects the text base direction and uses left or right alignment accordingly.
 - **text_color** (*Optional*, :ref:`color <lvgl-color>`): Color to render the text in. Inherited from parent. Defaults to ``0`` (black).
 - **text_decor** (*Optional*, list): Choose decorations for the text: ``NONE``, ``UNDERLINE``, ``STRIKETHROUGH`` (multiple can be specified as YAML list). Inherited from parent. Defaults to ``NONE``.
 - **text_font**: (*Optional*, :ref:`font <lvgl-fonts>`):  The ID of the font used to render the text or symbol. Inherited from parent.
@ -1050,6 +1084,9 @@ The meter widget can visualize data in very flexible ways. It can use arcs, need
            - **width**: Tick line width in pixels. Defaults to ``5``.
        - Style options from :ref:`lvgl-styling` for the tick *lines* and *labels* using the :ref:`lvgl-widget-line` and :ref:`lvgl-widget-label` text style properties.
 - Style options from :ref:`lvgl-styling` for the background of the meter, using the typical background properties.
+- **ticks** (*Optional*, dict): Styling options for the ticks *part*, which will be applied to the tick lines and labels using standard *line* and *label* styles.
+- **indicator** (*Optional*, dict): Styling options for the indicator *part*, which will be applied to the needle line or image using standard *line* and *image* styles.
+- **items** (*Optional*, dict): Settings for the items *part*, which will be applied to arcs.

 .. note::

@ -1116,7 +1153,7 @@ The text will be broken into multiple lines automatically and the height will be

 **Configuration variables:**

- **msgboxes** (*Optional*, dict): A list of message boxes to use. This option has to be added to the top level of the LVGL component configuration.
+- **msgboxes** (*Optional*, list): A list of message boxes to use. This option is available only at the top level of the LVGL component configuration. Each list entry may have the following options:
    - **title** (**Required**, string): A string to display at the top of the message box.
    - **body** (*Optional*, dict): The content of the body of the message box:
        - **text** (*Optional*, :ref:`text-property`): The text to display in the body of the message box.
@ -1129,7 +1166,7 @@ The text will be broken into multiple lines automatically and the height will be

 **Actions:**

-The configured message boxes are hidden by default. One can show them with ``lvgl.widget.show`` and ``lvgl.widget.hide`` :ref:`actions <lvgl-automation-shorthands>`.
+The configured message boxes are hidden by default. They can be shown and hidden using ``lvgl.widget.show`` and ``lvgl.widget.hide`` respectively :ref:`actions <lvgl-automation-shorthands>`.

 **Example:**

@ -1204,7 +1241,7 @@ Roller allows you to simply select one option from a list by scrolling.
 **Configuration variables:**

 - **anim_time** (*Optional*, :ref:`Time <config-time>`): When the Roller is scrolled and doesn't stop exactly on an option it will scroll to the nearest valid option automatically in this amount of time.
- **mode** (*Optional*, dict): Option to make the roller circular. ``NORMAL`` or ``INFINITE``, defaults to ``NORMAL``.
+- **mode** (*Optional*, enum): Option to make the roller circular. ``NORMAL`` or ``INFINITE``, defaults to ``NORMAL``.
 - **options** (**Required**, list): The list of available options in the roller.
 - **selected_index** (*Optional*, int8): The index of the item you wish to be selected.
 - **selected** (*Optional*, list): Settings for the selected *part* to show the value. Supports a list of :ref:`styles <lvgl-styling>` and state-based styles to customize. The selected option in the middle. Besides the typical background properties it uses the :ref:`lvgl-widget-label` text style properties to change the appearance of the text in the selected area.
@ -1508,14 +1545,14 @@ The tabs are indexed (zero-based) in the order they appear in the configuration

 **Configuration variables:**

- **position** (*Optional*, string): Position of the tab selector buttons. One of ``TOP``, ``BOTTOM``, ``LEFT``, ``RIGHT``. Defaults to ``TOP``.
+- **position** (*Optional*, enum): Position of the tab selector buttons. One of ``TOP``, ``BOTTOM``, ``LEFT``, ``RIGHT``. Defaults to ``TOP``.
 - **size** (*Optional*, percentage): The height (in case of ``TOP``, ``BOTTOM``) or width (in case of ``LEFT``, ``RIGHT``) tab buttons. Defaults to ``10%``.
 - **tabs** (**Required**, list): A list with (any number of) tabs to be added to tabview.
    - **name** (**Required**): The text to be shown on the button corresponding to the tab.
    - **id** (*Optional*): An ID for the tab itself.
    - **widgets** (**Required**, list): A list of :doc:`/components/lvgl/widgets` to be drawn on the tab, as children.
 - **tab_style** (*Optional*): Style settings for the tabs.
-    - **items** (*Optional*, list): Settings for the items *part*, the buttons all use the text and typical background style properties except translations and transformations.
+    - **items** (*Optional*, dict): Settings for the items *part*, the buttons all use the text and typical background style properties except translations and transformations.

 **Actions:**