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(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(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_obj_property_names.h