feat(docs): reorganize docs (#7136)
This commit is contained in:
Victor Wheeler
180
docs/details/widgets/dropdown.rst
Normal file
180
docs/details/widgets/dropdown.rst
Normal file
@@ -0,0 +1,180 @@
|
||||
.. _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 Widget to allow selecting an option
|
||||
with encoder navigation as well.
|
||||
|
||||
.. _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 Widget. For example:
|
||||
|
||||
.. code-block:: 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 as well
|
||||
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
|
||||
******
|
||||
|
||||
- :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
|
||||
|
||||
.. 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 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).
|
||||
|
||||
.. admonition:: Further Reading
|
||||
|
||||
Learn more about :ref:`indev_keys`.
|
||||
|
||||
|
||||
|
||||
.. _lv_dropdown_example:
|
||||
|
||||
Example
|
||||
*******
|
||||
|
||||
.. include:: ../../examples/widgets/dropdown/index.rst
|
||||
|
||||
|
||||
|
||||
.. _lv_dropdown_api:
|
||||
|
||||
API
|
||||
***
|
||||
Reference in New Issue
Block a user