第八章圆弧部件（lv_arc）

圆弧（arc）部件是一个较为常用的部件，它的应用场景非常多，例如：调节参数、显示参数、显示进度，等等。

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

8.1 圆弧部件的组成

8.2 圆弧部件的相关知识

8.3 圆弧部件的API函数

8.4 圆弧部件的实验

8.1 圆弧部件的组成

圆弧（lv_arc）部件由三个部分组成：背景弧、前景弧和旋钮，示意图如下：

图8.1.1圆弧（lv_arc）的组成部分

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

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

② 前景弧（LV_PART_INDICATOR）：用于显示当前值；

③ 旋钮（LV_PART_KNOB）：用于调节当前值。

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

8.2 圆弧部件的相关知识

8.2.1 圆弧的当前值和范围值

圆弧当前值指的是当前前景弧所指示的值，范围值是指圆弧当前值的可变化范围，示意图如下：

图8.2.1.1 圆弧的当前值和范围值

上图中，旋钮指示的就是当前值（50），起始值和终止值确定了范围值（0~100）。接下来，我们以简单示例来理解当前值和范围值，示例代码如下所示：

void lv_mainstart(void)
{
    lv_obj_t* arc = lv_arc_create(lv_scr_act());
    lv_arc_set_range(arc, 0, 100);  /* 设置arc的范围 */
    lv_arc_set_value(arc, 50);       /* 设置arc的值 */
    lv_obj_set_size(arc, 200, 200);
    lv_obj_align_to(arc, NULL, LV_ALIGN_CENTER, 0, 0);
}

在上述源码中，我们先创建圆弧部件，然后分别设置它的范围值和当前值，最后再设置其大小和位置。示例代码可以在PC模拟器中运行，效果图如下所示：

图8.2.1.2 示例代码效果图

8.2.2 圆弧部件角度设置

在设置圆弧部件的角度（绝对度数）之前，我们需要先搞清楚圆弧的角度划分。在圆弧部件默认的角度划分中，0度（绝对度数）位于对象右侧中部（3点钟方向），然后沿顺时针方向增加度数，直至360度，示意图如下：

图8.2.2.1角度划分示意图

了解了圆弧的角度划分，接下来我们介绍圆弧角度设置的相关函数，它们可以分为两类：背景弧角度设置和前景弧角度设置，具体函数如下所示：

/* 背景弧角度设置 */
lv_arc_set_bg_angles(arc, start_angle, end_angle) /* 同时设置起始角度和终止角度 */
lv_arc_set_bg_start/end_angle(arc, start_angle)   /* 分开设置起始角度/终止角度 */
 
/* 前景弧角度设置 */
lv_arc_set_angles(arc, start_angle, end_angle)  /* 同时设置起始角度和终止角度 */
lv_arc_set_start/end_angle(arc, start_angle)    /* 分开设置起始角度/终止角度 */

在上述函数中，我们只需要结合角度划分示意图，按需设置起始角度和终止角度即可。注意：前景弧的角度范围不能超过背景弧的角度范围，否则将会出现显示异常，该异常会在下次更新布局时被修正。

接下来，我们以一个简单的示例来理解圆弧角度的设置，示例代码如下：

void lv_mainstart(void)
{
    lv_obj_t* arc = lv_arc_create(lv_scr_act());
    lv_arc_set_bg_angles(arc, 135, 45);  /* 设置背景弧的起始角度和终止角度 */
    lv_arc_set_angles(arc, 135, 300);     /* 设置前景弧的起始角度和终止角度 */
    lv_obj_set_size(arc, 200, 200);
    lv_obj_align_to(arc, NULL, LV_ALIGN_CENTER, 0, 0);
}

在上述代码中，我们首先创建圆弧，设置背景弧的起始角度和终止角度分别为135°和45°，然后设置前景弧的起始角度和终止角度分别为135°和270°，最后再设置圆弧大小和位置。示例代码可以在PC模拟器中运行，运行效果如下图所示：

图8.2.2.2示例代码效果图

8.2.3 圆弧部件旋转设置

圆弧部件旋转是指将整个部件沿顺时针方向旋转某个角度，注意：旋转的角度为相对值（增量），它的范围是0~360度，旋转中心为圆弧的中心。圆弧旋转的示意图如下（旋转180度）：

图8.2.3.1圆弧旋转示意图

由上图可知，该圆弧旋转了180度，值得注意的是，圆弧旋转后，它的角度划分（绝对度数）就会发生变化。

接下来，我们以一个简单的示例来理解圆弧旋转的设置，示例代码如下：

