Drop-Down List (lv_dropdown)

Let the user pick a value from a list that opens on click and closes after the choice.

Overview

A Drop-Down List lets the user pick a value from a list.

It is closed by default and shows a single value or a fixed label. When the user clicks it, the list opens; after a pick, the list closes again.

A Drop-Down is added to the default group (if one is set). It is an editable widget — items can also be selected with an encoder or a keyboard.

List items

lv_dropdown_set_options(dd, "First\nSecond\nThird") — items separated by \n. The string is copied. Use _set_options_static to skip the copy when the string lives in flash (cannot be combined with _add_option). lv_dropdown_add_option(dd, "New", pos) inserts at index pos. lv_dropdown_set_selected(dd, id) picks the active option by index.

Get selected option

• lv_dropdown_get_selected(dd) returns the index.
• lv_dropdown_get_selected_str(dd, buf, size) copies the option text into buf.

Direction

lv_dropdown_set_dir(dd, LV_DIR_…) chooses which side the list opens toward (default LV_DIR_BOTTOM). Lists that would fall off the screen are clamped to the edge automatically.

Symbol

Add an indicator glyph (typically an arrow) with lv_dropdown_set_symbol. It's rendered on the right by default; on the left when direction is LV_DIR_LEFT.

lv_dropdown_set_symbol(dropdown, LV_SYMBOL_DOWN);

Show selected

By default the button shows the selected option. Set a fixed label with lv_dropdown_set_text(dd, "Menu") (or _set_text_static) and the button shows that string regardless of selection. Pass NULL to revert.

Set translation tag

When using LVGL's translation module, you can bind a translation tag to a drop-down list directly. After binding, future changes to the language will automatically update the bound text or options to display the corresponding translation for that tag in the new language.

• lv_dropdown_set_text_translation_tag(dd, tag) binds the button's fixed text (see Show selected).
• lv_dropdown_set_options_translation_tag(dd, tag) binds the options. The translation should contain the options in a \n separated list, e.g. "One\nTwo\nThree".

Calling any of the regular lv_dropdown_set_text…/lv_dropdown_set_options… functions (or lv_dropdown_add_option/lv_dropdown_clear_options) afterwards removes the binding.

Programmatically open/close

lv_dropdown_open(dd) and lv_dropdown_close(dd).

Styling

The widget has two parts: the button (opens the list when clicked) and the list (shown while open). Each part has its own selectors:

Button

• LV_PART_MAIN — background + text of the closed button. Picks up LV_STATE_CHECKED while the list is open.
• LV_PART_INDICATOR — the symbol set with lv_dropdown_set_symbol.

List (accessed via lv_dropdown_get_list(dd))

• LV_PART_MAIN — list background. max_height caps the open list size.
• LV_PART_SCROLLBAR — scrollbar.
• LV_PART_SELECTED — the highlighted/pressed option:
  • LV_STATE_CHECKED — used for the currently active option
  • LV_STATE_PRESSED — used for the option is being pressed by touch or the Enter key is being pressed

To restyle the list, just get it, and add a style:

lv_obj_t * list = lv_dropdown_get_list(dd);
lv_obj_add_style(list, &my_style, LV_PART_SELECTED);

Data binding

Data bindings connect a widget property to a piece of global data — a Subject. When the subject's value changes, every widget bound to it updates automatically; and an interactive widget can write back into the subject so other subscribers see the new value.

A Drop-Down binds its selected index to a Subject. The link is two-way: picking an option updates the subject, and an application-side write into the subject moves the selection. Only integer subjects are supported.

• lv_dropdown_bind_value(dropdown, subject)

To show the value live in a label next to the widget, attach a label and call lv_label_bind_text(label, subject, "%d") — the format string accepts any printf-style specifier (XML: bind_text + bind_text-fmt).

Events

• LV_EVENT_VALUE_CHANGED Sent when a new option is selected or the list is opened/closed.
• LV_EVENT_CANCEL Sent when list is closed.
• LV_EVENT_READY Sent when list is opened.

Learn more about Events emitted by all Widgets.

Keys

• LV_KEY_RIGHT/DOWN Select next list item.
• LV_KEY_LEFT/UP Select previous list item.
• LV_KEY_ENTER Apply selected list item (sends LV_EVENT_VALUE_CHANGED event and closes Drop-Down List).

Learn more about Keys.