第十九章 表格部件(lv_table)

       在LVGL中，表格部件是由一个个单元格组成的，该部件经过了专门的优化，它非常轻量化。较为遗憾的是：表格部件的单元格中只能存放文本形式的内容，不支持存放其他任何类型的对象或者部件。

       本章节将分为以下几个小节：

       19.1 表格部件的组成

       19.2 表格部件的相关知识

       19.3 表格部件的API函数

       19.4 表格部件的实验

        19.1 表格部件的组成

       表格部件由两个部分组成：主体背景LV_PART_MAIN和单元格LV_PART_ITEMS，关于部件样式设置的内容，请大家参考6.4.4章节。

        19.2 表格部件的相关知识

       19.2.1 设置单元格的值

       在默认的情况下，用户创建出表格部件，该表格中并没有任何的内容，如果我们想在某个单元格中添加文本，则可调用lv_table_set_cell_value函数。

       接下来，我们以简单示例来理解单元格值的设置，示例代码如下所示：

void lv_mainstart(void)
{
    /* 创建表格部件 */
    lv_obj_t* table = lv_table_create(lv_scr_act());
    /* 设置表格部件的单元格文本（第0行，第0列） */
    lv_table_set_cell_value(table, 0, 0, "123");
    lv_obj_center(table);
}

       在上述源码中，我们先调用lv_table_create函数创建表格部件，然后调用lv_table_set_cell_value函数，设置指定单元格的文本：123，值得注意的是，该函数的第二、三个形参分别代表行和列（从0开始）。示例代码可以在PC模拟器中运行，效果图如下所示：

图19.2.1.1 设置单元格文本

       19.2.2 行和列的设置

       在默认的情况下，用户创建出表格部件，该部件只拥有一个单元格，如果我们需要设置单元格的行数和列数，可调用lv_table_set_row_cnt和lv_table_set_col_cnt函数。

       接下来，我们以简单示例来理解单元格的行、列设置，示例代码如下所示：

void lv_mainstart(void)
{
    /* 创建table部件 */
    lv_obj_t* table = lv_table_create(lv_scr_act());
    /* 设置table部件的单元格文本 */
    lv_table_set_cell_value(table, 0, 0, "123");
    /*设置行数 */
    lv_table_set_row_cnt(table,2);
    /*设置列数 */
    lv_table_set_col_cnt(table,2);
    lv_obj_center(table);
}

       在上述源码中，我们调用lv_table_set_row_cnt和lv_table_set_col_cnt函数，分别设置表格部件的行数（2行）和列数（2列），示例代码可以在PC模拟器中运行，效果图如下所示：

图19.2.2.1 设置表格部件的行列数

       由上图可知，文本“123”所在的行和列分别为0、0。接下来，我们以一个示意图来理解表格部件的行列分布，如下图所示：

图19.2.2.2 表格部件的行列分布

       由上图可知：行和列的编号都是从0开始的，假设我们需要设置cell3的文本，其对应的行和列分别为1、1。

       19.2.3 宽度和高度的设置

       在表格部件中，用户可通过lv_table_set_col_width函数设置某一列的宽度，而单元格的高度则根据单元格样式（字体、填充等）和行数自动计算出来的。

       19.2.4 合并单元格

       合并单元格是指将指定的连续单元区域合并为1个单元格，示意图如下所示：

图19.2.4.1 table部件单元格合并示意图

       由上图可知：如果a和b的单元格发生合并，合并之后的单元格归a单元格所有，而b单元格将被删除。注意：在表格部件中，某一个单元格只能和右边的单元格进行合并，不能垂直合并单元格。用户需要合并单元格，可调用lv_table_add_cell_ctrl函数。

        19.3 表格部件的API函数

       LVGL官方提供了一些与表格部件相关API，如下表所示：

表19.3.1.1 表格部件相关的API函数

       接下来，我们介绍LVGL表格部件常用的API函数：

        1. lv_table_create函数

       创建表格部件，该函数原型如下所示：

lv_obj_t *lv_table_create(lv_obj_t *parent);

       该函数的形参，如下表所示：

表19.3.2 lv_table_create函数形参描述

       返回值：指向表格部件的指针。

        2. lv_table_set_cell_value函数

       设置单元格的值，该函数原型如下所示：

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

       该函数的形参，如下表所示：

表19.3.3 lv_table_set_cell_value函数形参描述

       返回值：无。

        3. lv_table_set_cell_value_fmt函数

       设置单元格的值（格式化输入），该函数原型如下所示：

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

       该函数的形参，如下表所示：

表19.3.4 lv_table_set_cell_value_fmt函数形参描述

       返回值：无。

        4. lv_table_set_row_cnt函数

       设置行数，该函数原型如下所示：

void lv_table_set_row_cnt(lv_obj_t *obj, uint16_t row_cnt);

       该函数的形参，如下表所示：

表19.3.5 lv_table_set_row_cnt函数形参描述

       返回值：无。

        5. lv_table_set_col_cnt函数

       设置列数，该函数原型如下所示：

void lv_table_set_col_cnt(lv_obj_t *obj, uint16_t row_cnt);

       该函数的形参，如下表所示：

表19.3.6 lv_table_set_col_cnt函数形参描述

       返回值：无。

        6. lv_table_set_col_width函数

       设置列的宽度，该函数原型如下所示：

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

       该函数的形参，如下表所示：

表19.3.7 lv_table_set_col_width函数形参描述

       返回值：无。

        19.4 表格部件的实验

       19.4.1 硬件设计

       1. 例程功能

       本实验主要测试表格部件API函数的使用，实验现象：开机后，屏幕上显示一个标题和表格。与此同时，LED0闪烁，提示系统正在运行。

       该实验的完整源码，请参考《LVGL例程16 lv_table(表格)》例程，路径：A盘→4，程序源码 →3，扩展例程 →3，LVGL例程。

       19.4.2 软件设计

       19.4.2.1 程序流程图

       本实验的程序流程图，如下图所示：

图19.4.2.1.1 表格部件实验流程图

       19.4.2.2 程序解析

       关于LVGL的用户代码，我们都是在lv_mainstart.c文件中编写的，本实验的源码如下所示： 

/**************************** 第一部分 开始 ****************************/
/**
 * @brief  LVGL演示
 * @param  无
 * @return 无
 */
void lv_mainstart(void)
{
    lv_example_table();
}
/**************************** 第一部分 结束 ****************************/
 
/**************************** 第二部分 开始 ****************************/
/**
 * @brief  表格实例
 * @param  无
 * @return 无
 */
static void lv_example_table(void)
{
    /* 表格 */
    lv_obj_t *table = lv_table_create(lv_scr_act());       /* 创建表格 */
    lv_obj_set_size(table, 190, 172);                      /* 设置表格总的高度 */
    lv_obj_center(table);                                  /* 设置位置 */
 
    /* 设置第1列单元格内容（名称） */
    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");
 
    /* 设置第2列单元格内容（价格） */
    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_col_width(table, 0, 90);
    lv_table_set_col_width(table, 1, 90);
}
/**************************** 第二部分 结束 ****************************/

       上述源码可分为以下两个部分：

       ① lv_mainstart接口函数。在该函数中，我们调用了表格部件相关的示例函数；

       ② 价格表的实现。我们先创建标题标签并设置其内容，然后创建表格并添加两行单元格的内容，最后再设置单元格的宽度。

       19.4.3 下载验证

       把工程编译并下载到我们的开发板中，运行效果如下图所示：

图19.4.3.1 表格部件实验