[English]

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.

Table（表格）是由包含文本的行、列和单元格构建的。

表格对象非常轻量级，因为仅存储文本。没有为各个单元格创建真实的对象，因为它们只是即时绘制出来的。

表格对象默认已经在默认组中（如果已设置）。可以在导航模式下选中整张表，之后进入编辑模式可以在各个单元格之间进行移动选择。

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.

• LV_PART_MAIN 表格的背景使用了所有典型的背景样式属性。

• LV_PART_ITEMS 表格的单元格也使用所有典型的背景样式属性和文本属性。

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

单元格只能存储文本，因此在将数字显示在表格中之前，需要将其转换为文本。

lv_table_set_cell_value(table, row, col, "Content")。 传入的文本由表独立保存，因此它甚至可以是局部变量。这个接口会自动添加新的行和列。

可以在文本中使用换行符，例如 "Value\n60.3"。

Rows and Columns（行和列）

显示原文

To explicitly set number of rows and columns use lv_table_set_row_count(table, row_cnt) and lv_table_set_column_count(table, col_cnt)

要明确设置行数和列数，请使用 lv_table_set_row_count(table, row_cnt) 和 lv_table_set_column_count(table, col_cnt)

Width and Height（宽度和高度）

显示原文

The width of the columns can be set with lv_table_set_column_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.

列的宽度可以通过 lv_table_set_column_width(table, col_id, width) 设置。 Table 对象的总宽度将设置为列宽的总和。

表格对象会根据单元的格样式（字体、填充等）和行数自动计算高度。

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.

单元格可以使用 lv_table_add_cell_ctrl(table, row, col, LV_TABLE_CELL_CTRL_MERGE_RIGHT) 进行水平合并。 要合并更多相邻单元格，请为每个单元格调用此函数。

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.

如果标签的宽度或高度设置为 LV_SIZE_CONTENT 则该尺寸将用于在相应方向上显示整个表格。 例如。lv_obj_set_size(table, LV_SIZE_CONTENT, LV_SIZE_CONTENT) 自动设置表格大小以显示所有列和行。

如果宽度或高度设置为小于“固有”大小的数字，则表格变为可滚动的。

Events（事件）

显示原文

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

See the events of the Base object too.

Learn more about Events（事件）.

• LV_EVENT_VALUE_CHANGED 用选择（通过触摸或按键点击）单元格时发送的事件。

参见 Base object 的事件。

详细了解更多 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（按键）.

以下 按键 由表处理：

• LV_KEY_RIGHT/LEFT/UP/DOWN/ 选中一个单元格。

请注意，与往常一样，LV_KEY_ENTER 的状态被转换为 LV_EVENT_PRESSED/PRESSING/RELEASED 等。

lv_table_get_selected_cell(table, &row, &col) 可用于获取当前选定的单元格。行和列将设置为 LV_TABLE_CELL_NONE 未选择任何单元格。

了解有关 Keys（按键） 的更多信息。

Example

[English]

Simple table

C code  

 View on GitHub

#include "../../lv_examples.h"
#if LV_USE_TABLE && LV_BUILD_EXAMPLES

