# Table (lv_table) (/widgets/table)



Overview [#overview]

Tables are built from rows, columns, and cells containing text.

The Table Widget is very lightweight because only the text strings are stored.
No real Widgets are created for cells --- they are just drawn on the fly.

The Table is added to the default group (if one is set).
Table is an editable Widget, allowing selection of a cell with encoder and keyboard
navigation as well.

Parts and Styles [#parts-and-styles]

* <ApiLink name="LV_PART_MAIN" /> The background of the Table; uses the [typical
  background style properties](/common-widget-features/styles/overview).
* <ApiLink name="LV_PART_ITEMS" /> The cells of the Table also use the
  [typical background style properties](/common-widget-features/styles/overview) as well as text
  style properties.

Usage [#usage]

Set cell value [#set-cell-value]

Cells can store only text so numbers need to be converted to text
before displaying them in a Table.

<ApiLink name="lv_table_set_cell_value" display="lv_table_set_cell_value(table, row, col, &#x22;Content&#x22;)" />. The text is
saved by the Table so the buffer containing the string can be a local variable.

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

New rows and columns are automatically added as required.

Rows and Columns [#rows-and-columns]

To explicitly set number of rows and columns use
<ApiLink name="lv_table_set_row_count" display="lv_table_set_row_count(table, row_cnt)" /> and
<ApiLink name="lv_table_set_column_count" display="lv_table_set_column_count(table, col_cnt)" />.

Width and Height [#width-and-height]

Column width can be set with
<ApiLink name="lv_table_set_column_width" display="lv_table_set_column_width(table, col_id, width)" />. The overall width of
the Table Widget will be set to the sum of all column widths.

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

Merge cells [#merge-cells]

Cells can be merged horizontally with
<ApiLink name="lv_table_set_cell_ctrl" display="lv_table_set_cell_ctrl(table, row, col, LV_TABLE_CELL_CTRL_MERGE_RIGHT)" />.
To merge more adjacent cells, call this function for each cell.

Scrolling [#scrolling]

If a Table's width or height is set to <ApiLink name="LV_SIZE_CONTENT" /> that size
will be used to show the whole Table in the respective direction. E.g.

<ApiLink name="lv_obj_set_size" display="lv_obj_set_size(table, LV_SIZE_CONTENT, LV_SIZE_CONTENT)" />

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 [#set-cell-user-data]

Custom data can be bound to a table cell. The data lifetime must be managed by the user. If the data is dynamically allocated,
the user must free it to prevent memory leaks. This can be done by binding to the <ApiLink name="LV_EVENT_DELETE" /> event.

```c title=" " lineNumbers=1
static void table_delete_event_cb(lv_event_t * e) {
    lv_obj_t * my_table = lv_event_get_target_obj(e);
    const uint32_t row_count = lv_table_get_row_count(table);
    const uint32_t col_count = lv_table_get_column_count(table);

    /* Assuming every cell has custom data associated with it*/
    for(uint32_t i = 0; i < row_count; ++i) {
        for(uint32_t j = 0; j < col_count; ++j) {
            void * cell_user_data = lv_table_get_cell_user_data(table, i, j);
            lv_free(cell_user_data);
        }
    }
}

lv_obj_add_event_cb(table, table_delete_event_cb, LV_EVENT_DELETE, NULL);
```

Events [#events]

* <ApiLink name="LV_EVENT_VALUE_CHANGED" /> Sent when a new cell is selected with
  keys.

<Callout type="info" title="Further Reading">
  Learn more about [Events](/common-widget-features/events) emitted by all Widgets.

  Learn more about [events](/common-widget-features/events).
</Callout>

Keys [#keys]

The following *Keys* are processed by Table Widgets:

* `LV_KEY_RIGHT/LEFT/UP/DOWN/` Select a cell.

Note that, as usual, the state of <ApiLink name="LV_KEY_ENTER" /> is translated to
`LV_EVENT_PRESSED/PRESSING/RELEASED` etc.

<ApiLink name="lv_table_get_selected_cell" display="lv_table_get_selected_cell(table, &row, &col)" /> can be used to get the
currently selected cell. Row and column will be set to
<ApiLink name="LV_TABLE_CELL_NONE" /> if no cell is selected.

<Callout type="info" title="Further Reading">
  Learn more about [Keys](/main-modules/indev/keypad).
</Callout>

Examples [#examples]

Simple table [#simple-table]

<LvglExample name="lv_example_table_1" path="widgets/table/lv_example_table_1" />

Lightweighted list from table [#lightweighted-list-from-table]

<LvglExample name="lv_example_table_2" path="widgets/table/lv_example_table_2" />

MicroPython [#micropython]

No examples yet.

API [#api]