mirror of
https://github.com/lvgl/lvgl.git
synced 2026-05-20 21:35:19 +08:00
Kevin Schlosser
78 lines
2.2 KiB
ReStructuredText
78 lines
2.2 KiB
ReStructuredText
Roller (lv_roller)
|
||
==================
|
||
|
||
Overview
|
||
********
|
||
|
||
Roller allows you to simply select one option from a list by scrolling.
|
||
|
||
Parts and Styles
|
||
****************
|
||
|
||
- :cpp:enumerator:`LV_PART_MAIN` The background of the roller uses all the typical
|
||
background properties and text style properties.
|
||
``style_text_line_space`` adjusts the space between the options. When
|
||
the Roller is scrolled and doesn’t stop exactly on an option it will
|
||
scroll to the nearest valid option automatically in ``anim_time``
|
||
milliseconds as specified in the style.
|
||
- :cpp:enumerator:`LV_PART_SELECTED` The selected option in the middle. Besides the
|
||
typical background properties it uses the text style properties to
|
||
change the appearance of the text in the selected area.
|
||
|
||
Usage
|
||
*****
|
||
|
||
Set options
|
||
-----------
|
||
|
||
Options are passed to the Roller as a string with
|
||
:cpp:expr:`lv_roller_set_options(roller, options, LV_ROLLER_MODE_NORMAL)`.
|
||
The options should be separated by ``\n``. For example:
|
||
``"First\nSecond\nThird"``.
|
||
|
||
:cpp:enumerator:`LV_ROLLER_MODE_INFINITE` makes the roller circular.
|
||
|
||
You can select an option manually with
|
||
:cpp:expr:`lv_roller_set_selected(roller, id, LV_ANIM_ON)`,
|
||
where *id* is the index of an option.
|
||
|
||
Get selected option
|
||
-------------------
|
||
|
||
To get the *index* of the currently selected option use :cpp:expr:`lv_roller_get_selected(roller)`.
|
||
|
||
:cpp:expr:`lv_roller_get_selected_str(roller, buf, buf_size)` will copy the name of the selected option to ``buf``.
|
||
|
||
Visible rows
|
||
------------
|
||
|
||
The number of visible rows can be adjusted with :cpp:expr:`lv_roller_set_visible_row_count(roller, num)`.
|
||
|
||
This function calculates the height with the current style. If the font,
|
||
line space, border width, etc. of the roller changes this function needs
|
||
to be called again.
|
||
|
||
Events
|
||
******
|
||
|
||
- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when a new option is selected.
|
||
|
||
See the events of the `Base object </widgets/obj>`__ too.
|
||
|
||
Learn more about :ref:`events`.
|
||
|
||
Keys
|
||
****
|
||
|
||
- ``LV_KEY_RIGHT/DOWN`` Select the next option
|
||
- ``LV_KEY_LEFT/UP`` Select the previous option
|
||
- :cpp:enumerator:`LY_KEY_ENTER` Apply the selected option (Send :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` event)
|
||
|
||
Example
|
||
*******
|
||
|
||
.. include:: ../examples/widgets/roller/index.rst
|
||
|
||
API
|
||
***
|