List (lv_list)¶

Overview¶

The Lists are built from a background Page and Buttons on it. The Buttons contain an optional icon-like Image (which can be a symbol too) and a Label. When the list becomes long enough it can be scrolled.

Add buttons¶

You can add new list elements with lv_list_add_btn(list, &icon_img, "Text") or with symbol lv_list_add_btn(list, SYMBOL_EDIT, "Edit text"). If you do not want to add image use NULL as image source. The function returns with a pointer to the created button to allow further configurations.

The width of the buttons is set to maximum according to the object width. The height of the buttons are adjusted automatically according to the content. (content height + padding.top + padding.bottom).

The labels are created with LV_LABEL_LONG_SROLL_CIRC long mode to automatically scroll the long labels circularly.

You can use lv_list_get_btn_label(list_btn) and lv_list_get_btn_img(list_btn) to get the label and the image of a list button. You can get the text directly with lv_list_get_btn_text(list_btn).

Delete buttons¶

To delete a list element use lv_list_remove(list, btn_index). btn_index can be obtained by lv_list_get_btn_index(list, btn) where btn is the return value of lv_list_add_btn().

To clean the list (remove all buttons) use lv_list_clean(list)

Layout¶

By default the list is vertical. To get a horizontal list use lv_list_set_layout(list, LV_LAYOUT_ROW_M).

Edge flash¶

A circle-like effect can be shown when the list reaches the most top or bottom position. lv_list_set_edge_flash(list, en) enables this feature.

Scroll propagation¶

If the list is created on an other scrollable element (like a Page) and the list can’t be scrolled further the scrolling can be propagated to the parent. This way the scroll will be continued on the parent. It can be enabled with lv_list_set_scroll_propagation(list, true)

If the buttons have lv_btn_set_toggle enabled then lv_list_set_single_mode(list, true) can be used to ensure that only one button can be in toggled state at the same time.

Style usage¶

The lv_list_set_style(list, LV_LIST_STYLE_..., &style) function sets the style of a list.

LV_LIST_STYLE_BG list background style. Default: lv_style_transp_fit
LV_LIST_STYLE_SCRL scrollable part’s style. Default: lv_style_pretty
LV_LIST_STYLE_SB scrollbars’ style. Default: lv_style_pretty_color. For details see Page
LV_LIST_STYLE_BTN_REL button released style. Default: lv_style_btn_rel
LV_LIST_STYLE_BTN_PR button pressed style. Default: lv_style_btn_pr
LV_LIST_STYLE_BTN_TGL_REL button toggled released style. Default: lv_style_btn_tgl_rel
LV_LIST_STYLE_BTN_TGL_PR button toggled pressed style. Default: lv_style_btn_tgl_pr
LV_LIST_STYLE_BTN_INA button inactive style. Default: lv_style_btn_ina

Because BG has a transparent style by default if there is only a few buttons the list will look shorter but become scrollable when more list elements are added.

To modify the height of the buttons adjust the body.padding.top/bottom fields of the corresponding styles (LV_LIST_STYLE_BTN_REL/PR/...)

Events¶

Only the Generic events are sent by the object type.

Learn more about Events.

Keys¶

The following Keys are processed by the Lists:

LV_KEY_RIGHT/DOWN Select the next button
LV_KEY_LEFT/UP Select the previous button

Note that, as usual, the state of LV_KEY_ENTER is translated to LV_EVENT_PRESSED/PRESSING/RELEASED etc.

The Selected buttons are in LV_BTN_STATE_PR/TG_PR state.

To manually select a button use lv_list_set_btn_selected(list, btn). When the list is defocused and focused again it will restore the last selected button.

Learn more about Keys.

Example¶

C¶

Simple List¶

#include "lvgl/lvgl.h"
#include <stdio.h>

static void event_handler(lv_obj_t * obj, lv_event_t event)
{
    if(event == LV_EVENT_CLICKED) {
        printf("Clicked: %s\n", lv_list_get_btn_text(obj));
    }
}

void lv_ex_list_1(void)
{
    /*Create a list*/
    lv_obj_t * list1 = lv_list_create(lv_scr_act(), NULL);
    lv_obj_set_size(list1, 160, 200);
    lv_obj_align(list1, NULL, LV_ALIGN_CENTER, 0, 0);

    /*Add buttons to the list*/

    lv_obj_t * list_btn;

    list_btn = lv_list_add_btn(list1, LV_SYMBOL_FILE, "New");
    lv_obj_set_event_cb(list_btn, event_handler);

    list_btn = lv_list_add_btn(list1, LV_SYMBOL_DIRECTORY, "Open");
    lv_obj_set_event_cb(list_btn, event_handler);

    list_btn = lv_list_add_btn(list1, LV_SYMBOL_CLOSE, "Delete");
    lv_obj_set_event_cb(list_btn, event_handler);

    list_btn = lv_list_add_btn(list1, LV_SYMBOL_EDIT, "Edit");
    lv_obj_set_event_cb(list_btn, event_handler);

    list_btn = lv_list_add_btn(list1, LV_SYMBOL_SAVE, "Save");
    lv_obj_set_event_cb(list_btn, event_handler);
}

