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 just use lv_obj_del(btn) on the return value of lv_list_add_btn().

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

Manual navigation

You can navigate manually in the list with lv_list_up(list) and lv_list_down(list).

You can focus on a button directly using lv_list_focus(btn, LV_ANIM_ON/OFF).

The animation time of up/down/focus movements can be set via: lv_list_set_anim_time(list, anim_time). Zero animation time means not animations.

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

List example in LittlevGL

code

#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

List example in LittlevGL with MicroPython

code

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:

LV_LIST_STYLE_BG

List background style

LV_LIST_STYLE_SCRL

List scrollable area style.

LV_LIST_STYLE_SB

List scrollbar style.

LV_LIST_STYLE_EDGE_FLASH

List edge flash style.

LV_LIST_STYLE_BTN_REL

Same meaning as the ordinary button styles.

LV_LIST_STYLE_BTN_PR
LV_LIST_STYLE_BTN_TGL_REL
LV_LIST_STYLE_BTN_TGL_PR
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

static 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

static 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

static 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

static 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

static 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

static 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

static 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

static 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