第十七章 滑块部件(lv_slider)

       滑块部件和进度条部件类似，它比进度条多了一个旋钮，该旋钮可以让用户手动设置当前值。值得注意的是，进度条部件的大部分属性设置逻辑在滑块部件中都适用，比如设置当前值、动画时间、范围值，等等。

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

       17.1 滑块部件的组成

       17.2 滑块部件的相关知识

       17.3 滑块部件的API函数

       17.4 滑块部件的实验

        17.1 滑块部件的组成

       滑块部件由三个部分组成：主体背景、指示器和旋钮，示意图如下：

图17.1.1 滑块部件组成部分

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

        17.2 滑块部件的相关知识

       17.2.1 设置滑块当前值和范围值

       默认情况下，滑块部件被创建出来后，它的当前值是0，范围值是0~100。如果用户需要设置当前值，可调用lv_slider_set_value函数；如果用户需要设置范围值，可以调用lv_slider_set_range函数。

       接下来，我们以简单示例来理解当前值和范围值的设置，示例代码如下所示：

void lv_mainstart(void)
{
    /* 创建slider部件 */
    lv_obj_t* slider = lv_slider_create(lv_scr_act());
    /* 设置slider部件范围值 */
    lv_slider_set_range(slider,0,255);
    /* 设置slider部件当前值 */
    lv_slider_set_value(slider,100, LV_ANIM_ON);
    /* 设置slider部件居中 */
    lv_obj_center(slider);
}

       在上述源码中，我们先调用lv_slider_create函数，创建滑块部件，然后调用lv_slider_set_range函数，设置滑块部件的范围值，最后调用lv_slider_set_value函数，设置滑块部件的当前值。示例代码可以在PC模拟器中运行，效果图如下所示： 

图17.2.1.1 设置当前值和范围值

       17.2.2 设置滑块部件的模式

       除了默认的模式之外，滑块部件还可以配置为以下两种拓展模式：

       ① LV_SLIDER_MODE_SYMMETRICAL：无论当前值是正数还是负数，指示器始终从零绘制到当前值。

       ② LV_SLIDER_MODE_RANGE：允许调用lv_bar_set_start_value函数设置起始值，该起始值必须小于结束值。

       用户需要设置滑块部件的模式，可调用以下函数：

lv_slider_set_mode(slider, LV_SLIDER_MODE_…);  /* 设置slider部件的模式*/

       接下来，我们以简单示例来理解滑块模式的设置，示例代码如下所示：

void lv_mainstart(void)
{
    /* 创建slider部件 */
    lv_obj_t* slider = lv_slider_create(lv_scr_act());
    /* 设置slider部件模式：始终从0开始绘制指示器 */
    lv_slider_set_mode(slider, LV_SLIDER_MODE_SYMMETRICAL);
    /* 设置slider部件数值范围 */
    lv_slider_set_range(slider,-100,100);
    lv_obj_center(slider);
 
    /* 创建slider1部件 */
    lv_obj_t* slider1 = lv_slider_create(lv_scr_act());
    /* 创建slider1部件模式：允许指定起始值 */
    lv_slider_set_mode(slider1, LV_SLIDER_MODE_RANGE);
    /* 创建slider1部件起始值 */
    lv_bar_set_start_value(slider1,0,LV_ANIM_OFF);
    /* 创建slider1部件数值范围 */
    lv_slider_set_range(slider1, -100, 100);
    lv_obj_align_to(slider1, slider,LV_ALIGN_OUT_BOTTOM_MID,0,30);
}

       在上述源码中，我们创建了两个滑块部件（slider和slider1），并将它们分别设置为LV_SLIDER_MODE_SYMMETRICAL和LV_SLIDER_MODE_RANGE模式，除此之外，我们还将两个部件的数值范围为-100~100，slider1部件的起始值设置为。示例代码可以在PC模拟器中运行，效果图如下所示：

图21.2.2.1 设置不同模式的滑块部件

       由上图可知，在LV_SLIDER_MODE_SYMMETRICAL模式下，滑块始终是从0点开始绘制指示器；而在LV_SLIDER_MODE_RANGE模式下，滑块部件可以改变起始值，值得注意的是，起始值必须小于结束值（当前值）。

       17.2.3 禁用单击

       默认情况下，用户可以通过拖动旋钮或者单击滑块的方式来调整指示器位置，而后者可能会导致当前值的突变，这在某些情景下是不允许出现的。如果用户想禁用单击调整当前值，可调用以下函数：

lv_obj_add_flag(slider, LV_OBJ_FLAG_ADV_HITTEST);  /* 禁用单击调整当前值 */

        17.3 滑块部件的API函数

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

表17.3.1.1 滑块部件相关的API函数

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

       1. lv_slider_create函数

       创建滑块部件，该函数原型如下所示：

