第二十一章 列表部件(lv_list)

       列表部件可用于展现多个选项，它在UI设计中广泛应用，例如：文件管理系统、设置菜单、功能菜单，等等。

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

       21.1 列表部件的组成

       21.2 列表部件的相关知识

       21.3 列表部件API函数

       21.4 列表部件实验

        21.1 列表部件的组成

       列表部件由两个部分组成:

       ① LV_PART_MAIN：主体背景；

       ② LV_PART_SCROLLBAR：滚动条。

       关于部件样式设置的内容，请大家参考6.4.4章节。

        21.2 列表部件的相关知识

       21.2.1 添加列表按钮

       在默认的情况下，列表部件被创建出来后，只有一个矩形背景框，并没有任何的文本和按钮，用户需要自行往列表里面添加按钮，添加按钮的相关函数为lv_list_add_btn。

       接下来，我们以简单示例来理解列表按钮的添加，示例代码如下所示：

void lv_mainstart(void)
{
    lv_obj_t *list = lv_list_create(lv_scr_act());     /* 创建列表 */
    lv_obj_set_width(list, 200);                       /* 设置列表宽度 */
    lv_obj_set_height(list, 150);                      /* 设置列表高度 */
    lv_obj_center(list);
 
    lv_obj_t *btn;
    btn = lv_list_add_btn(list, LV_SYMBOL_FILE, "New");        /* 添加按钮 */
    btn = lv_list_add_btn(list, LV_SYMBOL_DIRECTORY, "Open");  /* 添加按钮 */
}

       在上述的源码中，我们先创建列表部件，然后调用lv_list_add_btn函数添加列表按钮，该函数的第二个形参用于设置图标，第三个形参用于设置按钮的文本。示例代码可以在PC模拟器中运行，效果图如下所示：

图21.2.1.1 添加列表按钮

       上图中，我们添加了两个列表按钮，这两个列表按钮都是具有图标和文本的，如果用户不想显示图标或者文本，则在对应的形参中填入NULL即可。

       21.2.2 设置列表文本

       列表文本主要用于一类按钮的功能提示或按钮分类。用户需要添加列表文本，可调用lv_list_add_text函数进行设置，该函数有两个形参，第一个形参指向列表对象，第二个形参表示设置的文本。

       接下来，我们以简单示例来理解列表文本的设置，示例代码如下所示：

void lv_mainstart(void)
{
    lv_obj_t* list = lv_list_create(lv_scr_act());     /* 创建列表 */
    lv_obj_set_width(list, 200);                       /* 设置列表宽度 */
    lv_obj_set_height(list, 150);                      /* 设置列表高度 */
    lv_obj_center(list);
 
lv_obj_t* btn;
lv_list_add_text(list, "File");        /* 列表添加标签 */                                               
    btn = lv_list_add_btn(list, LV_SYMBOL_FILE, "New");      /* 添加按钮 */
    btn = lv_list_add_btn(list, LV_SYMBOL_DIRECTORY, "Open"); /* 添加按钮 */
}

       在上述源码中，我们创建了列表并为其添加按钮，于此同时，调用lv_list_add_text函数添加列表文本。示例代码可以在PC模拟器中运行，效果图如下所示：

图21.2.1.2 添加列表文本

        21.3 列表部件API函数

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

表21.3.1 列表部件相关的API函数

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

       1. lv_list_create函数

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

lv_obj_t *lv_list_create(lv_obj_t *parent);

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

表21.3.2 lv_list_create函数形参描述

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

       2. lv_list_add_text函数

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

lv_obj_t *lv_list_add_text( lv_obj_t *list, const char *txt);

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

表21.3.3 lv_list_add_text函数形参描述

       返回值：指向文本的指针。

       3. lv_list_add_btn函数

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

lv_obj_t *lv_list_add_btn( lv_obj_t *list, const char *icon, const char *txt);

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

表21.3.4 lv_list_add_btn函数形参描述

       返回值：指向按钮的指针。

       4. lv_list_get_btn_text函数

       获取按下的按钮文本，该函数原型如下所示：

const char *lv_list_get_btn_text(lv_obj_t *list, lv_obj_t *btn);

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

表21.3.5 lv_list_get_btn_text函数形参描述

       返回值：指向文本的指针。

        21.4 列表部件实验

       21.4.1 硬件设计

       1. 例程功能

       本实验主要测试列表部件API函数的使用，实验现象：开机后，屏幕上显示一个列表，用户可以通过KEY0、KEY1切换当前选项。与此同时，LED0闪烁，提示系统正在运行。

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

       21.4.2 软件设计

       21.4.2.1 程序流程图

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

图21.4.2.1.1 列表部件实验流程图

       21.4.2.2 程序解析

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

/**************************** 第一部分 开始 ****************************/
/**
 * @brief  LVGL演示
 * @param  无
 * @return 无
 */
void lv_mainstart(void)
{
    lv_example_list();
}
/**************************** 第一部分 结束 ****************************/
 
/**************************** 第二部分 开始 ****************************/
/**
 * @brief  列表示例
 * @param  无
 * @return 无
 */
static void lv_example_list(void)
{
    lv_group_t *g = lv_group_create();
    lv_group_set_default(g);
    lv_indev_set_group(indev_keypad, g);
    
    /* 创建列表 */
list = lv_list_create(lv_scr_act());
/* 设置列表宽度 */
lv_obj_set_width(list, lv_obj_get_width(lv_scr_act()) * 0.8);  
/* 设置列表高度 */
lv_obj_set_height(list, lv_obj_get_height(lv_scr_act()) * 0.9); 
/* 设置列表的位置 */
lv_obj_center(list);                   
/* 设置字体 */
    lv_obj_set_style_text_font(list, &lv_font_montserrat_16, LV_PART_MAIN); 
 
    /* 为列表添加按钮 */
    lv_list_add_text(list, "File");                       /* 添加列表文本 */
    lv_list_add_btn(list, LV_SYMBOL_FILE, "New");         /* 添加按钮 */
    lv_list_add_btn(list, LV_SYMBOL_DIRECTORY, "Open");   /* 添加按钮 */
    lv_list_add_btn(list, LV_SYMBOL_SAVE, "Save");        /* 添加按钮 */
    lv_list_add_btn(list, LV_SYMBOL_CLOSE, "Delete");     /* 添加按钮 */
    lv_list_add_btn(list, LV_SYMBOL_EDIT, "Edit");        /* 添加按钮 */
    lv_list_add_text(list, "Connectivity");               /* 添加列表文本 */
    lv_list_add_btn(list, LV_SYMBOL_BLUETOOTH, "Bluetooth");  /* 添加按钮 */
    lv_list_add_btn(list, LV_SYMBOL_GPS, "Navigation");       /* 添加按钮 */
    lv_list_add_btn(list, LV_SYMBOL_USB, "USB");              /* 添加按钮 */
    lv_list_add_btn(list, LV_SYMBOL_BATTERY_FULL, "Battery"); /* 添加按钮 */
    lv_list_add_text(list, "Exit");                           /* 添加列表文本 */
    lv_list_add_btn(list, LV_SYMBOL_OK, "Apply");             /* 添加按钮 */
    lv_list_add_btn(list, LV_SYMBOL_CLOSE, "Close");          /* 添加按钮 */
}
/**************************** 第二部分 结束 ****************************/

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

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

       ② 列表的实现。我们创建列表部件，并为列表添加多个按钮。

       21.4.3 下载验证

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

图21.4.3.1 列表部件实验