static void draw_event_cb(lv_event_t * e)
{
    lv_draw_task_t * draw_task = lv_event_get_draw_task(e);
    lv_draw_dsc_base_t * base_dsc = lv_draw_task_get_draw_dsc(draw_task);
    /*If the cells are drawn...*/
    if(base_dsc->part == LV_PART_ITEMS) {
        uint32_t row = base_dsc->id1;
        uint32_t col = base_dsc->id2;

        /*Make the texts in the first cell center aligned*/
        if(row == 0) {
            lv_draw_label_dsc_t * label_draw_dsc = lv_draw_task_get_label_dsc(draw_task);
            if(label_draw_dsc) {
                label_draw_dsc->align = LV_TEXT_ALIGN_CENTER;
            }
            lv_draw_fill_dsc_t * fill_draw_dsc = lv_draw_task_get_fill_dsc(draw_task);
            if(fill_draw_dsc) {
                fill_draw_dsc->color = lv_color_mix(lv_palette_main(LV_PALETTE_BLUE), fill_draw_dsc->color, LV_OPA_20);
                fill_draw_dsc->opa = LV_OPA_COVER;
            }
        }
        /*In the first column align the texts to the right*/
        else if(col == 0) {
            lv_draw_label_dsc_t * label_draw_dsc = lv_draw_task_get_label_dsc(draw_task);
            if(label_draw_dsc) {
                label_draw_dsc->align = LV_TEXT_ALIGN_RIGHT;
            }
        }

        /*Make every 2nd row grayish*/
        if((row != 0 && row % 2) == 0) {
            lv_draw_fill_dsc_t * fill_draw_dsc = lv_draw_task_get_fill_dsc(draw_task);
            if(fill_draw_dsc) {
                fill_draw_dsc->color = lv_color_mix(lv_palette_main(LV_PALETTE_GREY), fill_draw_dsc->color, LV_OPA_10);
                fill_draw_dsc->opa = LV_OPA_COVER;
            }
        }
    }
}

void lv_example_table_1(void)
{
    lv_obj_t * table = lv_table_create(lv_screen_active());

    /*Fill the first column*/
    lv_table_set_cell_value(table, 0, 0, "Name");
    lv_table_set_cell_value(table, 1, 0, "Apple");
    lv_table_set_cell_value(table, 2, 0, "Banana");
    lv_table_set_cell_value(table, 3, 0, "Lemon");
    lv_table_set_cell_value(table, 4, 0, "Grape");
    lv_table_set_cell_value(table, 5, 0, "Melon");
    lv_table_set_cell_value(table, 6, 0, "Peach");
    lv_table_set_cell_value(table, 7, 0, "Nuts");

    /*Fill the second column*/
    lv_table_set_cell_value(table, 0, 1, "Price");
    lv_table_set_cell_value(table, 1, 1, "$7");
    lv_table_set_cell_value(table, 2, 1, "$4");
    lv_table_set_cell_value(table, 3, 1, "$6");
    lv_table_set_cell_value(table, 4, 1, "$2");
    lv_table_set_cell_value(table, 5, 1, "$5");
    lv_table_set_cell_value(table, 6, 1, "$1");
    lv_table_set_cell_value(table, 7, 1, "$9");

    /*Set a smaller height to the table. It'll make it scrollable*/
    lv_obj_set_height(table, 200);
    lv_obj_center(table);

    /*Add an event callback to to apply some custom drawing*/
    lv_obj_add_event_cb(table, draw_event_cb, LV_EVENT_DRAW_TASK_ADDED, NULL);
    lv_obj_add_flag(table, LV_OBJ_FLAG_SEND_DRAW_TASK_EVENTS);
}

#endif

---

Lightweighted list from table

C code  

 View on GitHub

#include "../../lv_examples.h"
#if LV_USE_TABLE && LV_BUILD_EXAMPLES

#define ITEM_CNT 200

