下拉列表 (lv_dropdown)¶

概述¶

下拉列表允许用户从列表中选择一个值。

下拉列表默认是关闭的，仅显示一个值或预定义的文本。当激活时（通过点击下拉列表），会创建一个列表，用户可以从中选择一个选项。当用户选择新值时，列表会再次删除。

下拉列表会添加到默认组（如果已设置）。此外，下拉列表是一个可编辑对象，允许通过编码器导航选择选项。

部件和样式¶

下拉列表小部件由“按钮”和“列表”元素组成（两者与按钮和列表小部件无关）。

按钮¶

LV_PART_MAIN 按钮的背景。使用典型的背景属性和文本属性显示其上的文本。
LV_PART_INDICATOR 通常是一个箭头符号，可以是图像或文本（LV_SYMBOL）。

按钮在打开时进入 LV_STATE_CHECKED 状态。

列表¶

LV_PART_MAIN 列表本身。使用典型的背景属性。max_height 可用于限制列表的高度。
LV_PART_SCROLLBAR 滚动条的背景、边框、阴影属性和宽度（用于其自身宽度）以及右侧间距。
LV_PART_SELECTED 指当前按下、选中或按下+选中的选项。也使用典型的背景属性。

列表在打开/关闭时隐藏/显示。要为其添加样式，请使用 lv_dropdown_get_list(dropdown) 获取列表对象。例如：

lv_obj_t * list = lv_dropdown_get_list(dropdown) /*获取列表*/
lv_obj_add_style(list, &my_style, ...)           /*为列表添加样式*/

或者，可以通过扩展主题添加新样式。

用法¶

设置选项¶

选项通过字符串传递给下拉列表，使用 lv_dropdown_set_options(dropdown, options)。选项应以 \n 分隔。例如："First\nSecond\nThird"。此字符串将保存在下拉列表中，因此可以是局部变量。

lv_dropdown_add_option(dropdown, "New option", pos) 函数将新选项插入到 pos 索引。

为了节省内存，选项也可以通过静态（常量）字符串设置，使用 lv_dropdown_set_static_options(dropdown, options)。在这种情况下，选项字符串在下拉列表存在期间应保持有效，并且不能使用 lv_dropdown_add_option。

可以通过 lv_dropdown_set_selected(dropdown, id) 手动选择一个选项，其中 id 是选项的索引。

获取选中选项¶

要获取选中选项的索引，使用 lv_dropdown_get_selected(dropdown)。

lv_dropdown_get_selected_str(dropdown, buf, buf_size) 将选中选项的名称复制到 buf。

方向¶

列表可以在任意一侧创建。默认的 LV_DIR_BOTTOM 可以通过 lv_dropdown_set_dir(dropdown, LV_DIR_LEFT/RIGHT/UP/BOTTOM) 函数修改。

如果列表在垂直方向上超出屏幕，它将对齐到边缘。

符号¶

可以通过 lv_dropdown_set_symbol(dropdown, LV_SYMBOL_...) 为下拉列表添加一个符号（通常是一个箭头）。

如果下拉列表的方向为 LV_DIR_LEFT，符号将显示在左侧，否则显示在右侧。

显示选中项¶

主部分可以显示选中选项或静态文本。如果通过 lv_dropdown_set_text(dropdown, "Some text") 设置静态文本，则无论选中选项如何，都会显示该文本。如果文本为 NULL，则在按钮上显示选中选项。

手动打开/关闭¶

可以使用 lv_dropdown_open/close(dropdown) 函数手动打开或关闭下拉列表。

事件¶

除了通用事件，下拉列表还发送以下特殊事件：

LV_EVENT_VALUE_CHANGED 当选择新选项或列表打开/关闭时发送。
LV_EVENT_CANCEL 当列表关闭时发送。
LV_EVENT_READY 当列表打开时发送。

请参阅基础对象的事件。

了解更多关于事件的信息。

按键¶

LV_KEY_RIGHT/DOWN 选择下一个选项。
LV_KEY_LEFT/UP 选择上一个选项。
LY_KEY_ENTER 应用选中选项（发送 LV_EVENT_VALUE_CHANGED 事件并关闭下拉列表）。

了解更多关于按键的信息。

示例¶

简单的下拉列表¶

#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_scr_act());
    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

def event_handler(e):
    code = e.get_code()
    obj = e.get_target()
    if code == lv.EVENT.VALUE_CHANGED:
        option = " "*10 # should be large enough to store the option
        obj.get_selected_str(option, len(option))
        # .strip() removes trailing spaces
        print("Option: \"%s\"" % option.strip())

# Create a normal drop down list
dd = lv.dropdown(lv.scr_act())
dd.set_options("\n".join([
    "Apple",
    "Banana",
    "Orange",
    "Cherry",
    "Grape",
    "Raspberry",
    "Melon",
    "Orange",
    "Lemon",
    "Nuts"]))

dd.align(lv.ALIGN.TOP_MID, 0, 20)
dd.add_event_cb(event_handler, lv.EVENT.ALL, None)

四个方向的下拉¶

