1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
|
.. _lv_dropdown:
============================
Drop-down list (lv_dropdown)
============================
Overview
********
The drop-down list allows the user to select one value from a list.
The drop-down list is closed by default and displays a single value or a
predefined text. When activated (by click on the drop-down list), a list
is created from which the user may select one option. When the user
selects a new value, the list is deleted again.
The Drop-down list is added to the default group (if it is set). Besides
the Drop-down list is an editable object to allow selecting an option
with encoder navigation too.
.. _lv_dropdown_parts_and_styles:
Parts and Styles
****************
The Dropdown widget is built from the elements: "button" and "list"
(both not related to the button and list widgets)
Button
------
- :cpp:enumerator:`LV_PART_MAIN` The background of the button. Uses the typical
background properties and text properties for the text on it.
- :cpp:enumerator:`LV_PART_INDICATOR` Typically an arrow symbol that can be an image
or a text (:cpp:enumerator:`LV_SYMBOL`).
The button goes to :cpp:enumerator:`LV_STATE_CHECKED` when it's opened.
List
----
- :cpp:enumerator:`LV_PART_MAIN` The list itself. Uses the typical background
properties. ``max_height`` can be used to limit the height of the
list.
- :cpp:enumerator:`LV_PART_SCROLLBAR` The scrollbar background, border, shadow
properties and width (for its own width) and right padding for the
spacing on the right.
- :cpp:enumerator:`LV_PART_SELECTED` Refers to the currently pressed, checked or
pressed+checked option. Also uses the typical background properties.
The list is hidden/shown on open/close. To add styles to it use
:cpp:expr:`lv_dropdown_get_list(dropdown)` to get the list object. For example:
.. code:: c
lv_obj_t * list = lv_dropdown_get_list(dropdown) /*Get the list*/
lv_obj_add_style(list, &my_style, selector) /*Add the styles to the list*/
Alternatively the theme can be extended with the new styles.
.. _lv_dropdown_usage:
Usage
*****
.. _lv_dropdown_options:
Options
*******
Set options
-----------
Options are passed to the drop-down list as a string with
:cpp:expr:`lv_dropdown_set_options(dropdown, options)`. Options should be
separated by ``\n``. For example: ``"First\nSecond\nThird"``. This
string will be saved in the drop-down list, so it can in a local
variable.
The :cpp:expr:`lv_dropdown_add_option(dropdown, "New option", pos)` function
inserts a new option to ``pos`` index.
To save memory the options can set from a static(constant) string too
with :cpp:expr:`lv_dropdown_set_static_options(dropdown, options)`. In this case
the options string should be alive while the drop-down list exists and
:cpp:func:`lv_dropdown_add_option` can't be used
You can select an option manually with
:cpp:expr:`lv_dropdown_set_selected(dropdown, id)`, where ``id`` is the index of
an option.
Get selected option
-------------------
The get the *index* of the selected option, use
:cpp:expr:`lv_dropdown_get_selected(dropdown)`.
:cpp:expr:`lv_dropdown_get_selected_str(dropdown, buf, buf_size)` copies the
*name* of the selected option to ``buf``.
Direction
---------
The list can be created on any side. The default :cpp:enumerator:`LV_DIR_BOTTOM` can
be modified by :cpp:expr:`lv_dropdown_set_dir(dropdown, LV_DIR_LEFT)` function.
If the list would be vertically out of the screen, it will be aligned to
the edge.
Symbol
------
A symbol (typically an arrow) can be added to the dropdown list with
:cpp:expr:`lv_dropdown_set_symbol(dropdown, LV_SYMBOL_...)`
If the direction of the drop-down list is :cpp:enumerator:`LV_DIR_LEFT` the symbol
will be shown on the left, otherwise on the right.
Show selected
-------------
The main part can either show the selected option or a static text. If a
static is set with :cpp:expr:`lv_dropdown_set_text(dropdown, "Some text")` it
will be shown regardless to th selected option. If the text is ``NULL``
the selected option is displayed on the button.
Manually open/close
-------------------
To manually open or close the drop-down list the
``lv_dropdown_open/close(dropdown)`` function can be used.
.. _lv_dropdown_events:
Events
******
Apart from the `Generic events <../overview/event.html#generic-events>`__, the following
`Special events <../overview/event.html#special-events>`__ are sent by
the drop-down list:
- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when the new option is selected or the list is opened/closed.
- :cpp:enumerator:`LV_EVENT_CANCEL` Sent when the list is closed
- :cpp:enumerator:`LV_EVENT_READY` Sent when the list is opened
See the events of the :ref:`Base object <lv_obj>` too.
Learn more about :ref:`events`.
.. _lv_dropdown_keys:
Keys
****
- ``LV_KEY_RIGHT/DOWN`` Select the next option.
- ``LV_KEY_LEFT/UP`` Select the previous option.
- :cpp:enumerator:`LV_KEY_ENTER` Apply the selected option (Sends
:cpp:enumerator:`LV_EVENT_VALUE_CHANGED` event and closes the drop-down list).
Learn more about :ref:`indev_keys`.
.. _lv_dropdown_example:
Example
*******
.. include:: ../examples/widgets/dropdown/index.rst
.. _lv_dropdown_api:
API
***
|
