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