#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_scr_act());
    lv_dropdown_set_options_static(dd, opts);
    lv_obj_align(dd, LV_ALIGN_TOP_MID, 0, 10);

    dd = lv_dropdown_create(lv_scr_act());
    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_scr_act());
    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_scr_act());
    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

#
# Create a drop down, up, left and right menus
#

opts = "\n".join([
    "Apple",
    "Banana",
    "Orange",
    "Melon",
    "Grape",
    "Raspberry"])

dd = lv.dropdown(lv.scr_act())
dd.set_options_static(opts)
dd.align(lv.ALIGN.TOP_MID, 0, 10)
dd = lv.dropdown(lv.scr_act())
dd.set_options_static(opts)
dd.set_dir(lv.DIR.BOTTOM)
dd.set_symbol(lv.SYMBOL.UP)
dd.align(lv.ALIGN.BOTTOM_MID, 0, -10)

dd = lv.dropdown(lv.scr_act())
dd.set_options_static(opts)
dd.set_dir(lv.DIR.RIGHT)
dd.set_symbol(lv.SYMBOL.RIGHT)
dd.align(lv.ALIGN.LEFT_MID, 10, 0)

dd = lv.dropdown(lv.scr_act())
dd.set_options_static(opts)
dd.set_dir(lv.DIR.LEFT)
dd.set_symbol(lv.SYMBOL.LEFT)
dd.align(lv.ALIGN.RIGHT_MID, -10, 0)

菜单¶