MicroPython¶

Simple List¶

def event_handler(obj, event):
    if event == lv.EVENT.CLICKED:
        print("Clicked: %s" % lv.list.get_btn_text(obj))

# Create a list
list1 = lv.list(lv.scr_act())
list1.set_size(160, 200)
list1.align(None, lv.ALIGN.CENTER, 0, 0)

# Add buttons to the list

list_btn = list1.add_btn(lv.SYMBOL.FILE, "New")
list_btn.set_event_cb(event_handler)

list_btn = list1.add_btn(lv.SYMBOL.DIRECTORY, "Open")
list_btn.set_event_cb(event_handler)

list_btn = list1.add_btn(lv.SYMBOL.CLOSE, "Delete")
list_btn.set_event_cb(event_handler)

list_btn = list1.add_btn(lv.SYMBOL.EDIT, "Edit")
list_btn.set_event_cb(event_handler)

list_btn = list1.add_btn(lv.SYMBOL.SAVE, "Save")
list_btn.set_event_cb(event_handler)

API¶

Typedefs

typedef uint8_t lv_list_style_t¶

Enums

enum [anonymous]¶

List styles.

Values:

enumerator LV_LIST_STYLE_BG¶: List background style

enumerator LV_LIST_STYLE_SCRL¶: List scrollable area style.

enumerator LV_LIST_STYLE_SB¶: List scrollbar style.

enumerator LV_LIST_STYLE_EDGE_FLASH¶: List edge flash style.

enumerator LV_LIST_STYLE_BTN_REL¶: Same meaning as the ordinary button styles.

enumerator LV_LIST_STYLE_BTN_PR¶

enumerator LV_LIST_STYLE_BTN_TGL_REL¶

enumerator LV_LIST_STYLE_BTN_TGL_PR¶

enumerator LV_LIST_STYLE_BTN_INA¶

Functions

lv_obj_t *lv_list_create(lv_obj_t *par, const lv_obj_t *copy)¶

Create a list objects

Return

pointer to the created list

Parameters

par: pointer to an object, it will be the parent of the new list
copy: pointer to a list object, if not NULL then the new object will be copied from it

void lv_list_clean(lv_obj_t *list)¶

Delete all children of the scrl object, without deleting scrl child.

Parameters

list: pointer to an object

lv_obj_t *lv_list_add_btn(lv_obj_t *list, const void *img_src, const char *txt)¶

Add a list element to the list

Return

pointer to the new list element which can be customized (a button)

Parameters

list: pointer to list object
img_fn: file name of an image before the text (NULL if unused)
txt: text of the list element (NULL if unused)

bool lv_list_remove(const lv_obj_t *list, uint16_t index)¶

Remove the index of the button in the list

Return

true: successfully deleted

Parameters

list: pointer to a list object
index: pointer to a the button’s index in the list, index must be 0 <= index < lv_list_ext_t.size

void lv_list_set_single_mode(lv_obj_t *list, bool mode)¶

Set single button selected mode, only one button will be selected if enabled.

Parameters

list: pointer to the currently pressed list object
mode: enable(true)/disable(false) single selected mode.

void lv_list_set_btn_selected(lv_obj_t *list, lv_obj_t *btn)¶

Make a button selected

Parameters

list: pointer to a list object
btn: pointer to a button to select NULL to not select any buttons

void lv_list_set_sb_mode(lv_obj_t *list, lv_sb_mode_t mode)¶

Set the scroll bar mode of a list

Parameters

list: pointer to a list object
sb_mode: the new mode from ‘lv_page_sb_mode_t’ enum

void lv_list_set_scroll_propagation(lv_obj_t *list, bool en)¶

Enable the scroll propagation feature. If enabled then the List will move its parent if there is no more space to scroll.

Parameters

list: pointer to a List
en: true or false to enable/disable scroll propagation

void lv_list_set_edge_flash(lv_obj_t *list, bool en)¶

Enable the edge flash effect. (Show an arc when the an edge is reached)

Parameters

list: pointer to a List
en: true or false to enable/disable end flash

void lv_list_set_anim_time(lv_obj_t *list, uint16_t anim_time)¶

Set scroll animation duration on ‘list_up()’ ‘list_down()’ ‘list_focus()’

Parameters

list: pointer to a list object
anim_time: duration of animation [ms]

