Table (lv_table)

A lightweight grid of text cells. Only the strings are stored; cells are drawn on the fly.

Overview

A Table is a grid of rows, columns, and text cells. It is lightweight because no widgets are created for the cells — they are drawn on the fly.

Tables are added to the default group (if one is set). A Table is an editable widget: cells can be selected with encoder or keyboard input as well as with a pointer.

Set cell value

lv_table_set_cell_value(table, row, col, "Content") writes a cell. The text is copied so the source buffer can be local. Use \n for a line break inside a cell. Writing past the current grid grows the table automatically.

Rows and Columns

Pre-size the grid with lv_table_set_row_count(table, n) and lv_table_set_column_count(table, n).

Width and Height

lv_table_set_column_width(table, col, w) sets per-column pixel width; the table's overall width is the sum. Height is derived automatically from cell styles (font, padding) and row count.

Merge cells

extends a cell into the next column. Chain it on adjacent cells to span more than two columns.

Styling

• LV_PART_MAIN The background of the Table; uses the typical background style properties.
• LV_PART_ITEMS The cells of the Table also use the typical background style properties as well as text style properties.

Table has two stylable parts: LV_PART_MAIN (the table's outer frame and background) and LV_PART_ITEMS (every cell — borders, padding, text). Attach a named style with selector="main" or selector="items"; cells inherit the items style uniformly. Per-row styling isn't expressed through XML selectors today — use cell ctrl flags or a runtime draw event to vary the header row.

Scrolling

If a Table's width or height is set to LV_SIZE_CONTENT that size will be used to show the whole Table in the respective direction. E.g.

automatically sets the Table size to show all columns and rows.

If the width or height is set to a smaller number than its "intrinsic" size then the Table becomes scrollable.

Set cell user data

lv_table_set_cell_user_data(table, row, col, ptr) attaches an opaque pointer to a cell, retrievable with lv_table_get_cell_user_data. The table doesn't own the pointer — free it yourself on LV_EVENT_DELETE if the data was dynamically allocated:

static void table_delete_cb(lv_event_t * e) {
    lv_obj_t * table = lv_event_get_target_obj(e);
    for(uint32_t r = 0; r < lv_table_get_row_count(table); r++) {
        for(uint32_t c = 0; c < lv_table_get_column_count(table); c++) {
            lv_free(lv_table_get_cell_user_data(table, r, c));
        }
    }
}
lv_obj_add_event_cb(table, table_delete_cb, LV_EVENT_DELETE, NULL);

Events

LV_EVENT_VALUE_CHANGED is sent when a new cell is selected with keys.

Learn more about Events emitted by all Widgets.

Keys

LV_KEY_RIGHT/LEFT/UP/DOWN selects a cell.

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

lv_table_get_selected_cell(table, &row, &col) can be used to get the currently selected cell. Row and column will be set to LV_TABLE_CELL_NONE if no cell is selected.

Learn more about Keys.

Building a file explorer

A table can also be used to create a simple file explorer. In the example the table has 2 columns: a shorter one for an icon, and a longer one for the file/folder name.

The contents of a directory are listed with the lv_fs APIs (lv_fs_dir_open/lv_fs_dir_read/lv_fs_dir_close). Note that a file-system driver (e.g. LV_USE_FS_STDIO) needs to be enabled in lv_conf.h.

The example also contains a few extra features, like a quick access sidebar.

Examples

Scrollable 200-item list with per-row toggle

It builds a 200-row table inside a scrollable parent, attaches an LV_EVENT_DRAW_TASK_ADDED callback that paints a switch-style toggle in the second column based on the row's CUSTOM_1 cell control flag, and toggles that flag from LV_EVENT_VALUE_CHANGED.