Overview

Drop Down Lists allow you to simply select one option from more. The Drop Down List is closed by default an show the currently selected text. If you click on it the this list opens and all the options are shown.

The options are passed to the Drop Down List as a string with lv_ddlist_set_options(ddlist, options). The options should be separated by \n. For example: "First\nSecond\nThird"

You can select an option manually with lv_ddlist_set_selected(ddlist, id), where id is the index of an option.

A callback function can be specified with lv_ddlist_set_action(ddlist, my_action) to call when a new option is selected.

By default the list's height is adjusted automatically to show all options. The lv_ddlist_set_fix_height(ddlist, h) set a fix height for the opened list.

The width is also adjusted automatically. To prevent this apply lv_ddlist_set_hor_fit(ddlist, false) and set the width manually by lv_obj_set_width(ddlist, width)

Similarly to Page with fix height the Drop Down List supports various scrollbar display modes. It can be set by lv_ddlist_set_sb_mode(ddlist, LV_SB_MODE_...)

The Drop Dawn List open/close animation time is adjusted by lv_ddlist_set_anim_time(ddlist, anim_time). Zero animation time means no animation.

Style usage

The lv_ddlist_set_style(ddlist, LV_DDLIST_STYLE_..., &style) set the styles of a Drop Down List

  • LV_DDLIST_STYLE_BG Style of the background. All style.body properties are used. It is used for the label's style from style.text. Default: lv_style_pretty
  • LV_DDLIST_STYLE_SEL Style of the selected option. The style.body properties are used. The selected option will be recolored with text.color. Default: lv_style_plain_color
  • LV_DDLIST_STYLE_SB Style of the scrollbar. The style.body properties are used. Default: lv_style_plain_color

Notes

Example of Drop down list in Littlev Graphics Library

						static lv_res_t ddlist_action(lv_obj_t * ddlist)
{
    uint8_t id = lv_obj_get_free_num(ddlist);

    char sel_str[32];
    lv_ddlist_get_selected_str(ddlist, sel_str);
    printf("Ddlist %d new option: %s \n", id, sel_str);

    return LV_RES_OK; /*Return OK if the drop down list is not deleted*/
}


.
.
.

/*Create a drop down list*/
lv_obj_t * ddl1 = lv_ddlist_create(lv_scr_act(), NULL);
lv_ddlist_set_options(ddl1, "Apple\n"
                            "Banana\n"
                            "Orange\n"
                            "Melon\n"
                            "Grape\n"
                            "Raspberry");
lv_obj_align(ddl1, NULL, LV_ALIGN_IN_TOP_LEFT, 30, 10);
lv_obj_set_free_num(ddl1, 1);               /*Set a unique ID*/
lv_ddlist_set_action(ddl1, ddlist_action);  /*Set a function to call when anew option is chosen*/

/*Create a style*/
static lv_style_t style_bg;
lv_style_copy(&style_bg, &lv_style_pretty);
style_bg.body.shadow.width = 4; /*Enable the shadow*/
style_bg.text.color = LV_COLOR_MAKE(0x10, 0x20, 0x50);

/*Copy the drop down list and set the new style_bg*/
lv_obj_t * ddl2 = lv_ddlist_create(lv_scr_act(), ddl1);
lv_obj_align(ddl2, NULL, LV_ALIGN_IN_TOP_RIGHT, -30, 10);
lv_obj_set_free_num(ddl2, 2);       /*Set a unique ID*/
lv_obj_set_style(ddl2, &style_bg);

lv_obj_t *

lv_ddlist_create

(lv_obj_t * par, lv_obj_t * copy);

Create a drop down list objects

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

copy pointer to a drop down list object, if not NULL then the new object will be copied from it

return pointer to the created drop down list

void

lv_ddlist_set_options

(lv_obj_t * ddlist, const char * options);

Set the options in a drop down list from a string

ddlist pointer to drop down list object

options a string with '\n' separated options. E.g. "One\nTwo\nThree"

void

lv_ddlist_set_selected

