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.

• LV_PART_MAIN 按钮的背景。 对其上面的文本使用典型的背景属性和文本属性。

• LV_PART_INDICATOR 通常是一个箭头符号，可以是图像或文本（LV_SYMBOL...）。

按钮在打开时，会设置为 “LV_STATE_CHECKED” 状态。

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.

• LV_PART_MAIN 列表本身。 使用典型的背景属性。可通过设置 max_height 限制列表的高度。

• LV_PART_SCROLLBAR 列表滚动条的背景、边框、阴影属性和宽度（对于它自己的宽度）以及右侧间距的右侧填充。

• LV_PART_SELECTED 指的是当前按下、选中或按下+选中的选项。 也是使用典型的背景属性。

由于下拉列表关闭时列表不存在，因此无法简单地向其添加样式。 我们可以通过下面的方法实现：

1. 当在列表打开/关闭时会触发 LV_EVENT_VALUE_CHANGED 事件类型

2. 在事件处理回调函数中这样就获取到列表的指针 lv_obj_t * list = lv_dropdown_get_list(dropdown)

3. 添加样式： if(list != NULL) {/*将样式添加到列表中*/}

或者，可以使用自定义新样式扩展主题。

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.

可以通过这个函数 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 是一个选项的索引，选项从 0 开始索引。

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.

要获取所选中的选项的索引(index) ，可以使用 lv_dropdown_get_selected(dropdown);。

lv_dropdown_get_selected_str(dropdown, buf, buf_size); 将所选选项的 name 复制到 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.

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

如果列表展开会超出屏幕，他会自动进行调整。

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.

可以使用 lv_dropdown_set_symbol(dropdown, LV_SYMBOL_...) 将符号（通常是箭头）添加到下拉列表中

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

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.

主要部分(LV_PART_MAIN)可以显示所选选项或静态文本。 如果使用 lv_dropdown_set_text(dropdown, "Some text"); 设置内容，那么无论选择哪个选项，它都会只会显示你所设置的内容。 如果文本为“NULL”，则所当前选选项将显示在按钮上。

Manually open/close（手动打开/关闭）

查看原文

To manually open or close the drop-down list the lv_dropdown_open/close(dropdown) function can be used.

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

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.

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

• LV_EVENT_VALUE_CHANGED 在选择新选项或打开/关闭列表时发送。

可以参考 Base object 的事件。

详细了解 事件。

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.

• LV_KEY_RIGHT/DOWN 选择下一个选项。

• LV_KEY_LEFT/UP 选择上一个选项。

• LY_KEY_ENTER 应用选择的选项（发送 LV_EVENT_VALUE_CHANGED 事件并关闭下拉列表）。

了解有关 Keys 的更多信息。

Example

Simple Drop down list

C code  

 GitHub

#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

MicroPython code  

 GitHub Simulator

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)

---

Drop down in four directions

C code  

 GitHub

#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

MicroPython code  

 GitHub Simulator

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

---

Menu

C code  

 GitHub

#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

MicroPython code  

 GitHub Simulator

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

参数

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

返回

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.

参数

• 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

参数

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

参数

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

参数

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

参数

obj -- pointer to drop-down list object

void lv_dropdown_set_selected(lv_obj_t *obj, uint16_t sel_opt)

Set the selected option

参数

• 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

参数

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

注解

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

参数

• 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

参数

• 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

参数

obj -- pointer to a drop-down list object

返回

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.

参数

obj -- pointer to a drop-down list object

返回

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

参数

obj -- pointer to drop-down list object

返回

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

参数

obj -- pointer to drop-down list object

返回

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

参数

obj -- pointer to drop-down list object

返回

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

参数

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

const char *lv_dropdown_get_symbol(lv_obj_t *obj)

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

参数

obj -- pointer to drop-down list object

返回

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

参数

obj -- pointer to drop-down list object

返回

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

参数

obj -- pointer to a drop-down list object

返回

LV_DIR_LEF/RIGHT/TOP/BOTTOM

void lv_dropdown_open(lv_obj_t *dropdown_obj)

Open the drop.down list

参数

obj -- pointer to drop-down list object

void lv_dropdown_close(lv_obj_t *obj)

Close (Collapse) the drop-down list

参数

obj -- pointer to drop-down list object

bool lv_dropdown_is_open(lv_obj_t *obj)

Tells whether the list is opened or not

参数

obj -- pointer to a drop-down list object

返回

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