列表部件

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

列表部件的组成

• 列表部件由两个部分组成:
  • LV_PART_MAIN：主体背景；
  • LV_PART_SCROLLBAR：滚动条。

添加列表按钮

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

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

  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 函数添加列表按钮，该函数的第二个形参用于设置图标，第三个形参用于设置按钮的文本。示例代码运行效果图如下所示：

  

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

设置列表文本

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

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

  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_list_add_text(list, "File");                             /* 设置列表文本 */
  
  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_text 函数添加列表文本。示例代码运行效果图如下所示：

  

列表部件 API 函数

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

  函数	描述
  lv_list_create()	创建列表部件
  lv_list_add_text()	添加列表文本
  lv_list_add_btn()	添加列表按钮
  lv_list_get_btn_text()	获取按下的按钮文本

代码实战

• 要求：开机后，屏幕上显示一个列表和标签，当用户按下列表中的按钮时，该按钮的文本将会被更新到标签中。

• 首先创建左右两侧背景框，没啥用，仅仅为了美观，代码实现如下：

  /* 创建左侧矩形背景 */
  lv_obj_t* obj_left = lv_obj_create(lv_scr_act());                       /* 创建一个基础对象 */
  lv_obj_set_width(obj_left, with * 0.7);                                 /* 设置宽度 */
  lv_obj_set_height(obj_left, height * 0.9);                              /* 设置高度 */
  lv_obj_align(obj_left, LV_ALIGN_LEFT_MID, 5, 0);                        /* 设置位置 */
  lv_obj_update_layout(obj_left);                                         /* 手动更新物体的参数 */
  
  /* 创建右侧矩形背景 */
  lv_obj_t* obj_right = lv_obj_create(lv_scr_act());                      /* 创建一个基础对象 */
  lv_obj_set_width(obj_right, with - lv_obj_get_width(obj_left) - 15);    /* 设置宽度 */
  lv_obj_set_height(obj_right, lv_obj_get_height(obj_left));              /* 设置高度 */
  lv_obj_align_to(obj_right, obj_left, LV_ALIGN_OUT_RIGHT_MID, 5, 0);     /* 设置位置 */
  lv_obj_update_layout(obj_right);                                        /* 手动更新物体的参数 */

• 实现右侧标签，用于显示点击后的按钮文本，代码如下：

  list_label = lv_label_create(obj_right);                                        /* 创建标签 */
  lv_obj_set_width(list_label, lv_obj_get_width(obj_right) - 13);                 /* 设置标签的宽度 */ 
  lv_obj_align(list_label, LV_ALIGN_TOP_MID, 0, 5);                               /* 设置标签位置 */
  lv_obj_update_layout(list_label);                                               /* 手动更新标签的参数 */
  lv_obj_set_style_text_align(list_label, LV_TEXT_ALIGN_CENTER, LV_PART_MAIN);    /* 设置标签文本对齐方式   */
  lv_label_set_text(list_label, "New");                                           /* 设置标签文本 */
  lv_obj_set_style_text_font(list_label, &lv_font_montserrat_24, LV_PART_MAIN);   /* 设置标签文本字体 */