(lv_obj_t * ddlist, uint16_t sel_opt);

Set the selected option

ddlist pointer to drop down list object

sel_opt id of the selected option (0 ... number of option - 1);

void

lv_ddlist_set_action

(lv_obj_t * ddlist, lv_action_t action);

Set a function to call when a new option is chosen

ddlist pointer to a drop down list

action pointer to a call back function

void

lv_ddlist_set_fix_height

(lv_obj_t * ddlist, lv_coord_t h);

Set the fix height for the drop down list
If 0 then the opened ddlist will be auto. sized else the set height will be applied.

ddlist pointer to a drop down list

h the height when the list is opened (0: auto size)

void

lv_ddlist_set_hor_fit

(lv_obj_t * ddlist, bool fit_en);

Enable or disable the horizontal fit to the content

ddlist pointer to a drop down list

fit en true: enable auto fit; false: disable auto fit

void

lv_ddlist_set_sb_mode

(lv_obj_t * ddlist, lv_sb_mode_t mode);

Set the scroll bar mode of a drop down list

ddlist pointer to a drop down list object

sb_mode the new mode from 'lv_page_sb_mode_t' enum

void

lv_ddlist_set_anim_time

(lv_obj_t * ddlist, uint16_t anim_time);

Set the open/close animation time.

ddlist pointer to a drop down list

anim_time: open/close animation time [ms]

void

lv_ddlist_set_style

(lv_obj_t *ddlist, lv_ddlist_style_t type, lv_style_t *style);

Set a style of a drop down list

ddlist pointer to a drop down list object

type which style should be set

style pointer to a style

const

char

* lv_ddlist_get_options(lv_obj_t * ddlist);

Get the options of a drop down list

ddlist pointer to drop down list object

return the options separated by '\n'-s (E.g. "Option1\nOption2\nOption3")

uint16_t

lv_ddlist_get_selected

(lv_obj_t * ddlist);

Get the selected option

ddlist pointer to drop down list object

return id of the selected option (0 ... number of option - 1);

void

lv_ddlist_get_selected_str

(lv_obj_t * ddlist, char * buf);

Get the current selected option as a string

ddlist pointer to ddlist object

buf pointer to an array to store the string

lv_action_t

lv_ddlist_get_action

(lv_obj_t * ddlist);

Get the "option selected" callback function

ddlist pointer to a drop down list

return pointer to the call back function

lv_coord_t

lv_ddlist_get_fix_height

(lv_obj_t * ddlist);

Get the fix height value.

ddlist pointer to a drop down list object

return the height if the ddlist is opened (0: auto size)

lv_sb_mode_t

lv_ddlist_get_sb_mode

(lv_obj_t * ddlist);

Get the scroll bar mode of a drop down list

ddlist pointer to a drop down list object

return scrollbar mode from 'lv_page_sb_mode_t' enum

uint16_t

lv_ddlist_get_anim_time

(lv_obj_t * ddlist);

Get the open/close animation time.

ddlist pointer to a drop down list

return open/close animation time [ms]

lv_style_t *

lv_ddlist_get_style

(lv_obj_t *ddlist, lv_ddlist_style_t type);

Get a style of a drop down list

ddlist pointer to a drop down list object

type which style should be get

return style pointer to a style

void

lv_ddlist_open

(lv_obj_t * ddlist, bool anim);

Open the drop down list with or without animation

ddlist pointer to drop down list object

anim_en true: use animation; false: not use animations

void

lv_ddlist_close_en

(lv_obj_t * ddlist, bool anim);

Close (Collapse) the drop down list

ddlist pointer to drop down list object

anim true: use animation; false: not use animations

LittlevGL - Open-source Embedded GUI Library

LittlevGL is a free and open-source graphics library providing everything you need to create embedded GUI with easy-to-use graphical elements, beautiful visual effects and low memory footprint.

If you like LittlevGL, please
support its deveopment!


The founder of Littlev Graphics Library (LittlevGL) and related software modules is:
Gábor Kiss-Vámosi
All Rights Reserved ©  2018 Hungary