1.. _lv_dropdown: 2 3============================ 4Drop-Down List (lv_dropdown) 5============================ 6 7Overview 8******** 9 10The Drop-Down List allows the user to select a value from a list. 11 12The Drop-Down List is closed by default and displays a single value or 13predefined text. When activated (by click on the Drop-Down List), a list 14is created from which the user may select one item. When the user 15selects a new value, the list is deleted again. 16 17The Drop-down list is added to the default group (if one is set). 18The Drop-down list is an editable Widget allowing list-item selection via 19encoder or keyboard navigation as well. 20 21 22.. _lv_dropdown_parts_and_styles: 23 24Parts and Styles 25**************** 26 27The Drop-Down List Widget is built from the elements: "button" and "list" 28(lightweight versions of the Button and List Widgets). 29 30Button 31------ 32 33- :cpp:enumerator:`LV_PART_MAIN` Background of button, uses the :ref:`typical 34 background <typical bg props>` and text style properties for its text. 35- :cpp:enumerator:`LV_PART_INDICATOR` Typically an arrow symbol that can be an Image 36 or text (e.g. :cpp:enumerator:`LV_SYMBOL`). 37 38The button goes to :cpp:enumerator:`LV_STATE_CHECKED` when it's opened. 39 40List 41---- 42 43- :cpp:enumerator:`LV_PART_MAIN` The list itself; uses the :ref:`typical background 44 style properties <typical bg props>`. ``max_height`` can be used to limit the 45 height of the list. 46- :cpp:enumerator:`LV_PART_SCROLLBAR` The scrollbar background, border, shadow 47 properties and width (for its own width) and right padding for the 48 spacing on the right. 49- :cpp:enumerator:`LV_PART_SELECTED` Refers to the currently pressed, checked or 50 pressed+checked option. Also uses the :ref:`typical background style properties 51 <typical bg props>`. 52 53The list is shown/hidden on open/close. To add styles to it use 54:cpp:expr:`lv_dropdown_get_list(dropdown)` to get the list object. Example: 55 56.. code-block:: c 57 58 lv_obj_t * list = lv_dropdown_get_list(dropdown) /* Get list */ 59 lv_obj_add_style(list, &my_style, selector) /* Add styles to list */ 60 61Alternatively the theme can be extended with new styles. 62 63 64.. _lv_dropdown_usage: 65 66Usage 67***** 68 69 70.. _lv_dropdown_list_items: 71 72List items 73---------- 74 75The list items are passed to the Drop-Down List as a newline-separated list in a string 76as the ``options`` argument to :cpp:expr:`lv_dropdown_set_options(dropdown, options)`. 77Each list item should be separated by ``\n``. Example: ``"First\nSecond\nThird"``. 78This string is copied by the Drop-Down List, so its contents do not need to remain 79available beyond this call. 80 81The :cpp:expr:`lv_dropdown_add_option(dropdown, "New option", pos)` function 82inserts a new option at index ``pos``. 83 84To save memory the options can be set from a static (const) string as well 85with :cpp:expr:`lv_dropdown_set_options_static(dropdown, options)`. In this case 86the options string's contents must remain available for the life of the Drop-Down 87List and :cpp:func:`lv_dropdown_add_option` cannot be used. 88 89You can select an option programmatically with 90:cpp:expr:`lv_dropdown_set_selected(dropdown, id, LV_ANIM_ON/LV_ANIM_OFF)`, where ``id`` is the index of 91the target option. 92 93Get selected option 94------------------- 95 96To get the *index* of the selected option, use 97:cpp:expr:`lv_dropdown_get_selected(dropdown)`. 98 99:cpp:expr:`lv_dropdown_get_selected_str(dropdown, buf, buf_size)` copies the 100*name* of the selected option to ``buf``. 101 102Direction 103--------- 104 105The list can be created on any side. The default :cpp:enumerator:`LV_DIR_BOTTOM` can 106be modified using :cpp:expr:`lv_dropdown_set_dir(dropdown, LV_DIR_LEFT)`. 107 108If the list would be vertically out of the screen, it will be aligned to 109the edge. 110 111Symbol 112------ 113 114A symbol (typically an arrow) can be added to the Drop-Down List with 115:cpp:expr:`lv_dropdown_set_symbol(dropdown, LV_SYMBOL_...)` 116 117If the direction of the Drop-Down List is :cpp:enumerator:`LV_DIR_LEFT` the symbol 118will be shown on the left, otherwise on the right. 119 120Show selected 121------------- 122 123The main part can either show the selected item or static text. If 124static is set with :cpp:expr:`lv_dropdown_set_text(dropdown, "Some text")` it 125will be shown regardless of the selected item. If the text is ``NULL`` 126the selected option is displayed on the button. 127 128Programmatically open/close 129--------------------------- 130 131To programmatically open or close the Drop-Down List use 132:cpp:expr:`lv_dropdown_open(dropdown)` or :cpp:expr:`lv_dropdown_close(dropdown)`. 133 134 135 136.. _lv_dropdown_events: 137 138Events 139****** 140 141- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when a new option is selected or the list is opened/closed. 142- :cpp:enumerator:`LV_EVENT_CANCEL` Sent when list is closed. 143- :cpp:enumerator:`LV_EVENT_READY` Sent when list is opened. 144 145.. admonition:: Further Reading 146 147 Learn more about :ref:`lv_obj_events` emitted by all Widgets. 148 149 Learn more about :ref:`events`. 150 151 152 153.. _lv_dropdown_keys: 154 155Keys 156**** 157 158- ``LV_KEY_RIGHT/DOWN`` Select next list item. 159- ``LV_KEY_LEFT/UP`` Select previous list item. 160- :cpp:enumerator:`LV_KEY_ENTER` Apply selected list item (sends 161 :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` event and closes Drop-Down List). 162 163.. admonition:: Further Reading 164 165 Learn more about :ref:`indev_keys`. 166 167 168 169.. _lv_dropdown_example: 170 171Example 172******* 173 174.. include:: ../../examples/widgets/dropdown/index.rst 175 176 177 178.. _lv_dropdown_api: 179 180API 181*** 182