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