Table (lv_table)

Overview

Tables, as usual, are built from rows, columns, and cells containing texts.

The Table object is very lightweight because only the texts are stored. No real objects are created for cells but they are just drawn on the fly.

The Table is added to the default group (if it is set). Besides the Table is an editable object to allow selecting a cell with encoder navigation too.

Parts and Styles

  • LV_PART_MAIN The background of the table uses all the typical background style properties.

  • LV_PART_ITEMS The cells of the table also use all the typical background style properties and the text properties.

Usage

Set cell value

The cells can store only text so numbers need to be converted to text before displaying them in a table.

lv_table_set_cell_value(table, row, col, "Content"). The text is saved by the table so it can be even a local variable.

Line breaks can be used in the text like "Value\n60.3".

New rows and columns are automatically added is required

Rows and Columns

To explicitly set number of rows and columns use lv_table_set_row_cnt(table, row_cnt) and lv_table_set_col_cnt(table, col_cnt)

Width and Height

The width of the columns can be set with lv_table_set_col_width(table, col_id, width). The overall width of the Table object will be set to the sum of columns widths.

The height is calculated automatically from the cell styles (font, padding etc) and the number of rows.

Merge cells

Cells can be merged horizontally with lv_table_add_cell_ctrl(table, row, col, LV_TABLE_CELL_CTRL_MERGE_RIGHT). To merge more adjacent cells call this function for each cell.

Scroll

If the label'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. lv_obj_set_size(table, LV_SIZE_CONTENT, LV_SIZE_CONTENT) automatically sets the table size to show all the columns and rows.

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

Events

  • LV_EVENT_VALUE_CHANGED Sent when a new cell is selected with keys.

  • LV_EVENT_DRAW_PART_BEGIN and LV_EVENT_DRAW_PART_END are sent for the following types:

    • LV_TABLE_DRAW_PART_CELL The individual cells of the table

      • part: LV_PART_ITEMS

      • draw_area: area of the indicator

      • rect_dsc

      • label_dsc

      • id: current row × col count + current column

See the events of the Base object too.

Learn more about Events.

Keys

The following Keys are processed by the Tables:

  • LV_KEY_RIGHT/LEFT/UP/DOWN/ Select 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 no cell is selected.

Learn more about Keys.

Example

MicroPython

No examples yet.

API

Typedefs

typedef uint8_t lv_table_cell_ctrl_t

Enums

enum [anonymous]

Values:

enumerator LV_TABLE_CELL_CTRL_MERGE_RIGHT
enumerator LV_TABLE_CELL_CTRL_TEXT_CROP
enumerator LV_TABLE_CELL_CTRL_CUSTOM_1
enumerator LV_TABLE_CELL_CTRL_CUSTOM_2
enumerator LV_TABLE_CELL_CTRL_CUSTOM_3
enumerator LV_TABLE_CELL_CTRL_CUSTOM_4
enum lv_table_draw_part_type_t

type field in lv_obj_draw_part_dsc_t if class_p = lv_table_class Used in LV_EVENT_DRAW_PART_BEGIN and LV_EVENT_DRAW_PART_END

Values:

enumerator LV_TABLE_DRAW_PART_CELL

A cell

Functions

LV_EXPORT_CONST_INT(LV_TABLE_CELL_NONE)
lv_obj_t *lv_table_create(lv_obj_t *parent)

Create a table object

Parameters

parent -- pointer to an object, it will be the parent of the new table

Returns

pointer to the created table

void lv_table_set_cell_value(lv_obj_t *obj, uint16_t row, uint16_t col, const char *txt)

Set the value of a cell.

Note

New roes/columns are added automatically if required

Parameters
  • obj -- pointer to a Table object

  • row -- id of the row [0 .. row_cnt -1]

  • col -- id of the column [0 .. col_cnt -1]

  • txt -- text to display in the cell. It will be copied and saved so this variable is not required after this function call.

