diff --git a/components/lvgl/widgets.rst b/components/lvgl/widgets.rst index 9bcb2dff7c..47631bbc10 100644 --- a/components/lvgl/widgets.rst +++ b/components/lvgl/widgets.rst @@ -240,8 +240,8 @@ The animation image is similar to the normal ``image`` widget. The main differen - **id** (**Required**): The ID or a list of IDs of animimg widgets which you want stop. - ``lvgl.animimg.update`` :ref:`action ` can be used to change ``repeat_count`` and ``duration``, just like the :ref:`lvgl.widget.update ` action is used for the common styles, states or flags. ``src`` and ``auto_start`` cannot be updated at runtime. - - **id** (**Required**): The ID or a list of IDs of animimg widgets which you want update. - - Widget styles or properties from the specific options above, which you want update. + - **id** (**Required**): The ID or a list of IDs of animimg widgets to be updated. + - Widget styles or properties from the specific options above, to be updated. **Triggers:** @@ -306,8 +306,8 @@ If the ``adv_hittest`` :ref:`flag ` is enabled the arc can be **Actions:** - ``lvgl.arc.update`` :ref:`action ` updates the widget styles and properties from the specific options above, just like the :ref:`lvgl.widget.update ` action is used for the common styles, states or flags. - - **id** (**Required**): The ID or a list of IDs of arc widgets which you want update. - - Widget styles or properties from the specific options above, which you want update. + - **id** (**Required**): The ID or a list of IDs of arc widgets to be updated. + - Widget styles or properties from the specific options above, to be updated. **Triggers:** @@ -381,8 +381,8 @@ Not only the end, but also the start value of the bar can be set, which changes **Actions:** - ``lvgl.bar.update`` :ref:`action ` updates the widget styles and properties from the specific options above, just like the :ref:`lvgl.widget.update ` action is used for the common styles, states or flags. - - **id** (**Required**): The ID or a list of IDs of bar widgets which you want update. - - Widget styles or properties from the specific options above, which you want update. + - **id** (**Required**): The ID or a list of IDs of bar widgets to be updated. + - Widget styles or properties from the specific options above, to be updated. **Triggers:** @@ -511,12 +511,12 @@ The button matrix widget is a lightweight way to display multiple buttons in row **Actions:** - ``lvgl.buttonmatrix.update`` :ref:`action ` updates the item styles and properties specified in the specific ``state``, ``items`` options. - - **id** (**Required**): The ID or a list of IDs of buttonmatrix widgets which you want update. - - Widget styles or properties from ``state``, ``items`` options above, which you want update. + - **id** (**Required**): The ID or a list of IDs of buttonmatrix widgets to be updated. + - Widget styles or properties from ``state``, ``items`` options above, to be updated. - ``lvgl.matrix.button.update`` :ref:`action ` updates the button styles and properties specified in the specific ``control``, ``width`` and ``selected`` options. - - **id** (**Required**): The ID or a list of IDs of matrix buttons which you want update. - - Widget styles or properties from ``control``, ``width`` and ``selected`` options above, which you want update. + - **id** (**Required**): The ID or a list of IDs of matrix buttons to be updated. + - Widget styles or properties from ``control``, ``width`` and ``selected`` options above, to be updated. **Triggers:** @@ -624,9 +624,9 @@ The checkbox widget is made internally from a *tick box* and a label. When the c **Actions:** - ``lvgl.checkbox.update`` :ref:`action ` updates the widget styles and properties from the specific options above, just like the :ref:`lvgl.widget.update ` action is used for the common styles, states or flags. - - **id** (**Required**): The ID or a list of IDs of checkbox widgets which you want update. + - **id** (**Required**): The ID or a list of IDs of checkbox widgets to be updated. - **text** (*Optional*, :ref:`text-property`): Text to display beside the checkbox. - - Widget styles or properties from the specific options above, which you want update. + - Widget styles or properties from the specific options above, to be updated. **Triggers:** @@ -689,14 +689,15 @@ The Dropdown widget is built internally from a *button* part and a *list* part ( - **indicator** (*Optional*, dict): Styles for the dropdown symbol. - **options** (**Required**, list): The list of available options in the drop-down. - **selected_index** (*Optional*, int8): The index of the item you wish to be selected. +- **selected_text** (*Optional*, string): The text of the item you wish to be selected. - **symbol** (*Optional*, dict): A symbol (typically an chevron) is shown in dropdown list. If ``dir`` of the drop-down list is ``LEFT`` the symbol will be shown on the left, otherwise on the right. Choose a different :ref:`symbol ` from those built-in or from your own customized font. - Style options from :ref:`lvgl-styling` for the background of the button. Uses the typical background properties and :ref:`lvgl-widget-label` text properties for the text on it. ``text_font`` can be used to set the font of the button part, including the symbol. **Actions:** - ``lvgl.dropdown.update`` :ref:`action ` updates the widget styles and properties from the specific options above, just like the :ref:`lvgl.widget.update ` action is used for the common styles, states or flags. - - **id** (**Required**): The ID or a list of IDs of dropdown widgets which you want update. - - Widget styles or properties from the specific options above, which you want update. + - **id** (**Required**): The ID or a list of IDs of dropdown widgets to update. + - Widget styles or properties from the specific options above to update. **Triggers:** @@ -772,8 +773,8 @@ Images are the basic widgets used to display images. **Actions:** - ``lvgl.image.update`` :ref:`action ` updates the widget styles and properties from the specific options above, just like the :ref:`lvgl.widget.update ` action is used for the common styles, states or flags. Updating the ``src`` option changes the image at runtime. - - **id** (**Required**): The ID or a list of IDs of image widgets which you want update. - - Widget styles or properties from the specific options above, which you want update. + - **id** (**Required**): The ID or a list of IDs of image widgets to be updated. + - Widget styles or properties from the specific options above, to be updated. **Triggers:** @@ -912,9 +913,9 @@ A label is the basic widget type that is used to display text. **Actions:** - ``lvgl.label.update`` :ref:`action ` updates the widget styles and properties from the specific options above, just like the :ref:`lvgl.widget.update ` action is used for the common styles, states or flags. - - **id** (**Required**): The ID or a list of IDs of label widgets which you want update. + - **id** (**Required**): The ID or a list of IDs of label widgets to be updated. - **text** (*Optional*, :ref:`text-property`): Text to display on the button. - - Widget styles or properties from the specific options above, which you want update. + - Widget styles or properties from the specific options above, to be updated. **Triggers:** @@ -967,8 +968,8 @@ The LED widgets are either circular or rectangular widgets whose brightness can **Actions:** - ``lvgl.led.update`` :ref:`action ` updates the widget styles and properties from the specific options above, just like the :ref:`lvgl.widget.update ` action is used for the common styles, states or flags. - - **id** (**Required**): The ID or a list of IDs of led widgets which you want update. - - Widget styles or properties from the specific options above, which you want update. + - **id** (**Required**): The ID or a list of IDs of led widgets to be updated. + - Widget styles or properties from the specific options above, to be updated. **Triggers:** @@ -1263,6 +1264,7 @@ Roller allows you to simply select one option from a list by scrolling. - **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_text** (*Optional*, string): The text 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 ` 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. - **visible_row_count** (*Optional*, int8): The number of visible rows. - Style options from :ref:`lvgl-styling`. The background of the roller uses all the typical background properties and :ref:`lvgl-widget-label` style properties. ``text_line_space`` adjusts the space between the options. @@ -1270,12 +1272,13 @@ Roller allows you to simply select one option from a list by scrolling. **Actions:** - ``lvgl.roller.update`` :ref:`action ` updates the widget styles and properties from the specific options above, just like the :ref:`lvgl.widget.update ` action is used for the common styles, states or flags. - - **id** (**Required**): The ID or a list of IDs of roller widgets which you want update. - - Widget styles or properties from the specific options above, which you want update. +- **id** (**Required**): The ID or a list of IDs of roller widgets to be updated. +- **animated** (*Optional*, boolean): Animate the indicator when the bar changes value. Defaults to ``true``. +- All the other roller options as listed above. **Triggers:** -- ``on_value`` :ref:`trigger ` is activated when you select an item from the list. The new selected index is returned in the variable ``x``. +- ``on_value`` :ref:`trigger ` is activated when you select an item from the list. The new selected index is returned in the variable ``x``, and the text of the selected item is returned in the variable ``text``. - :ref:`interaction ` LVGL event triggers which also return the selected index in ``x``. **Example:** @@ -1305,8 +1308,8 @@ Roller allows you to simply select one option from a list by scrolling. ... on_value: - logger.log: - format: "Selected index is: %d" - args: [ x ] + format: "Selected index is: %d, text is: %s" + args: [x, text.c_str()] The ``roller`` can be also integrated as :doc:`Select ` component. @@ -1336,8 +1339,8 @@ Normally, the slider can be adjusted either by dragging the knob, or by clicking **Actions:** - ``lvgl.slider.update`` :ref:`action ` updates the widget styles and properties from the specific options above, just like the :ref:`lvgl.widget.update ` action is used for the common styles, states or flags. - - **id** (**Required**): The ID or a list of IDs of slider widgets which you want update. - - Widget styles or properties from the specific options above, which you want update. + - **id** (**Required**): The ID or a list of IDs of slider widgets to be updated. + - Widget styles or properties from the specific options above, to be updated. **Triggers:** @@ -1411,8 +1414,8 @@ The spinbox contains a numeric value (as text) which can be increased or decreas **Actions:** - ``lvgl.spinbox.update`` :ref:`action ` updates the widget styles and properties from the specific options above, just like the :ref:`lvgl.widget.update ` action is used for the common styles, states or flags. - - **id** (**Required**): The ID or a list of IDs of spinbox widgets which you want update. - - Widget styles or properties from the specific options above, which you want update. + - **id** (**Required**): The ID or a list of IDs of spinbox widgets to be updated. + - Widget styles or properties from the specific options above, to be updated. - ``lvgl.spinbox.increment`` :ref:`action ` increases the value by one ``step`` configured above. - **id** (**Required**): The ID of the spinbox widget which you want to increment. @@ -1485,8 +1488,8 @@ The Spinner widget is a spinning arc over a ring. **Actions:** - ``lvgl.spinner.update`` :ref:`action ` updates the widget styles and properties for the *indicator* part (anything other than the properties that apply commonly to all widgets), just like the :ref:`lvgl.widget.update ` action is used for the common styles, states or flags. - - **id** (**Required**): The ID or a list of IDs of spinner widgets which you want update. - - Widget styles or properties from the specific options above, which you want update. + - **id** (**Required**): The ID or a list of IDs of spinner widgets to be updated. + - Widget styles or properties from the specific options above, to be updated. **Triggers:** @@ -1655,7 +1658,7 @@ The textarea is an extended label widget which displays a cursor and allows the **Actions:** - ``lvgl.textarea.update`` :ref:`action ` updates the widget's ``text`` property, to replace the entire text content. - - **id** (**Required**): The ID or a list of IDs of textarea widgets which you want update. + - **id** (**Required**): The ID or a list of IDs of textarea widgets to be updated. - **text** (*Optional*, :ref:`text-property`): The text to replace the textarea content. **Triggers:** @@ -1706,7 +1709,7 @@ The ``textarea`` can be also integrated as :doc:`Text ` o The tileview is a container object whose elements, called tiles, can be arranged in grid form. A user can navigate between the tiles by dragging or swiping. Any direction can be disabled on the tiles individually to not allow moving from one tile to another. -If the Tile view is screen sized, the user interface resembles what you may have seen on smartwatches. +If the tileview is screen sized, the user interface resembles what you may have seen on smartwatches. The tileview has parts ``main`` and ``scrollbar``. **Configuration variables:** @@ -1785,7 +1788,7 @@ Several universal actions are also available for all widgets, these are outlined This powerful :ref:`action ` allows changing/updating any widget's common :ref:`style property `, state (templatable) or :ref:`flag ` on the fly. -- **id** (**Required**): The ID or a list of IDs of widgets configured in LVGL which you want update. +- **id** (**Required**): The ID or a list of IDs of widgets configured in LVGL to be updated. - The widget's common :ref:`style property `, state (templatable) or :ref:`flag `. .. code-block:: yaml