mirror of
https://github.com/lvgl/lvgl.git
synced 2025-01-28 07:03:00 +08:00
181 lines
5.1 KiB
ReStructuredText
181 lines
5.1 KiB
ReStructuredText
.. _lv_dropdown:
|
|
|
|
============================
|
|
Drop-Down List (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).
|
|
|
|
Button
|
|
------
|
|
|
|
- :cpp:enumerator:`LV_PART_MAIN` Background of button, uses the typical
|
|
background- and text-properties for its text.
|
|
- :cpp:enumerator:`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.
|
|
|
|
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 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:
|
|
|
|
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.
|
|
|
|
Get selected 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``.
|
|
|
|
Direction
|
|
---------
|
|
|
|
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.
|
|
|
|
Symbol
|
|
------
|
|
|
|
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.
|
|
|
|
Show selected
|
|
-------------
|
|
|
|
The main part can either show the selected item or static text. If
|
|
static is set with :cpp:expr:`lv_dropdown_set_text(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.
|
|
|
|
Programmatically open/close
|
|
---------------------------
|
|
|
|
To programmatically open or close the Drop-Down List use
|
|
:cpp:expr:`lv_dropdown_open(dropdown)` or :cpp:expr:`lv_dropdown_close(dropdown)`.
|
|
|
|
|
|
|
|
.. _lv_dropdown_events:
|
|
|
|
Events
|
|
******
|
|
|
|
- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when a new option is selected or the list is opened/closed.
|
|
- :cpp:enumerator:`LV_EVENT_CANCEL` Sent when list is closed.
|
|
- :cpp:enumerator:`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.
|
|
- :cpp:enumerator:`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:
|
|
|
|
Example
|
|
*******
|
|
|
|
.. include:: ../../examples/widgets/dropdown/index.rst
|
|
|
|
|
|
|
|
.. _lv_dropdown_api:
|
|
|
|
API
|
|
***
|