lv_obj_t *lv_slider_create(lv_obj_t *parent);

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

表17.3.1.2 lv_slider_create函数形参描述

       返回值：滑块部件的指针。

       2. lv_slider_set_value函数

       设置滑块部件的当前值，该函数原型如下所示：

static inline void lv_slider_set_value(lv_obj_t *obj, int32_t value,
lv_anim_enable_t anim);

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

表17.3.1.3 lv_slider_set_value函数形参描述

       返回值：无。

       3. lv_slider_set_range函数

       设置滑块部件的范围值，该函数原型如下所示：

static inline void lv_slider_set_range(lv_obj_t *obj,int32_t min, int32_t max);

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

表17.3.4 lv_slider_set_range函数形参描述

       返回值：无。

       4. lv_slider_set_mode函数

       设置滑块的模式，该函数原型如下所示：

static inline void lv_slider_set_mode(lv_obj_t *obj, lv_slider_mode_t mode);

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

表17.3.1.5 lv_slider_set_mode函数形参描述

       返回值：无。

        17.4 滑块部件的实验

       17.4.1 硬件设计

       1. 例程功能

       本实验主要测试滑块部件API函数的使用，实验现象：开机后，屏幕上会显示一个滑块，用户可以通过KEY0、KEY1来调节滑块的值。与此同时，LED0闪烁，提示系统正在运行。

       该实验的完整源码，请参考《LVGL例程14 lv_slider(滑块)》例程，路径：A盘→4，程序源码 →3，扩展例程 →3，LVGL例程。

       17.4.2 软件设计

       17.4.2.1 程序流程图

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

图17.4.2.1.1 滑块部件实验流程图

       17.4.2.2 程序解析

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

/**************************** 第一部分 开始 ****************************/
/**
 * @brief  LVGL演示
 * @param  无
 * @return 无
 */
void lv_mainstart(void)
{
    lv_example_slider();
}
/**************************** 第一部分 结束 ****************************/
 
/**************************** 第二部分 开始 ****************************/
/**
 * @brief  滑块事件回调
 * @param  *e ：事件相关参数的集合，它包含了该事件的所有数据
 * @return 无
 */
static void slider_event_cb(lv_event_t *e)
{
    lv_obj_t *target = lv_event_get_target(e);       /* 获取触发源 */
    lv_event_code_t code = lv_event_get_code(e);     /* 获取事件类型 */
 
    if(code == LV_EVENT_VALUE_CHANGED)
    {
        lv_label_set_text_fmt(slider_label, "%d%%", 
lv_slider_get_value(target));    /* 获取当前值，更新进度条百分比 */
    }
}
 
/**
 * @brief  音量调节滑块
 * @param  无
 * @return 无
 */
static void lv_example_slider(void)
{
    lv_group_t *g = lv_group_create();
    lv_indev_set_group(indev_keypad, g);
 
    /* 滑块 */
    lv_obj_t * slider = lv_slider_create(lv_scr_act());   /* 创建滑块 */
    lv_obj_set_size(slider, 120, 15);                     /* 设置大小 */
    lv_obj_align(slider, LV_ALIGN_CENTER, -10, 0);        /* 设置位置 */
lv_slider_set_value(slider, 50, LV_ANIM_OFF);         /* 设置当前值 */
/* 添加事件 */
    lv_obj_add_event_cb(slider, slider_event_cb, LV_EVENT_VALUE_CHANGED, NULL);
 
    /* 百分比标签 */
    slider_label = lv_label_create(lv_scr_act());          /* 创建百分比标签 */
lv_label_set_text(slider_label, "50%");                /* 设置文本内容 */
/* 设置字体 */
lv_obj_set_style_text_font(slider_label, &lv_font_montserrat_22, 0); 
/* 设置位置 */
    lv_obj_align_to(slider_label, slider, LV_ALIGN_OUT_RIGHT_MID, 15, 0); 
 
    /* 音量图标 */
lv_obj_t *sound_label = lv_label_create(lv_scr_act());    /* 创建音量标签 */
/* 设置文本内容：音量图标 */
lv_label_set_text(sound_label, LV_SYMBOL_VOLUME_MAX); 
/* 设置字体 */ 
lv_obj_set_style_text_font(sound_label, &lv_font_montserrat_22, 0); 
/* 设置位置 */
    lv_obj_align_to(sound_label, slider, LV_ALIGN_OUT_LEFT_MID, -15, 0); 
 
    lv_group_add_obj(g, slider);
}
/**************************** 第二部分 结束 ****************************/

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

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

       ② 音量调节的实现。我们创建滑块、百分比标签和音量图标，并为滑块添加事件回调。当滑块的值发生变化时，会触发事件回调，在回调函数中，我们获取滑块的当前值，并将该值更新到百分比标签中。

       17.4.3 下载验证

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

图17.4.3.1 滑块部件实验