第十六章 滚轮部件(lv_roller)

       滚轮部件可展现多个选项，用户可以通过滚动的形式，从这些选项中选择所需的内容。在用户界面设计中，该部件常用于设置时间、日期等。

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

       16.1 滚轮部件的组成

       16.2 滚轮部件的相关知识

       16.3 滚轮部件的API函数

       16.4 滚轮部件的实验

        16.1 滚轮部件的组成

       滚轮部件由两个部分组成：主体背景和所选文本，示意图如下：

图16.1.1 滚轮部件的组成部分

       各组成部分的相关枚举如下所示：

       ① 主体背景LV_PART_MAIN；

       ② 所选文本LV_PART_SELECTED。

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

        16.2 滚轮部件的相关知识

       16.2.1 添加选项和滚轮模式

       1. 添加选项

       默认情况下，滚轮部件创建出来后，其并不具备任何选项，用户需要添加选项，可调用lv_roller_set_options函数。

       2. 滚轮模式：

       滚轮部件具有两种滚动模式，如下所示：

       ①  LV_ROLLER_MODE_INFINITE：循环滚动模式；

       ② LV_ROLLER_MODE_NORMAL：正常模式。

       如果滚轮部件为LV_ROLLER_MODE_INFINITE模式，此时，用户滚动选项，当选项滚动到最后一个，若继续滚动，其将回到第一个选项（循环滚动）；如果滚轮部件为LV_ROLLER_MODE_NORMAL模式，则滚轮部件的最后一个和第一个选项不能循环切换，这两种模式的示意图如下：

图16.2.1.1 滚轮部件模式示意图

       默认情况下，滚轮部件的所选项为第一个添加的选项，如果用户想改变所选项，可调用lv_roller_set_selected函数进行设置。

       16.2.2 获取选项索引和文本

       如果用户想获取当前选中选项的索引，可调用lv_roller_get_selected函数；如果用户想获取当前选中选项的文本，可调用lv_roller_get_selected_str函数。

       16.2.3 可见选项的数量

       滚轮部件中存在多个选项，用户可以调用lv_roller_set_visible_row_count函数，设置默认显示的选项数量。

       接下来，我们以简单示例来理解可见选项数量的设置，示例代码如下所示：

/* 滚轮选项 */
static const char* roller_options = "option 0\n"
                                    "option 1\n"
                                    "option 2\n"
                                    "option 3\n"
                                    "option 4\n"
                                    "option 5\n"
                                    "option 6\n"
                                    "option 7";
/**
 * @brief  LVGL演示
 * @param  无
 * @return 无
 */
void lv_mainstart(void)
{
/* 定义并创建滚轮 */
lv_obj_t* roller = lv_roller_create(lv_scr_act());
/* 滚轮添加选项并设置无限模式 */
lv_roller_set_options(roller, roller_options, LV_ROLLER_MODE_NORMAL); 
/* 设置滚轮宽度 */
lv_obj_set_width(roller, 110);
/* 设置滚轮可见选项个数 */
    lv_roller_set_visible_row_count(roller, 3); 
}

       上述源码中，我们调用了lv_roller_set_visible_row_count函数，设置滚轮的可见选项个数为3，示例代码可以在PC模拟器中运行，效果图如下所示：

表16.3.1.1 滚轮部件相关的API函数

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

        1. lv_roller_create函数

       创建滚轮部件，该函数原型如下所示：

lv_obj_t *lv_roller_create(lv_obj_t *parent);

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

表16.3.2 lv_roller_create函数形参描述

       返回值：滚轮对象。

        2. lv_roller_set_options函数

       设置滚轮的选项，该函数原型如下所示：

void lv_roller_set_options(lv_obj_t *obj, const char *options, 
lv_roller_mode_t mode);

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

表16.3.3 lv_roller_set_options函数形参描述

       返回值：无。

        3. lv_roller_set_selected函数

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

