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 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 Dropdown widget is built from the elements: "button" and "list" (both not related to the button and list widgets)
下拉组件由以下元素组成：“按钮”和“列表”（都与按钮和列表控件无关，也就是并不是按钮和列表控件）
List（列表）
显示原文
LV_PART_MAINThe list itself. Uses the typical background properties.max_heightcan be used to limit the height of the list.LV_PART_SCROLLBARThe scrollbar background, border, shadow properties and width (for its own width) and right padding for the spacing on the right.LV_PART_SELECTEDRefers to the currently pressed, checked or pressed+checked option. Also uses the typical background properties.
The list is hidden/shown on open/close. To add styles to it use lv_dropdown_get_list(dropdown) to get the list object. For example:
lv_obj_t * list = lv_dropdown_get_list(dropdown) /*Get the list*/
lv_obj_add_style(list, &my_style, selector) /*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指的是当前按下、选中或按下+选中的选项。 也是使用典型的背景属性。
列表在打开或关闭时会隐藏或显示。若要向其添加样式，请使用 lv_dropdown_get_list(dropdown) 获取列表对象。例如：
lv_obj_t * list = lv_dropdown_get_list(dropdown) /*Get the list*/
lv_obj_add_style(list, &my_style, selector) /*Add the styles to the list*/
或者，可以使用自定义新样式扩展主题。
Usage（用法）
Options（选项）
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 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) 函数的 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)。
要获取所选中的选项的文本（str），使用函数 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) 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) 修改展开方向。
如果列表在指定的展开方向超出的屏幕（父对象）的范围，其会自动进行调整展开方向。
Symbol（符号）
显示原文
A symbol (typically an arrow) can be added to the dropdown 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，则所当前选选项将显示在按钮上。
Programmatically open/close（编程打开或关闭）
显示原文
To programmatically open or close the Drop-Down List use lv_dropdown_open(dropdown) or lv_dropdown_close(dropdown).
要通过编程方式打开或关闭下拉列表，可以使用 lv_dropdown_open(dropdown)`或 :cpp:expr:`lv_dropdown_close(dropdown)。
Events（事件）
显示原文
Apart from the Generic events, the following Special events are sent by the drop-down list:
LV_EVENT_VALUE_CHANGEDSent when the new option is selected or the list is opened/closed.LV_EVENT_CANCELSent when the list is closedLV_EVENT_READYSent when the list is opened
See the events of the Base object too.
Learn more about Events（事件）.
LV_EVENT_VALUE_CHANGED在选择新选项或打开/关闭列表时发送。LV_EVENT_CANCEL列表关闭时发送LV_EVENT_READY打开列表时发送
可以参考 Base object 的事件。
详细了解更多 Events（事件）。
Keys（按键）
显示原文
LV_KEY_RIGHT/DOWNSelect next list item.LV_KEY_LEFT/UPSelect previous list item.LV_KEY_ENTERApply selected list item (sendsLV_EVENT_VALUE_CHANGEDevent and closes Drop-Down List).
Further Reading
Learn more about Keys（按键）.
LV_KEY_RIGHT/DOWN：选择下一个列表项。LV_KEY_LEFT/UP：选择上一个列表项。LV_KEY_ENTER：应用所选的列表项（会发送LV_EVENT_VALUE_CHANGED事件并关闭下拉列表）。
Further Reading
进一步了解:ref:indev_keys。
Example
Simple Drop down list
C code
View on 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_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
C code
View on 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_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