第九章 进度条部件(lv_bar)

       进度条的功能较为简单，它一般被用作参数指示器或者进度指示器。

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

       9.1 进度条部件的组成

       9.2 进度条部件的相关知识

       9.3 进度条部件的API函数

       9.4 进度条部件的实验

        9.1 进度条部件的组成

       进度条(lv_bar)部件由两个部分组成：背景和指示器，示意图如下：

图9.1.1 进度条的组成部分

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

       ① 背景（LV_PART_MAIN）：用于显示范围值；

       ② 指示器（LV_PART_INDICATOR）：用于显示当前值；

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

        9.2 进度条部件的相关知识

       9.2.1 进度条的方向

       进度条可以设置为水平或者垂直方向，当它的宽度小于高度时，其为水平方向，反之为垂直方向。

       9.2.2 进度条的当前值和范围值

       进度条当前值指的是当前指示器所指示的值，范围值是指进度条当前值的可变化范围，用户需要设置这两个参数，可以调用以下函数：

lv_bar_set_range(bar, min, max);      /* 设置进度条部件范围 */
lv_bar_set_value(bar, new_value, LV_ANIM_ON/OFF); /* 设置进度条当前值 */

       上述的当前值设置函数的最后一个形参代表是否使用动画，如果使用动画请传入LV_ANIM_ON，否则传入LV_ANIM_OFF。

       注意：在默认情况下，范围值为0~100，进度条都是从该范围的最小值开始绘制的。

       接下来，我们以简单示例来帮助大家理解当前值和范围值，示例代码如下所示：

void lv_mainstart(void)
{
    lv_obj_t* lv_bar1 = lv_bar_create(lv_scr_act());   /* 创建进度条 */
lv_obj_set_style_bg_color(lv_bar1, lv_color_black(),
LV_PART_MAIN|LV_STATE_DEFAULT);
lv_obj_set_style_bg_color(lv_bar1, lv_palette_main(LV_PALETTE_RED),
LV_PART_INDICATOR |LV_STATE_DEFAULT);
    lv_obj_set_size(lv_bar1, 100, 20);                  /* 设置进度条的大小 */
    lv_obj_align(lv_bar1, LV_ALIGN_CENTER, 0, 0);        /* 设置对齐模式 */
    lv_bar_set_range(lv_bar1, 0, 100);
    lv_bar_set_value(lv_bar1, 100, LV_ANIM_OFF);        /* 设置进度条的值 */
 
 
    lv_obj_t* lv_bar2 = lv_bar_create(lv_scr_act());   /* 创建进度条 */
    lv_obj_set_style_bg_color(lv_bar2, lv_color_black(),LV_STATE_DEFAULT);
lv_obj_set_style_bg_color(lv_bar2, lv_palette_main(LV_PALETTE_BLUE),
LV_STATE_DEFAULT);
    lv_obj_set_size(lv_bar2, 20, 100);      /* 设置进度条的大小 */
    /* 设置对齐模式 */
    lv_obj_align_to(lv_bar2, lv_bar1, LV_ALIGN_OUT_BOTTOM_MID, 0, 20);
lv_bar_set_range(lv_bar2, 0, 100); 
/* 填充满的时间 */
    lv_obj_set_style_anim_time(lv_bar2, 5000, LV_STATE_DEFAULT);
    lv_bar_set_value(lv_bar2, 100, LV_ANIM_ON);       /* 设置进度条当前值 */
}

       在上述源码中，我们分别创建了两个进度条，将lv_bar1进度条设置为垂直进度条，不使用动画；lv_bar2进度条则设置为水平进度条且开启动画，动画时间为5秒。在实际运行时，lv_bar2进度条需要5秒才能填充完毕，而lv_bar1进度条则是瞬间填充完毕。示例代码可以在PC模拟器中运行，效果图如下所示：

图9.2.2.1 示例代码效果图

       注意：设置动画时间的函数（lv_obj_set_style_anim_time）必须在lv_bar_set_value函数之前调用，否则不会出现效果。

       9.2.3 进度条模式

       进度条部件具有三种模式，它们对应的枚举如下所示：

       ① LV_BAR_MODE_NORMAL：普通模式（默认）；

       ② LV_BAR_MODE_SYMMETRICAL：始终从零开始绘制，范围值可以是负数；

       ③ LV_BAR_MODE_RANGE：允许设置起始值，该起始值必须始终小于结束值。

       接下来，我们结合源码，给大家重点介绍LV_BAR_MODE_SYMMETRICAL模式的使用，示例代码如下所示：

void lv_mainstart(void)
{
    lv_obj_t* bar = lv_bar_create(lv_scr_act());     /* 创建 bar 部件 */
lv_obj_center(bar);
    lv_obj_set_style_bg_color(bar, lv_color_black(), LV_STATE_DEFAULT);
lv_obj_set_style_bg_color(bar, lv_palette_main(LV_PALETTE_BLUE),
LV_STATE_DEFAULT);
    lv_bar_set_mode(bar, LV_BAR_MODE_SYMMETRICAL);    /* 设置模式 */
    lv_bar_set_range(bar, -100, 100);              /* 设置范围值 */
    lv_obj_set_style_anim_time(bar, 5000, LV_STATE_DEFAULT);  /* 设置动画时间 */
    lv_bar_set_value(bar, 100, LV_ANIM_ON);           /* 设置当前值*/
}

       在上述源码中，我们把进度条的范围值设置为-100~100，并使用LV_BAR_MODE_SYMMETRICAL模式，此时，进度条始终从0开始绘制，直至当前值处停止。示例代码可以在PC模拟器中运行，效果图如下所示：