void lv_roller_set_selected(lv_obj_t *obj, uint16_t sel_opt, 
lv_anim_enable_t anim);

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

表16.3.4 lv_roller_set_selected函数形参描述

       返回值：无。

        4. lv_roller_set_visible_row_count函数

       设置可见选项数量，该函数原型如下所示：

void lv_roller_set_visible_row_count(lv_obj_t *obj, uint8_t row_cnt);

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

表16.3.5 lv_roller_set_visible_row_count函数形参描述

       返回值：无。

        5. lv_roller_get_selected函数

       获取所选选项的索引，该函数原型如下所示：

uint16_t lv_roller_get_selected(const lv_obj_t *obj);

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

表16.3.6 lv_roller_get_selected函数形参描述

       返回值：无。

        6. lv_roller_get_selected_str函数

       获取当前所选项的文本，该函数原型如下所示：

void lv_roller_get_selected_str(const lv_obj_t *obj, char *buf, 
uint32_t buf_size);

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

表16.3.7 lv_roller_get_selected_str函数形参描述

       返回值：无。

        7. lv_roller_get_options函数

       获取滚轮的选项，该函数原型如下所示：

const char *lv_roller_get_options(const lv_obj_t *obj);

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

表16.3.8 lv_roller_get_options函数形参描述

       返回值：选项内容，例如:“Option1 \ nOption2 \ nOption3”。

        16.4 滚轮部件的实验

       16.4.1 硬件设计

       1. 例程功能

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

       该实验的完整源码，请参考《LVGL例程13 lv_roller(滚轮)》例程，路径：A盘→4，程序源码 →3，扩展例程 →3，LVGL例程。

       16.4.2 程序设计

       16.4.2.1 程序流程图

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

图16.4.2.1.1 滚轮部件实验流程图

       16.4.2.2 程序解析

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

/**************************** 第一部分 开始 ****************************/
/**
 * @brief  LVGL演示
 * @param  无
 * @return 无
 */
void lv_mainstart(void)
{
    lv_group_t *g = lv_group_create();
    lv_group_set_default(g);
    lv_indev_set_group(indev_keypad, g);
    
    lv_example_roller();               /* 滚轮 */
}
/**************************** 第一部分 结束 ****************************/
/**************************** 第二部分 开始 ****************************/
/**
 * @brief  滚轮示例
 * @param  无
 * @return 无
 */
static void lv_example_roller(void)
{
/* 创建温度设置滚轮 */
lv_obj_t *temp_roller = lv_roller_create(lv_scr_act());      
/* 滚轮添加选项、设置正常模式 */
lv_roller_set_options(temp_roller, temp_options, LV_ROLLER_MODE_NORMAL); 
/* 设置滚轮位置 */
lv_obj_align(temp_roller, LV_ALIGN_CENTER, 0, 5);  
/* 设置滚轮宽度 */
lv_obj_set_width(temp_roller, 80);   
/* 设置滚轮字体 */
lv_obj_set_style_text_font(temp_roller, &lv_font_montserrat_22, 0);  
/* 设置滚轮可见选项个数 */
lv_roller_set_visible_row_count(temp_roller, 3); 
/* 设置滚轮当前所选项 */
    lv_roller_set_selected(temp_roller, 2, LV_ANIM_OFF);       
 
    lv_obj_t *label = lv_label_create(lv_scr_act());      /* 创建标签 */
    lv_label_set_text(label, "TEMP");                     /* 设置文本内容 */
lv_obj_set_style_text_font(label, &lv_font_montserrat_22, 0);  /* 设置字体 */
lv_obj_align_to(label,temp_roller,LV_ALIGN_OUT_TOP_MID,0,-15 );/* 设置位置 */
}
/**************************** 第二部分 结束 ****************************/

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

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

       ② 滚轮的实现。

       16.4.3 下载验证

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

图16.4.3.1 滚轮部件实验