docs/src/widgets/dropdown.rst
.. _lv_dropdown:
Overview
The Drop-Down List allows the user to select a value from a list.
The Drop-Down List is closed by default and displays a single value or predefined text. When activated (by click on the Drop-Down List), a list is created from which the user may select one item. When the user selects a new value, the list is deleted again.
The Drop-down list is added to the default group (if one is set). The Drop-down list is an editable Widget allowing list-item selection via encoder or keyboard navigation as well.
.. _lv_dropdown_parts_and_styles:
Parts and Styles
The Drop-Down List Widget is built from the elements: "button" and "list" (lightweight versions of the Button and List Widgets).
LV_PART_MAIN Background of button, uses the :ref:typical background <typical bg props> and text style properties for its text.LV_PART_INDICATOR Typically an arrow symbol that can be an Image
or text (e.g. :cpp:enumerator:LV_SYMBOL).The button goes to :cpp:enumerator:LV_STATE_CHECKED when it's opened.
LV_PART_MAIN The list itself; uses the :ref:typical background style properties <typical bg props>. max_height can be used to limit the
height of the list.LV_PART_SCROLLBAR The scrollbar background, border, shadow
properties and width (for its own width) and right padding for the
spacing on the right.LV_PART_SELECTED Refers to the currently pressed, checked or
pressed+checked option. Also uses the :ref:typical background style properties <typical bg props>.The list is shown/hidden on open/close. To add styles to it use
:cpp:expr:lv_dropdown_get_list(dropdown) to get the list object. Example:
.. code-block:: c
lv_obj_t * list = lv_dropdown_get_list(dropdown) /* Get list / lv_obj_add_style(list, &my_style, selector) / Add styles to list */
Alternatively the theme can be extended with new styles.
.. _lv_dropdown_usage:
Usage
.. _lv_dropdown_list_items:
The list items are passed to the Drop-Down List as a newline-separated list in a string
as the options argument to :cpp:expr:lv_dropdown_set_options(dropdown, options).
Each list item should be separated by \n. Example: "First\nSecond\nThird".
This string is copied by the Drop-Down List, so its contents do not need to remain
available beyond this call.
The :cpp:expr:lv_dropdown_add_option(dropdown, "New option", pos) function
inserts a new option at index pos.
To save memory the options can be set from a static (const) string as well
with :cpp:expr:lv_dropdown_set_options_static(dropdown, options). In this case
the options string's contents must remain available for the life of the Drop-Down
List and :cpp:func:lv_dropdown_add_option cannot be used.
You can select an option programmatically with
:cpp:expr:lv_dropdown_set_selected(dropdown, id), where id is the index of
the target option.
To 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.
The list can be created on any side. The default :cpp:enumerator:LV_DIR_BOTTOM can
be modified using :cpp:expr:lv_dropdown_set_dir(dropdown, LV_DIR_LEFT).
If the list would be vertically out of the screen, it will be aligned to the edge.
A symbol (typically an arrow) can be added to the Drop-Down 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.
The main part can either show the selected item or fixed text. If
fixed text is set with :cpp:expr:lv_dropdown_set_text(dropdown, "Some text")
or :cpp:expr:lv_dropdown_set_text_static(dropdown, "Some text") it
will be shown regardless of the selected item. If the text is NULL
the selected option is displayed on the button.
To programmatically open or close the Drop-Down List use
:cpp:expr:lv_dropdown_open(dropdown) or :cpp:expr:lv_dropdown_close(dropdown).
To get familiar with observers, subjects, and data bindings in general visit the
:ref:Observer <observer_how_to_use> page.
This method of subscribing to an integer Subject affects a Drop-Down Widget's integer value directly. Note that this is a two-way binding (Subject <===> Widget) so an end user's direct interaction with the Drop-Down Widget updates the Subject's value and vice versa.
It support only integer Subjects.
lv_dropdown_bind_value(dropdown, &subject).. _lv_dropdown_events:
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... admonition:: Further Reading
Learn more about :ref:`lv_obj_events` emitted by all Widgets.
Learn more about :ref:`events`.
.. _lv_dropdown_keys:
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
:cpp:enumerator:LV_EVENT_VALUE_CHANGED event and closes Drop-Down List)... admonition:: Further Reading
Learn more about :ref:`indev_keys`.
.. _lv_dropdown_example:
Examples
.. include:: /examples/widgets/dropdown/index.rst
.. _lv_dropdown_api:
API