#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_scr_act());
    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_IMG_DECLARE(img_caret_down)
    lv_dropdown_set_symbol(dropdown, &img_caret_down);
    lv_obj_set_style_transform_angle(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

from imagetools import get_png_info, open_png

# Register PNG image decoder
decoder = lv.img.decoder_create()
decoder.info_cb = get_png_info
decoder.open_cb = open_png

# Create an image from the png file
try:
    with open('../../assets/img_caret_down.png','rb') as f:
        png_data = f.read()
except:
    print("Could not find img_caret_down.png")
    sys.exit()

img_caret_down_argb = lv.img_dsc_t({
  'data_size': len(png_data),
  'data': png_data
})

def event_cb(e):
    dropdown = e.get_target()
    option = " "*64 # should be large enough to store the option
    dropdown.get_selected_str(option, len(option))
    print(option.strip() +" is selected")
#
# Create a menu from a drop-down list and show some drop-down list features and styling
#

# Create a drop down list
dropdown = lv.dropdown(lv.scr_act())
dropdown.align(lv.ALIGN.TOP_LEFT, 10, 10)
dropdown.set_options("\n".join([
    "New project",
    "New file",
    "Open project",
    "Recent projects",
    "Preferences",
    "Exit"]))

# Set a fixed text to display on the button of the drop-down list
dropdown.set_text("Menu")

# Use a custom image as down icon and flip it when the list is opened
# LV_IMG_DECLARE(img_caret_down)
dropdown.set_symbol(img_caret_down_argb)
dropdown.set_style_transform_angle(1800, lv.PART.INDICATOR | lv.STATE.CHECKED)

# In a menu we don't need to show the last clicked item
dropdown.set_selected_highlight(False)

dropdown.add_event_cb(event_cb, lv.EVENT.VALUE_CHANGED, None)

API¶

Functions

LV_EXPORT_CONST_INT(LV_DROPDOWN_POS_LAST)¶

lv_obj_t *lv_dropdown_create(lv_obj_t *parent)¶

Create a drop-down list object

Parameters: parent -- pointer to an object, it will be the parent of the new drop-down list
Returns: pointer to the created drop-down list

void lv_dropdown_set_text(lv_obj_t *obj, const char *txt)¶

Set text of the drop-down list's button. If set to NULL the selected option's text will be displayed on the button. If set to a specific text then that text will be shown regardless of the selected option.

Parameters

obj -- pointer to a drop-down list object
txt -- the text as a string (Only its pointer is saved)

void lv_dropdown_set_options(lv_obj_t *obj, const char *options)¶

Set the options in a drop-down list from a string. The options will be copied and saved in the object so the options can be destroyed after calling this function

Parameters

obj -- pointer to drop-down list object
options --
a string with '

' separated options. E.g. "One\nTwo\nThree"

void lv_dropdown_set_options_static(lv_obj_t *obj, const char *options)¶

Set the options in a drop-down list from a static string (global, static or dynamically allocated). Only the pointer of the option string will be saved.

Parameters

obj -- pointer to drop-down list object
options --
a static string with '

' separated options. E.g. "One\nTwo\nThree"

void lv_dropdown_add_option(lv_obj_t *obj, const char *option, uint32_t pos)¶

Add an options to a drop-down list from a string. Only works for non-static options.

Parameters

obj -- pointer to drop-down list object
option --
a string without '

'. E.g. "Four"
pos -- the insert position, indexed from 0, LV_DROPDOWN_POS_LAST = end of string

void lv_dropdown_clear_options(lv_obj_t *obj)¶

Clear all options in a drop-down list. Works with both static and dynamic options.

Parameters: obj -- pointer to drop-down list object

void lv_dropdown_set_selected(lv_obj_t *obj, uint16_t sel_opt)¶

Set the selected option

Parameters

obj -- pointer to drop-down list object
sel_opt -- id of the selected option (0 ... number of option - 1);

void lv_dropdown_set_dir(lv_obj_t *obj, lv_dir_t dir)¶

Set the direction of the a drop-down list

Parameters

obj -- pointer to a drop-down list object
dir -- LV_DIR_LEFT/RIGHT/TOP/BOTTOM

void lv_dropdown_set_symbol(lv_obj_t *obj, const void *symbol)¶

Set an arrow or other symbol to display when on drop-down list's button. Typically a down caret or arrow.

Note

angle and zoom transformation can be applied if the symbol is an image. E.g. when drop down is checked (opened) rotate the symbol by 180 degree

Parameters

obj -- pointer to drop-down list object
symbol -- a text like LV_SYMBOL_DOWN, an image (pointer or path) or NULL to not draw symbol icon

void lv_dropdown_set_selected_highlight(lv_obj_t *obj, bool en)¶

Set whether the selected option in the list should be highlighted or not

Parameters

obj -- pointer to drop-down list object
en -- true: highlight enabled; false: disabled

lv_obj_t *lv_dropdown_get_list(lv_obj_t *obj)¶

Get the list of a drop-down to allow styling or other modifications

Parameters: obj -- pointer to a drop-down list object
Returns: pointer to the list of the drop-down

const char *lv_dropdown_get_text(lv_obj_t *obj)¶

Get text of the drop-down list's button.

Parameters: obj -- pointer to a drop-down list object
Returns: the text as string, NULL if no text

const char *lv_dropdown_get_options(const lv_obj_t *obj)¶

Get the options of a drop-down list

Parameters

obj -- pointer to drop-down list object

Returns

the options separated by '

'-s (E.g. "Option1\nOption2\nOption3")

uint16_t lv_dropdown_get_selected(const lv_obj_t *obj)¶

Get the index of the selected option

Parameters: obj -- pointer to drop-down list object
Returns: index of the selected option (0 ... number of option - 1);

uint16_t lv_dropdown_get_option_cnt(const lv_obj_t *obj)¶

Get the total number of options

Parameters: obj -- pointer to drop-down list object
Returns: the total number of options in the list

void lv_dropdown_get_selected_str(const lv_obj_t *obj, char *buf, uint32_t buf_size)¶

Get the current selected option as a string

Parameters

obj -- pointer to drop-down object
buf -- pointer to an array to store the string
buf_size -- size of buf in bytes. 0: to ignore it.

int32_t lv_dropdown_get_option_index(lv_obj_t *obj, const char *option)¶

Get the index of an option.

Parameters

obj -- pointer to drop-down object
option -- an option as string

Returns

index of option in the list of all options. -1 if not found.

const char *lv_dropdown_get_symbol(lv_obj_t *obj)¶

Get the symbol on the drop-down list. Typically a down caret or arrow.

Parameters: obj -- pointer to drop-down list object
Returns: the symbol or NULL if not enabled

bool lv_dropdown_get_selected_highlight(lv_obj_t *obj)¶

Get whether the selected option in the list should be highlighted or not

Parameters: obj -- pointer to drop-down list object
Returns: true: highlight enabled; false: disabled

lv_dir_t lv_dropdown_get_dir(const lv_obj_t *obj)¶

Get the direction of the drop-down list

Parameters: obj -- pointer to a drop-down list object
Returns: LV_DIR_LEF/RIGHT/TOP/BOTTOM

void lv_dropdown_open(lv_obj_t *dropdown_obj)¶

Open the drop.down list

Parameters: obj -- pointer to drop-down list object

void lv_dropdown_close(lv_obj_t *obj)¶

Close (Collapse) the drop-down list

Parameters: obj -- pointer to drop-down list object

bool lv_dropdown_is_open(lv_obj_t *obj)¶

Tells whether the list is opened or not

Parameters: obj -- pointer to a drop-down list object
Returns: true if the list os opened

Variables

const lv_obj_class_t lv_dropdown_class¶

const lv_obj_class_t lv_dropdownlist_class¶

struct lv_dropdown_t¶

Public Members

lv_obj_t obj¶

lv_obj_t *list¶: The dropped down list

const char *text¶: Text to display on the dropdown's button

const void *symbol¶: Arrow or other icon when the drop-down list is closed

char *options¶

Options in a '

' separated list

uint16_t option_cnt¶: Number of options

uint16_t sel_opt_id¶: Index of the currently selected option

uint16_t sel_opt_id_orig¶: Store the original index on focus

uint16_t pr_opt_id¶: Index of the currently pressed option

lv_dir_t dir¶: Direction in which the list should open

uint8_t static_txt¶: 1: Only a pointer is saved in options

uint8_t selected_highlight¶: 1: Make the selected option highlighted in the list

struct lv_dropdown_list_t¶

Public Members

lv_obj_t obj¶

lv_obj_t *dropdown¶