1.. _lv_roller:
2
3==================
4Roller (lv_roller)
5==================
6
7
8Overview
9********
10
11Roller allows the end user to select an item from a list by scrolling it.
12The item in the middle is the selected item and normally stands out from
13the other items due to different styles applied to it.
14
15
16
17
18.. _lv_roller_parts_and_styles:
19
20Parts and Styles
21****************
22
23-  :cpp:enumerator:`LV_PART_MAIN` The background of the roller uses the :ref:`typical
24   background <typical bg props>` and text style properties.
25
26   - Style ``text_line_space`` adjusts the space between list items.
27     Use :cpp:func:`lv_obj_set_style_text_line_space` to set this value.
28
29   - When the Roller is scrolled and doesn't stop exactly on an item, it will
30     automatically scroll to the nearest valid item in ``anim_time``
31     milliseconds as specified in the ``anim_duration`` style.  Use
32     :cpp:func:`lv_obj_set_style_anim_duration` to set this value.
33
34-  :cpp:enumerator:`LV_PART_SELECTED` The selected item (displayed in the  middle of
35   the Roller).  Besides the typical background properties, it uses text style
36   properties to change the appearance of the text of the selected item.
37
38
39
40.. _lv_roller_usage:
41
42Usage
43*****
44
45Setting the list items
46----------------------
47
48List items are passed to the Roller as a string with
49:cpp:expr:`lv_roller_set_options(roller, string_list, LV_ROLLER_MODE_NORMAL)`.
50The items should be separated by ``\n``. For example:
51``"First\nSecond\nThird"``.
52
53:cpp:enumerator:`LV_ROLLER_MODE_INFINITE` makes the Roller circular.
54
55You can select an option programmatically with
56:cpp:expr:`lv_roller_set_selected(roller, id, LV_ANIM_ON)`,
57where *id* is the zero-based index of the list item to be selected.
58
59If you don't know the index of an option can also select an item with
60:cpp:expr:`lv_roller_set_selected_str(roller, str, LV_ANIM_ON)`,
61where *str* is the string equal to one of the list items.
62
63Get selected option
64-------------------
65
66To get the *index* of the currently selected item use :cpp:expr:`lv_roller_get_selected(roller)`.
67
68:cpp:expr:`lv_roller_get_selected_str(roller, buf, buf_size)` will copy the name of the selected item to ``buf``.
69
70Visible rows
71------------
72
73The number of visible rows can be adjusted with :cpp:expr:`lv_roller_set_visible_row_count(roller, num)`.
74
75This function calculates the height with the current style. If the font,
76line space, border width, etc. of the Roller changes, this function needs
77to be called again.
78
79
80
81.. _lv_roller_events:
82
83Events
84******
85
86-  :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when a new list item is selected.
87
88.. admonition::  Further Reading
89
90    Learn more about :ref:`lv_obj_events` emitted by all Widgets.
91
92    Learn more about :ref:`events`.
93
94
95
96.. _lv_roller_keys:
97
98Keys
99****
100
101-  ``LV_KEY_RIGHT/DOWN`` Select next option
102-  ``LV_KEY_LEFT/UP`` Select previous option
103-  :cpp:enumerator:`LY_KEY_ENTER` Accept the selected option (sends :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` event)
104
105.. admonition::  Further Reading
106
107    Learn more about :ref:`indev_keys`.
108
109
110
111.. _lv_roller_example:
112
113Example
114*******
115
116.. include:: ../../examples/widgets/roller/index.rst
117
118
119
120.. _lv_roller_api:
121
122API
123***
124