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.

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¶

LV_PART_MAIN Background of button, uses the typical background and text style properties for its text.
LV_PART_INDICATOR Typically an arrow symbol that can be an Image or text (e.g. LV_SYMBOL).

The button goes to LV_STATE_CHECKED when it's opened.

List¶

LV_PART_MAIN The list itself; uses the typical background style 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 style properties.

The list is shown/hidden on open/close. To add styles to it use lv_dropdown_get_list(dropdown) to get the list object. Example:

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.

Usage¶

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 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 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 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 lv_dropdown_add_option() cannot be used.

You can select an option programmatically with 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 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 using 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 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 item or static text. If static is set with 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 lv_dropdown_open(dropdown) or lv_dropdown_close(dropdown).

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.

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).

Example¶

Simple Drop down list¶

#include "../../lv_examples.h"
#if LV_USE_DROPDOWN && LV_BUILD_EXAMPLES

static void event_handler(lv_event_t * e)
{
    lv_event_code_t code = lv_event_get_code(e);
    lv_obj_t * obj = lv_event_get_target_obj(e);
    if(code == LV_EVENT_VALUE_CHANGED) {
        char buf[32];
        lv_dropdown_get_selected_str(obj, buf, sizeof(buf));
        LV_LOG_USER("Option: %s", buf);
    }
}

void lv_example_dropdown_1(void)
{

    /*Create a normal drop down list*/
    lv_obj_t * dd = lv_dropdown_create(lv_screen_active());
    lv_dropdown_set_options(dd, "Apple\n"
                            "Banana\n"
                            "Orange\n"
                            "Cherry\n"
                            "Grape\n"
                            "Raspberry\n"
                            "Melon\n"
                            "Orange\n"
                            "Lemon\n"
                            "Nuts");

    lv_obj_align(dd, LV_ALIGN_TOP_MID, 0, 20);
    lv_obj_add_event_cb(dd, event_handler, LV_EVENT_ALL, NULL);
}


#endif

Drop down in four directions¶

#include "../../lv_examples.h"
#if LV_USE_DROPDOWN && LV_BUILD_EXAMPLES

/**
 * Create a drop down, up, left and right menus
 */
void lv_example_dropdown_2(void)
{
    static const char * opts = "Apple\n"
                               "Banana\n"
                               "Orange\n"
                               "Melon";

    lv_obj_t * dd;
    dd = lv_dropdown_create(lv_screen_active());
    lv_dropdown_set_options_static(dd, opts);
    lv_obj_align(dd, LV_ALIGN_TOP_MID, 0, 10);

    dd = lv_dropdown_create(lv_screen_active());
    lv_dropdown_set_options_static(dd, opts);
    lv_dropdown_set_dir(dd, LV_DIR_BOTTOM);
    lv_dropdown_set_symbol(dd, LV_SYMBOL_UP);
    lv_obj_align(dd, LV_ALIGN_BOTTOM_MID, 0, -10);

    dd = lv_dropdown_create(lv_screen_active());
    lv_dropdown_set_options_static(dd, opts);
    lv_dropdown_set_dir(dd, LV_DIR_RIGHT);
    lv_dropdown_set_symbol(dd, LV_SYMBOL_RIGHT);
    lv_obj_align(dd, LV_ALIGN_LEFT_MID, 10, 0);

    dd = lv_dropdown_create(lv_screen_active());
    lv_dropdown_set_options_static(dd, opts);
    lv_dropdown_set_dir(dd, LV_DIR_LEFT);
    lv_dropdown_set_symbol(dd, LV_SYMBOL_LEFT);
    lv_obj_align(dd, LV_ALIGN_RIGHT_MID, -10, 0);
}

#endif

Menu¶

#include "../../lv_examples.h"
#if LV_USE_DROPDOWN && LV_BUILD_EXAMPLES

static void event_cb(lv_event_t * e)
{
    lv_obj_t * dropdown = lv_event_get_target_obj(e);
    char buf[64];
    lv_dropdown_get_selected_str(dropdown, buf, sizeof(buf));
    LV_LOG_USER("'%s' is selected", buf);
}

/**
 * Create a menu from a drop-down list and show some drop-down list features and styling
 */
void lv_example_dropdown_3(void)
{
    /*Create a drop down list*/
    lv_obj_t * dropdown = lv_dropdown_create(lv_screen_active());
    lv_obj_align(dropdown, LV_ALIGN_TOP_LEFT, 10, 10);
    lv_dropdown_set_options(dropdown, "New project\n"
                            "New file\n"
                            "Save\n"
                            "Save as ...\n"
                            "Open project\n"
                            "Recent projects\n"
                            "Preferences\n"
                            "Exit");

    /*Set a fixed text to display on the button of the drop-down list*/
    lv_dropdown_set_text(dropdown, "Menu");

    /*Use a custom image as down icon and flip it when the list is opened*/
    LV_IMAGE_DECLARE(img_caret_down);
    lv_dropdown_set_symbol(dropdown, &img_caret_down);
    lv_obj_set_style_transform_rotation(dropdown, 1800, LV_PART_INDICATOR | LV_STATE_CHECKED);

    /*In a menu we don't need to show the last clicked item*/
    lv_dropdown_set_selected_highlight(dropdown, false);

    lv_obj_add_event_cb(dropdown, event_cb, LV_EVENT_VALUE_CHANGED, NULL);
}

#endif

API¶

lv_api_map_v8.h

lv_dropdown.h

lv_dropdown_private.h

lv_obj_property_names.h

lv_observer.h