void lv_mainstart(void)
{
    lv_obj_t* arc = lv_arc_create(lv_scr_act());
    lv_arc_set_bg_angles(arc, 135, 45);
    lv_arc_set_angles(arc, 135, 270);
    lv_arc_set_rotation(arc, 180);  /* 旋转180度 */
    lv_obj_set_size(arc, 200, 200);
    lv_obj_align_to(arc, NULL, LV_ALIGN_CENTER, 0, 0);
}

在上述的源码中，我们调用了lv_arc_set_rotation函数，让圆弧部件旋转180度，示例代码的效果如下图所示：

图8.2.3.2 示例代码效果图

8.2.4 圆弧的模式选择

默认情况下，圆弧部件是沿顺时针方向绘制的，如果用户需要修改绘制的方向，可以调用lv_arc_set_mode函数，设置圆弧的绘制模式，圆弧模式相关的枚举如下所示：

① LV_ARC_MODE_NORMAL：顺时针方向绘制；

② LV_ARC_MODE_REVERSE：逆时针方向绘制；

③ LV_ARC_MODE_SYMMETRIC：从中间点开始绘制到当前值。

8.2.5 圆弧部件的变化率设置

当圆弧的旋钮被滑动时，前景弧将根据设定的变化率来绘制。变化率的单位为：度/秒，用户可调用lv_arc_set_change_rage函数设置变化率。

8.2.6 移除旋钮

当我们将圆弧作为进度指示器或者参数指示器来使用时，则需要移除它的旋钮，并清除可点击的属性，示例代码如下：

lv_obj_t *arc = lv_arc_create(lv_scr_act());
lv_obj_remove_style(arc, NULL, LV_PART_KNOB);  /* 移除旋钮 */
lv_obj_clear_flag(arc, LV_OBJ_FLAG_CLICKABLE);  /* 清除可点击属性 */
lv_obj_center(arc);

在上述的源码中，我们先调用了lv_obj_remove_style函数，移除了旋钮部分，然后调用lv_obj_clear_flag函数，清除圆弧的可点击属性，示例代码的效果如下图所示：

图8.2.6.1 示例代码效果图

8.2.7 圆弧部件事件

① LV_EVENT_VALUE_CHANGED：圆弧的值发生变化；

② LV_ARC_DRAW_PART_BACKGROUND：绘制背景弧线；

③ LV_ARC_DRAW_PART_FOREGROUND：绘制前景弧线；

④ LV_ARC_DRAW_PART_KNOB ：绘制旋钮。

8.3 圆弧部件的API函数

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

表8.3.1 圆弧部件相关的API函数

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

1. lv_arc_create函数

创建圆弧对象，其函数原型如下所示：

lv_obj_t *lv_arc_create(lv_obj_t *parent);

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

表8.3.2 lv_arc_create函数形参描述

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

2. lv_arc_set_start_angle函数

设置前景弧的起始角度，其函数原型如下所示：

void lv_arc_set_start_angle(lv_obj_t *arc, uint16_t start);

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

表8.3.3 lv_arc_set_start_angle函数形参描述

返回值：无。

3. lv_arc_set_end_angle函数

设置前景弧的结束角度，其函数原型如下所示：

void lv_arc_set_end_angle(lv_obj_t *arc, uint16_t end);

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

表8.3.4 lv_arc_set_end_angle函数形参描述

返回值：无。

4. lv_arc_set_angles函数

设置前景弧的开始和结束角度，其函数原型如下所示：

void lv_arc_set_angles(lv_obj_t *arc, uint16_t start, uint16_t end);

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

表8.3.5 lv_arc_set_angles函数形参描述

返回值：无。

5. lv_arc_set_bg_start_angle函数

设置背景弧的起始角度，其函数原型如下所示：

void lv_arc_set_bg_start_angle(lv_obj_t *arc, uint16_t start);

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

表8.3.6 lv_arc_set_bg_start_angle函数形参描述

返回值：无。

6. lv_arc_set_bg_end_angle函数

设置背景弧的结束角度，其函数原型如下所示：

void lv_arc_set_bg_end_angle(lv_obj_t *arc, uint16_t end);

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

表8.3.7 lv_arc_set_bg_end_angle函数形参描述

返回值：无。

7. lv_arc_set_bg_angles函数

设置背景弧的起止角度，其函数原型如下所示：

void lv_arc_set_bg_angles(lv_obj_t *arc, uint16_t start, uint16_t end);

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

表8.3.8 lv_arc_set_bg_angles函数形参描述