图9.2.3.1 LV_BAR_MODE_SYMMETRICAL模式示例

       在上述的示例源码中，如果我们不设置进度条的模式（默认），效果图如下所示：

图9.2.3.2默认模式

       9.2.4 进度条事件

       LV_BAR_DRAW_PART_INDICATOR：绘制指示器。

        9.3 进度条部件的API函数

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

表9.3.1 进度条相关的API函数

       接下来，我们介绍LVGL进度条部件常用的API函数：

       1.lv_bar_create函数

       创建进度条对象，其函数原型如下所示：

lv_obj_t *lv_bar_create(lv_obj_t *parent);

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

表9.3.2 lv_bar_create函数形参描述

       返回值：返回对象控制块。

       2.lv_bar_set_value函数

       在进度条设置新值，其函数原型如下所示：

void lv_bar_set_value(lv_obj_t *obj, int32_t value, lv_anim_enable_t anim);

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

表9.3.3 lv_bar_set_value函数形参描述

       返回值：无。

       3.lv_bar_set_start_value函数

       在进度条设置新的起始值，其函数原型如下所示：

void lv_bar_set_start_value(lv_obj_t *obj, int32_t start_value, 
lv_anim_enable_t anim);

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

表9.3.4 lv_bar_set_start_value函数形参描述

       返回值：无。

       4.lv_bar_set_range函数

       设置进度条范围值，其函数原型如下所示：

void lv_bar_set_range(lv_obj_t *obj, int32_t min, int32_t max);

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

表9.3.5 lv_bar_set_range函数形参描述

       返回值：无。

       5.lv_bar_set_mode函数

       设置进度条模式，其函数原型如下所示：

void lv_bar_set_mode(lv_obj_t *obj, lv_bar_mode_t mode);

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

表9.3.6 lv_bar_set_mode函数形参描述

       返回值：无。

        9.4 进度条部件的实验

       9.4.1 硬件设计

       1. 例程功能

       本实验主要测试进度条部件API函数的使用，实验现象：开机后，屏幕上显示一个进度条，当它加载到100%会提示finished。与此同时，LED0闪烁，提示系统正在运行。

       该实验的完整源码，请参考《LVGL例程6 bar(进度条)》例程，路径：A盘→4，程序源码 →3，扩展例程 → 3，LVGL例程。

       9.4.2 软件设计

       9.4.2.1 程序流程图

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

图9.4.2.1.1 进度条部件实验流程图

       9.4.2.2 程序解析

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

/**************************** 第一部分 开始 ****************************/
/**
 * @brief  LVGL演示
 * @param  无
 * @return 无
 */
void lv_mainstart(void)
{
    lv_example_label();           /* 加载提示标签 */
    lv_example_bar();             /* 加载进度条 */
}
/**************************** 第一部分 结束 ****************************/
/**************************** 第二部分 开始 ****************************/
/**
 * @brief  加载提示标签
 * @param  无
 * @return 无
 */
static void lv_example_label(void)
{
    /* 加载标题标签 */
    label_load = lv_label_create(lv_scr_act());
    lv_label_set_text(label_load, "LOADING...");
    lv_obj_set_style_text_font(label_load, &lv_font_montserrat_22, 0);
    lv_obj_align(label_load, LV_ALIGN_CENTER, 0, -scr_act_height() / 10 );
    /* 百分比标签 */
    label_per = lv_label_create(lv_scr_act());
    lv_label_set_text(label_per, "%0");
    lv_obj_set_style_text_font(label_per, &lv_font_montserrat_22, 0);
    lv_obj_align(label_per, LV_ALIGN_CENTER, 0, scr_act_height() / 10 );
}
/**************************** 第二部分 结束 ****************************/
/**************************** 第三部分 开始 ****************************/
/**
 * @brief  定时器回调
 * @param  *timer ：该定时器相关的数据
 * @return 无
 */
static void timer_cb(lv_timer_t *timer)
{
    if(val < 100)                                    /* 当前值小于100 */
    {
        val ++;
        lv_bar_set_value(bar, val, LV_ANIM_ON);      /* 设置当前值 */
/* 获取当前值，更新显示 */
        lv_label_set_text_fmt(label_per, "%d %%", lv_bar_get_value(bar));   
    }else               /* 当前值大于等于100 */
    {
        lv_label_set_text(label_per, "finished!");   /* 加载完成 */
    }
}
 
/**
 * @brief  加载进度条
 * @param  无
 * @return 无
 */
static void lv_example_bar(void)
{
    bar = lv_bar_create(lv_scr_act());                     /* 创建进度条 */
    lv_obj_set_align(bar, LV_ALIGN_CENTER);                /* 设置位置 */
    lv_obj_set_size(bar, scr_act_width() * 4 / 5, 15);     /* 设置大小 */
    lv_obj_set_style_anim_time(bar, 100, LV_STATE_DEFAULT);   /* 设置动画时间 */
    lv_timer_create(timer_cb, 100, NULL);                  /* 初始化定时器 */
}
/**************************** 第三部分 结束 ****************************/

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

       ① lv_mainstart接口函数。在该函数中，我们调用了标签和进度条示例函数；

       ② 百分比标签实现。我们创建标题标签和百分比标签，然后设置相应的文本内容、位置。

       ③ 进度条动画实现。我们先创建进度条部件和定时器，设置每100ms触发一次定时器回调，然后在定时器回调中修改进度条的当前值，如果当前值大于等于100，则显示“finished!”。

       9.4.3 下载验证

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

图9.4.3.1 进度条实验