static void draw_event_cb(lv_event_t * e)
{
    lv_obj_t * obj = lv_event_get_target(e);

    lv_draw_task_t * draw_task = lv_event_get_draw_task(e);
    lv_draw_dsc_base_t * base_dsc = lv_draw_task_get_draw_dsc(draw_task);
    /*If the cells are drawn...*/
    if(base_dsc->part == LV_PART_ITEMS && lv_draw_task_get_type(draw_task) == LV_DRAW_TASK_TYPE_FILL) {
        /*Draw the background*/
        bool chk = lv_table_has_cell_ctrl(obj, base_dsc->id1, 0, LV_TABLE_CELL_CTRL_CUSTOM_1);
        lv_draw_rect_dsc_t rect_dsc;
        lv_draw_rect_dsc_init(&rect_dsc);
        rect_dsc.bg_color = chk ? lv_theme_get_color_primary(obj) : lv_palette_lighten(LV_PALETTE_GREY, 2);
        rect_dsc.radius = LV_RADIUS_CIRCLE;

        lv_area_t sw_area;
        sw_area.x1 = 0;
        sw_area.x2 = 40;
        sw_area.y1 = 0;
        sw_area.y2 = 24;
        lv_area_t draw_task_area;
        lv_draw_task_get_area(draw_task, &draw_task_area);
        lv_area_align(&draw_task_area, &sw_area, LV_ALIGN_RIGHT_MID, -15, 0);
        lv_draw_rect(base_dsc->layer, &rect_dsc, &sw_area);

        /*Draw the knob*/
        rect_dsc.bg_color = lv_color_white();
        lv_area_t knob_area;
        knob_area.x1 = 0;
        knob_area.x2 = 18;
        knob_area.y1 = 0;
        knob_area.y2 = 18;
        if(chk) {
            lv_area_align(&sw_area, &knob_area, LV_ALIGN_RIGHT_MID, -3, 0);
        }
        else {
            lv_area_align(&sw_area, &knob_area, LV_ALIGN_LEFT_MID, 3, 0);
        }
        lv_draw_rect(base_dsc->layer, &rect_dsc, &knob_area);
    }
}

static void change_event_cb(lv_event_t * e)
{
    lv_obj_t * obj = lv_event_get_target(e);
    uint32_t col;
    uint32_t row;
    lv_table_get_selected_cell(obj, &row, &col);
    bool chk = lv_table_has_cell_ctrl(obj, row, 0, LV_TABLE_CELL_CTRL_CUSTOM_1);
    if(chk) lv_table_clear_cell_ctrl(obj, row, 0, LV_TABLE_CELL_CTRL_CUSTOM_1);
    else lv_table_add_cell_ctrl(obj, row, 0, LV_TABLE_CELL_CTRL_CUSTOM_1);
}

/**
 * A very light-weighted list created from table
 */
void lv_example_table_2(void)
{
    /*Measure memory usage*/
    lv_mem_monitor_t mon1;
    lv_mem_monitor(&mon1);

    uint32_t t = lv_tick_get();

    lv_obj_t * table = lv_table_create(lv_screen_active());

    /*Set a smaller height to the table. It'll make it scrollable*/
    lv_obj_set_size(table, LV_SIZE_CONTENT, 200);

    lv_table_set_column_width(table, 0, 150);
    lv_table_set_row_count(table, ITEM_CNT); /*Not required but avoids a lot of memory reallocation lv_table_set_set_value*/
    lv_table_set_column_count(table, 1);

    /*Don't make the cell pressed, we will draw something different in the event*/
    lv_obj_remove_style(table, NULL, LV_PART_ITEMS | LV_STATE_PRESSED);

    uint32_t i;
    for(i = 0; i < ITEM_CNT; i++) {
        lv_table_set_cell_value_fmt(table, i, 0, "Item %"LV_PRIu32, i + 1);
    }

    lv_obj_align(table, LV_ALIGN_CENTER, 0, -20);

    /*Add an event callback to to apply some custom drawing*/
    lv_obj_add_event_cb(table, draw_event_cb, LV_EVENT_DRAW_TASK_ADDED, NULL);
    lv_obj_add_event_cb(table, change_event_cb, LV_EVENT_VALUE_CHANGED, NULL);
    lv_obj_add_flag(table, LV_OBJ_FLAG_SEND_DRAW_TASK_EVENTS);

    lv_mem_monitor_t mon2;
    lv_mem_monitor(&mon2);

    size_t mem_used = mon1.free_size - mon2.free_size;

    uint32_t elaps = lv_tick_elaps(t);

    lv_obj_t * label = lv_label_create(lv_screen_active());
    lv_label_set_text_fmt(label, "%"LV_PRIu32" items were created in %"LV_PRIu32" ms\n"
                          "using %zu bytes of memory",
                          (uint32_t)ITEM_CNT, elaps, mem_used);

    lv_obj_align(label, LV_ALIGN_BOTTOM_MID, 0, -10);

}

#endif

---

MicroPython

No examples yet.

API

lv_types.h

lv_table.h

lv_api_map_v8.h