• 开始关键部分代码，创建列表，并添加多个按钮，代码实现如下：

  list = lv_list_create(lv_scr_act());                                            /* 创建列表 */
  lv_obj_set_width(list, lv_obj_get_width(obj_left) * 0.8);                       /* 设置列表宽度 */
  lv_obj_set_height(list, lv_obj_get_height(obj_left) * 0.9);                     /* 设置列表高度 */
  lv_obj_align_to(list, obj_left, LV_ALIGN_CENTER, 0, 0);                         /* 设置列表的位置 */
  lv_obj_set_style_text_font(list, &lv_font_montserrat_24, LV_PART_MAIN);         /* 设置字体 */
  
  lv_obj_t* btn;
  lv_list_add_text(list, "File");                                                 /* 添加列表文本 */
  btn = lv_list_add_btn(list, LV_SYMBOL_FILE, "New");                             /* 添加按钮 */
  lv_obj_add_event_cb(btn, list_btn_event_cb, LV_EVENT_CLICKED, NULL);            /* 添加按钮回调 */
  btn = lv_list_add_btn(list, LV_SYMBOL_DIRECTORY, "Open");                       /* 添加按钮 */
  lv_obj_add_event_cb(btn, list_btn_event_cb, LV_EVENT_CLICKED, NULL);            /* 添加按钮回调 */
  btn = lv_list_add_btn(list, LV_SYMBOL_SAVE, "Save");                            /* 添加按钮 */
  lv_obj_add_event_cb(btn, list_btn_event_cb, LV_EVENT_CLICKED, NULL);            /* 添加按钮回调 */
  btn = lv_list_add_btn(list, LV_SYMBOL_CLOSE, "Delete");                         /* 添加按钮 */
  lv_obj_add_event_cb(btn, list_btn_event_cb, LV_EVENT_CLICKED, NULL);            /* 添加按钮回调 */
  btn = lv_list_add_btn(list, LV_SYMBOL_EDIT, "Edit");                            /* 添加按钮 */
  lv_obj_add_event_cb(btn, list_btn_event_cb, LV_EVENT_CLICKED, NULL);            /* 添加按钮回调 */
  lv_list_add_text(list, "Connectivity");                                         /* 添加列表文本 */
  btn = lv_list_add_btn(list, LV_SYMBOL_BLUETOOTH, "Bluetooth");                  /* 添加按钮 */
  lv_obj_add_event_cb(btn, list_btn_event_cb, LV_EVENT_CLICKED, NULL);            /* 添加按钮回调 */
  btn = lv_list_add_btn(list, LV_SYMBOL_GPS, "Navigation");                       /* 添加按钮 */
  lv_obj_add_event_cb(btn, list_btn_event_cb, LV_EVENT_CLICKED, NULL);            /* 添加按钮回调 */
  btn = lv_list_add_btn(list, LV_SYMBOL_USB, "USB");                              /* 添加按钮 */
  lv_obj_add_event_cb(btn, list_btn_event_cb, LV_EVENT_CLICKED, NULL);            /* 添加按钮回调 */
  btn = lv_list_add_btn(list, LV_SYMBOL_BATTERY_FULL, "Battery");                 /* 添加按钮 */
  lv_obj_add_event_cb(btn, list_btn_event_cb, LV_EVENT_CLICKED, NULL);            /* 添加按钮回调 */
  lv_list_add_text(list, "Exit");                                                 /* 添加列表文本 */
  btn = lv_list_add_btn(list, LV_SYMBOL_OK, "Apply");                             /* 添加按钮 */
  lv_obj_add_event_cb(btn, list_btn_event_cb, LV_EVENT_CLICKED, NULL);            /* 添加按钮回调 */
  btn = lv_list_add_btn(list, LV_SYMBOL_CLOSE, "Close");                          /* 添加按钮 */
  lv_obj_add_event_cb(btn, list_btn_event_cb, LV_EVENT_CLICKED, NULL);            /* 添加按钮回调 */

• 绑定列表按钮回调函数,当某个列表按钮被按下时，将触发事件回调，在事件回调函数中，我们获取被按下按钮的文本内容，并将其更新到当前选项文本标签中。代码实现如下：

  lv_obj_add_event_cb(btn, list_btn_event_cb, LV_EVENT_CLICKED, NULL);            /* 添加按钮回调 */
  
  
  lv_obj_t* list_label = NULL;
  lv_obj_t* list = NULL;
  
  static void list_btn_event_cb(lv_event_t *e)
  {
      lv_obj_t *list_btn = lv_event_get_target(e);                                    /* 获取触发源 */
      lv_label_set_text(list_label, lv_list_get_btn_text(list, list_btn));            /* 获取按钮文本并显  示 */
      lv_obj_add_state(list_btn, LV_STATE_FOCUS_KEY);                                 /* 添加状态（聚焦）   */
  }

• 完整代码见：Demo_list.c

• 运行效果如下图所示：