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 it's opened.
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.
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, ...) /*Add the styles to the list*/}`
Alternatively the theme can be extended with the new styles.
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.
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
.
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.
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.
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.
Manually open/close¶
To manually open or close the drop-down list the lv_dropdown_open/close(dropdown)
function can be used.
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.LV_EVENT_CANCEL
Sent when the list is closedLV_EVENT_READY
Sent when the list is opened
See the events of the Base object too.
Learn more about Events.
Keys¶
LV_KEY_RIGHT/DOWN
Select the next option.LV_KEY_LEFT/UP
Select the previous option.LY_KEY_ENTER
Apply the selected option (SendsLV_EVENT_VALUE_CHANGED
event and closes the drop-down list).
Learn more about 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
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
#
# 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)
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.
-
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
-
struct lv_dropdown_t¶
Public Members
-
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
-
const char *text¶
-
struct lv_dropdown_list_t¶