返回值：无。

8. lv_arc_set_rotation函数

设置圆弧的旋转，其函数原型如下所示：

void lv_arc_set_rotation(lv_obj_t *arc, uint16_t rotation);

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

表8.3.9 lv_arc_set_rotation函数形参描述

返回值：无。

9. lv_arc_set_mode函数

设置圆弧的模式，其函数原型如下所示：

void lv_arc_set_mode(lv_obj_t *arc, lv_arc_mode_t type);

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

表8.3.10 lv_arc_set_mode函数形参描述

返回值：无。

10. lv_arc_set_value函数

设置圆弧当前值，其函数原型如下所示：

void lv_arc_set_value(lv_obj_t *arc, int16_t value);

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

表8.3.11 lv_arc_set_value函数形参描述

返回值：无。

11. lv_arc_set_range函数

设置圆弧的范围值，其函数原型如下所示：

void lv_arc_set_range(lv_obj_t *arc, int16_t min , int16_t max);

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

表8.3.12 lv_arc_set_range函数形参描述

返回值：无。

12. lv_arc_set_change_rate函数

设置变化率，其函数原型如下所示：

void lv_arc_set_change_rate(lv_obj_t *arc, uint16_t rate);

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

表8.3.13 lv_arc_set_change_rate函数形参描述

返回值：无。

8.4 圆弧部件的实验

8.4.1 硬件设计

1. 例程功能

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

该实验的完整源码，请参考《LVGL例程5 arc(弧)》例程，路径：A盘à 4，程序源码à 3，扩展例程à 3，LVGL例程。

8.4.2 软件设计

8.4.2.1 程序流程图

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

图8.4.2.1.1 圆弧实验流程图

8.4.2.2 程序解析

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

/**************************** 第一部分 开始 ****************************/
/**
 * @brief  LVGL演示
 * @param  无
 * @return 无
 */
void lv_mainstart(void)
{
    lv_example_arc();       /* 圆弧 */
}
/**************************** 第一部分 结束 ****************************/
 
/**************************** 第二部分 开始 ****************************/
/**
 * @brief  圆弧
 * @param  无
 * @return 无
 */
void lv_example_arc(void)
{
/* 创建“组” */
    lv_group_t *g = lv_group_create();
lv_indev_set_group(indev_keypad, g);
 
arc = lv_arc_create(lv_scr_act());                      /* 创建圆弧 */
/* 设置大小 */
    lv_obj_set_size(arc, scr_act_height() * 2/3, scr_act_height() * 2/3);  
    lv_obj_align(arc, LV_ALIGN_CENTER, 0, 0);               /* 设置位置 */
    lv_arc_set_value(arc, 0);                               /* 设置当前值 */
    lv_obj_set_style_arc_width(arc, 20, LV_PART_MAIN);      /* 设置背景弧宽度 */
lv_obj_set_style_arc_width(arc, 20, LV_PART_INDICATOR); /* 设置前景弧宽度 */
/* 添加事件 */
    lv_obj_add_event_cb(arc, arc_event_cb, LV_EVENT_VALUE_CHANGED, NULL);  
 
    /* 百分比标签 */
    label = lv_label_create(lv_scr_act());                   /* 创建百分比标签 */
    lv_obj_align(label, LV_ALIGN_CENTER, 0, 0);                   /* 设置位置 */
    lv_label_set_text(label, "0%");                               /* 设置文本 */
    lv_obj_set_style_text_font(label, &lv_font_montserrat_32, 0); /* 设置字体 */
 
/* 添加部件到“组” */
    lv_group_add_obj(g, arc);
}
/**************************** 第二部分 结束 ****************************/

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

① lv_mainstart接口函数。在该函数中，我们调用了圆弧示例函数；

②圆弧实现。我们创建圆弧并为其添加事件回调，然后创建百分比标签，用于指示圆弧的当前值。注意：因为我们用的是按键控制GUI，因此需要创建“组”，并将部件添加到“组”当中（某些部件默认在组中，不需要添加），这样才能成功控制部件。

8.4.3 下载验证

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

图8.4.3.1 圆弧实验效果图

ITPub博客

《LVGL开发指南 V1.0（G4电机开发板专用）》第八章圆弧部件（lv_arc）

最新文章

ITPub博客

《LVGL开发指南 V1.0（G4电机开发板专用）》第八章 圆弧部件（lv_arc）

最新文章

《LVGL开发指南 V1.0（G4电机开发板专用）》第八章圆弧部件（lv_arc）