void lv_table_set_cell_value_fmt (lv_obj_t *obj, uint16_t row, uint16_t col, const char *fmt,...) LV_FORMAT_ATTRIBUTE(4

Set the value of a cell. Memory will be allocated to store the text by the table.

Note

New roes/columns are added automatically if required

Parameters
  • obj -- pointer to a Table object

  • row -- id of the row [0 .. row_cnt -1]

  • col -- id of the column [0 .. col_cnt -1]

  • fmt -- printf-like format

void void lv_table_set_row_cnt (lv_obj_t *obj, uint16_t row_cnt)

Set the number of rows

Parameters
  • obj -- table pointer to a Table object

  • row_cnt -- number of rows

void lv_table_set_col_cnt(lv_obj_t *obj, uint16_t col_cnt)

Set the number of columns

Parameters
  • obj -- table pointer to a Table object

  • col_cnt -- number of columns.

void lv_table_set_col_width(lv_obj_t *obj, uint16_t col_id, lv_coord_t w)

Set the width of a column

Parameters
  • obj -- table pointer to a Table object

  • col_id -- id of the column [0 .. LV_TABLE_COL_MAX -1]

  • w -- width of the column

void lv_table_add_cell_ctrl(lv_obj_t *obj, uint16_t row, uint16_t col, lv_table_cell_ctrl_t ctrl)

Add control bits to the cell.

Parameters
  • obj -- pointer to a Table object

  • row -- id of the row [0 .. row_cnt -1]

  • col -- id of the column [0 .. col_cnt -1]

  • ctrl -- OR-ed values from ::lv_table_cell_ctrl_t

void lv_table_clear_cell_ctrl(lv_obj_t *obj, uint16_t row, uint16_t col, lv_table_cell_ctrl_t ctrl)

Clear control bits of the cell.

Parameters
  • obj -- pointer to a Table object

  • row -- id of the row [0 .. row_cnt -1]

  • col -- id of the column [0 .. col_cnt -1]

  • ctrl -- OR-ed values from ::lv_table_cell_ctrl_t

const char *lv_table_get_cell_value(lv_obj_t *obj, uint16_t row, uint16_t col)

Get the value of a cell.

Parameters
  • obj -- pointer to a Table object

  • row -- id of the row [0 .. row_cnt -1]

  • col -- id of the column [0 .. col_cnt -1]

Returns

text in the cell

uint16_t lv_table_get_row_cnt(lv_obj_t *obj)

Get the number of rows.

Parameters

obj -- table pointer to a Table object

Returns

number of rows.

uint16_t lv_table_get_col_cnt(lv_obj_t *obj)

Get the number of columns.

Parameters

obj -- table pointer to a Table object

Returns

number of columns.

lv_coord_t lv_table_get_col_width(lv_obj_t *obj, uint16_t col)

Get the width of a column

Parameters
  • obj -- table pointer to a Table object

  • col -- id of the column [0 .. LV_TABLE_COL_MAX -1]

Returns

width of the column

bool lv_table_has_cell_ctrl(lv_obj_t *obj, uint16_t row, uint16_t col, lv_table_cell_ctrl_t ctrl)

Get whether a cell has the control bits

Parameters
  • obj -- pointer to a Table object

  • row -- id of the row [0 .. row_cnt -1]

  • col -- id of the column [0 .. col_cnt -1]

  • ctrl -- OR-ed values from ::lv_table_cell_ctrl_t

Returns

true: all control bits are set; false: not all control bits are set

void lv_table_get_selected_cell(lv_obj_t *obj, uint16_t *row, uint16_t *col)

Get the selected cell (pressed and or focused)

Parameters
  • obj -- pointer to a table object

  • row -- pointer to variable to store the selected row (LV_TABLE_CELL_NONE: if no cell selected)

  • col -- pointer to variable to store the selected column (LV_TABLE_CELL_NONE: if no cell selected)

Variables

const lv_obj_class_t lv_table_class
struct lv_table_t

Public Members

lv_obj_t obj
uint16_t col_cnt
uint16_t row_cnt
char **cell_data
lv_coord_t *row_h
lv_coord_t *col_w
uint16_t col_act
uint16_t row_act