Embedded/lvgl
1
0
Fork 0
mirror of https://github.com/lvgl/lvgl.git synced 2025-01-14 06:42:58 +08:00
Code Issues Projects Releases Wiki Activity
lvgl/docs/widgets/core/dropdown.md
Gabor Kiss-Vamosi 88c485949f feat(event, widgets) improve the paramter of LV_EVENT_DRAW_PART_BEGIN/END 
Add lv_<widget>_draw_part_type_t to widgets to precisly describe the hooked drawings.
Also add class_p element to lv_obj_draw_part_dsc_t to show what widgets lv_<widget>_draw_part_type_t needs to be used.

Related to: https://forum.lvgl.io/t/how-to-add-minor-division-lines-to-a-chart/5366/
2021-07-07 16:19:06 +02:00

4.5 KiB
Raw Blame History 

.. include:: /header.rst 
:github_url: |github_link_base|/widgets/dropdown.md

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.

Parts and Styles

The Dropdown widget is built from the elements: "button" and "list" (both not related to the button and list widgets)

Button

  • LV_PART_MAIN The background of the button. Uses the typical background properties and text properties for the text on it.
  • LV_PART_INDICATOR Typically an arrow symbol that can be an image or a text (LV_SYMBOL).

The button goes to LV_STATE_CHECKED when its opened.

List

  • LV_PART_MAIN The list itself. Uses the typical background properties. 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 typical background properties.

As list does not exist when the drop-down list is closed it's not possible to simply add styles to it. Instead the following should be done:

  1. Ad an event handler to the button for LV_EVENT_VALUE_CHANGED (triggered when the list is opened/closed)
  2. Use lv_obj_t * list = lv_dropdown_get_list(dropdown)
  3. if(list != NULL) {/*Add the styles to the list*/}

Alternatively the theme can be extended with the new styles.

Usage

Overview

Set options

Options are passed to the drop-down list as a string with 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 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 lv_dropdown_set_static_options(dropdown, options). In this case the options string should be alive while the drop-down list exists and lv_dropdown_add_option can't be used

You can select an option manually with 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 lv_dropdown_get_selected(dropdown).

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 LV_DIR_BOTTOM can be modified by lv_dropdown_set_dir(dropdown, LV_DIR_LEFT/RIGHT/UP/BOTTOM) 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 drop down list with lv_dropdown_set_symbol(dropdown, LV_SYMBOL_...)

If the direction of the drop-down list is 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 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.

Events

Apart from the Generic events, the following Special events are sent by the drop-down list:

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

See the events of the Base object too.

Learn more about Events.

Keys

  • LV_KEY_RIGHT/DOWN Select the next option.
  • LV_KEY_LEFT/UP Select the previous option.
  • LY_KEY_ENTER Apply the selected option (Sends LV_EVENT_VALUE_CHANGED event and closes the drop-down list).

Learn more about Keys.

Example


.. include:: ../../../examples/widgets/dropdown/index.rst

API


.. doxygenfile:: lv_dropdown.h
  :project: lvgl