void lv_list_set_style(lv_obj_t *list, lv_list_style_t type, const lv_style_t *style)¶

Set a style of a list

Parameters

list: pointer to a list object
type: which style should be set
style: pointer to a style

void lv_list_set_layout(lv_obj_t *list, lv_layout_t layout)¶

Set layout of a list

Parameters

list: pointer to a list object
layout: which layout should be used

bool lv_list_get_single_mode(lv_obj_t *list)¶

Get single button selected mode.

Parameters

list: pointer to the currently pressed list object.

const char *lv_list_get_btn_text(const lv_obj_t *btn)¶

Get the text of a list element

Return

pointer to the text

Parameters

btn: pointer to list element

lv_obj_t *lv_list_get_btn_label(const lv_obj_t *btn)¶

Get the label object from a list element

Return

pointer to the label from the list element or NULL if not found

Parameters

btn: pointer to a list element (button)

lv_obj_t *lv_list_get_btn_img(const lv_obj_t *btn)¶

Get the image object from a list element

Return

pointer to the image from the list element or NULL if not found

Parameters

btn: pointer to a list element (button)

lv_obj_t *lv_list_get_prev_btn(const lv_obj_t *list, lv_obj_t *prev_btn)¶

Get the next button from list. (Starts from the bottom button)

Return

pointer to the next button or NULL when no more buttons

Parameters

list: pointer to a list object
prev_btn: pointer to button. Search the next after it.

lv_obj_t *lv_list_get_next_btn(const lv_obj_t *list, lv_obj_t *prev_btn)¶

Get the previous button from list. (Starts from the top button)

Return

pointer to the previous button or NULL when no more buttons

Parameters

list: pointer to a list object
prev_btn: pointer to button. Search the previous before it.

int32_t lv_list_get_btn_index(const lv_obj_t *list, const lv_obj_t *btn)¶

Get the index of the button in the list

Return

the index of the button in the list, or -1 of the button not in this list

Parameters

list: pointer to a list object. If NULL, assumes btn is part of a list.
btn: pointer to a list element (button)

uint16_t lv_list_get_size(const lv_obj_t *list)¶

Get the number of buttons in the list

Return

the number of buttons in the list

Parameters

list: pointer to a list object

lv_obj_t *lv_list_get_btn_selected(const lv_obj_t *list)¶

Get the currently selected button. Can be used while navigating in the list with a keypad.

Return

pointer to the selected button

Parameters

list: pointer to a list object

lv_layout_t lv_list_get_layout(lv_obj_t *list)¶

Get layout of a list

Return

layout of the list object

Parameters

list: pointer to a list object

lv_sb_mode_t lv_list_get_sb_mode(const lv_obj_t *list)¶

Get the scroll bar mode of a list

Return

scrollbar mode from ‘lv_page_sb_mode_t’ enum

Parameters

list: pointer to a list object

bool lv_list_get_scroll_propagation(lv_obj_t *list)¶

Get the scroll propagation property

Return

true or false

Parameters

list: pointer to a List

bool lv_list_get_edge_flash(lv_obj_t *list)¶

Get the scroll propagation property

Return

true or false

Parameters

list: pointer to a List

uint16_t lv_list_get_anim_time(const lv_obj_t *list)¶

Get scroll animation duration

Return

duration of animation [ms]

Parameters

list: pointer to a list object

const lv_style_t *lv_list_get_style(const lv_obj_t *list, lv_list_style_t type)¶

Get a style of a list

Return

style pointer to a style

Parameters

list: pointer to a list object
type: which style should be get

void lv_list_up(const lv_obj_t *list)¶

Move the list elements up by one

Parameters

list: pointer a to list object

void lv_list_down(const lv_obj_t *list)¶

Move the list elements down by one

Parameters

list: pointer to a list object

void lv_list_focus(const lv_obj_t *btn, lv_anim_enable_t anim)¶

Focus on a list button. It ensures that the button will be visible on the list.

Parameters

btn: pointer to a list button to focus
anim: LV_ANOM_ON: scroll with animation, LV_ANIM_OFF: without animation

struct lv_list_ext_t¶

Public Members

lv_page_ext_t page¶

const lv_style_t *styles_btn[_LV_BTN_STATE_NUM]¶

const lv_style_t *style_img¶

uint16_t size¶

uint8_t single_mode¶

lv_obj_t *last_sel¶

lv_obj_t *selected_btn¶

lv_obj_t *last_clicked_btn¶

List (lv_list)¶

Overview¶

Add buttons¶

Delete buttons¶

Manual navigation¶

Layout¶

Edge flash¶

Scroll propagation¶

Style usage¶

Events¶

Keys¶

Example¶

C¶

Simple List¶

MicroPython¶

Simple List¶

API¶