LVGL 控件之仪表盘（lv_meter)

一、概述

仪表盘部件可以非常灵活地展示数据，其功能包括显示弧形（arcs）、指针（needles）、刻度线（ticks lines）以及标签（labels）。这意味着它可以模拟各种仪表盘样式。

仪表盘部件由四个部分组成，示意图如下：

• LV_PART_MAIN：主体背景；
• LV_PART_TICK：仪表的刻度；
• LV_PART_INDICATOR：仪表指针；
• LV_PART_ITEMS：圆弧。

二、仪表盘部件

在 LVGL 中，当用户创建出一个仪表部件时，该部件并不具备仪表的角度、仪表的范围、仪表的刻度以及仪表的指针等功能（见下图），这些功能都是由用户自行设置的。接下来，我们分别介绍这些功能的添加和设置。

lv_obj_t* meter = lv_meter_create(lv_scr_act());
lv_obj_center(meter);

1、添加刻度

刻度分为小刻度和主刻度，主刻度是图中加粗的线条，而小刻度是图中正常的线条。这些刻度的添加是由三个函数来完成，如下表所示：

上表的函数调用是有一定的顺序的，首先调用第一个函数把刻度添加到仪表当中，该函数返回一个刻度的对象，然后我们根据这个刻度的对象分别设置小刻度和主刻度。

/** 
 * obj 指向仪表对象的指针
 */
lv_meter_scale_t *lv_meter_add_scale(lv_obj_t *obj);

/**
 * meter : 指向仪表对象的指针
 * scale : 指向刻度对象
 * cnt	 : 小刻度的数量
 * width : 小刻度的宽度
 * len   : 小刻度的长度
 * color : 小刻度的颜色
 */
void lv_meter_set_scale_ticks(lv_obj_t *obj, lv_meter_scale_t *scale,
							  uint16_t cnt, uint16_t width,
							  uint16_t len, lv_color_t color);

/**
 * meter     : 指向仪表对象的指针
 * scale     : 指向刻度对象
 * nth       : 绘画主刻度的步长
 * width     : 主刻度的宽度
 * len       : 主刻度的长度
 * color     : 主刻度的颜色
 * label_gap : 刻度与标签之间的间隙
 */
void lv_meter_set_scale_major_ticks(lv_obj_t *obj, lv_meter_scale_t *scale,
									uint16_t nth, uint16_t width, uint16_t len,
									lv_color_t color, int16_t label_gap);

例：

/* 获取当前活动屏幕的宽高 */
#define scr_act_width() lv_obj_get_width(lv_scr_act())
#define scr_act_height() lv_obj_get_height(lv_scr_act())

void my_gui(void) {
    lv_obj_t* meter = lv_meter_create(lv_scr_act());  /* 定义并创建仪表 */
    lv_obj_set_width(meter, scr_act_height() * 0.4);  /* 设置仪表宽度 */    
    lv_obj_set_height(meter, scr_act_height() * 0.4); /* 设置仪表高度 */
    
    lv_obj_center(meter);
    
    /* 设置仪表刻度 */
    lv_meter_scale_t* scale = lv_meter_add_scale(meter); /* 定义并添加刻度 */
    /* 设置小刻度数量为41，宽度为1，长度为屏幕高度除以80，颜色为灰色 */
    lv_meter_set_scale_ticks(meter, scale, 41, 1, scr_act_height() / 80,
                             lv_palette_main(LV_PALETTE_GREY));
    /* 设置主刻度的步长为8,宽度为1，长度为屏幕高度除以60，颜色为黑色，
       刻度与数值的间距为屏幕高度除以30 */
    lv_meter_set_scale_major_ticks(meter, scale, 8, 1, scr_act_height() / 60,
                                   lv_color_black(), scr_act_height() / 30);
}

2、添加指针

仪表指针，是指用于仪表上指示数据的零部件。指针的功能就是以比较客观直接的方法指示复杂的数据结构。指针的结构一般是狭长的，一端尖，便于指示和读数。因为精确度是仪器仪表的主要性能之一，指针的这种设计和构造有利于提高仪器仪表的精度，减小误差。

在 LVGL 中，关于仪表指针的函数有两个，如下表所示：

/**
 * obj   : 指向仪表对象的指针
 * scale : 指向刻度对象
 * width : 指针宽度
 * color : 指针颜色
 * r_mod : 修改半径长度(0：默认值；-10：默认长度-10)
 */
lv_meter_indicator_t *lv_meter_add_needle_line(lv_obj_t *obj, lv_meter_scale_t *scale,
											   uint16_t width, lv_color_t color, int16_t r_mod);

/**
 * obj   : 指向仪表对象的指针
 * indic : 指向指针对象
 * value : 指向的数值
 */
void lv_meter_set_indicator_value( lv_obj_t * obj, lv_meter_indicator_t * indic,
								   int32_t value);

例：那么接下来再上一小节的代码中添加如下代码：

lv_meter_indicator_t* indic;
/* 添加仪表指针，该指针宽度为4，颜色为灰色，长度-10 */
indic = lv_meter_add_needle_line(meter, scale, 4,
                                 lv_palette_main(LV_PALETTE_GREY), -10);
/* 设置指针指向的数值 */
lv_meter_set_indicator_value(meter, indic,66);

3、设置仪表的角度和仪表的范围

仪表的角度主要设置仪表从顺时针旋转的角度以及有效的角度范围，比如在上一小节的示例图中，该图中的仪表有效角度范围为 0~270°，如果我们使用仪表部件制作时钟 UI，显然 0~270° 有效角度范围并不满足我们的需求，所以我们可手动设置仪表的有效角度范围为 0~360°。

仪表的范围是指仪表的数值范围，默认仪表的数值范围为 0~100 的数值，我们可以手动调整数值的范围。

上述仪表的三个功能是由一个 LVGL 函数 lv_meter_set_scale_range 统一设置，见下：

/**
 * obj   	   : 指向仪表对象的指针
 * scale	   : 指向指针对象
 * min  	   : 最小值
 * max   	   : 最大值
 * angle_range : 最大的角度(默认是270°，可设置0~360°)
 * rotation    : 旋转的角度(默认是0°，可设置0~360°)
 */
void lv_meter_set_scale_range(lv_obj_t * obj,
							  lv_meter_scale_t * scale,
							  int32_t min, int32_t max,
							  uint32_t angle_range, uint32_t rotation);

例：这次又在前面的基础上添加一行代码：

/* 设置仪表数值范围、有效角度和旋转角度 */
lv_meter_set_scale_range(meter, scale, 0, 150, 360, 90);

4、装饰

4.1 仪表指针图片

为了提高仪表的美观度，用户可以使用图片来替代仪表的指针，这样能使仪表更加生动。仪表指针图片相关的函数 lv_meter_add_needle_img 原型如下所示：

/**
 * obj     : 指向仪表对象的指针
 * scale   : 指向刻度对象
 * src     : 图像源(C 数组、路径等)
 * pivot_x : X 枢轴点
 * pivot_y : Y 枢轴点
 */
lv_meter_indicator_t *lv_meter_add_needle_img( lv_obj_t *obj,
											   lv_meter_scale_t *scale,
											   const void *src,
											   lv_coord_t pivot_x,
											   lv_coord_t pivot_y);

4.2 仪表的指示刻度

仪表的指示刻度是指在仪表刻度上指定某个范围刻度填充颜色，前面我们学习过 lv_meter_set_scale_ticks 和 lv_meter_set_scale_major_ticks 这两个函数，它们都有一个形参表示刻度填充的颜色，显然地，这些形参只针对整体设置颜色，并不是指定某个刻度范围设置颜色。

这个次要功能也是比较常见的，比如汽车油表，它的最低值和最大值的某范围都是使用明显的颜色提示和引导驾驶员。下面我们使用一个示意图来讲解这个功能，如下图所示：

从上图可知：我们设置仪表从 0 到 10 和 50 到 60 以某种颜色渐变，这样的功能在仪表部件中是比较常见的。关于这个功能，LVGL 官方提供了三个函数，如下表所示：

上述表中的函数也是按照某些顺序执行，首先我们调用函数 lv_meter_add_scale_lines 在仪表上添加指示刻度，该函数返回指示刻度指针，然后程序根据指示刻度指针设置指示刻度的起始值和终止值，起始值和终止值无需顺序调用。

注意：如果仪表不设置起始值，则指示刻度从 0 开始；如果仪表只添加指示刻度不设置起始值和终止值，则指示刻度不会被绘画出来。

/**
 * obj         : 指向仪表对象的指针
 * scale       : 指向刻度对象
 * color_start : 开始颜色
 * color_end   : 终止颜色
 * local       : true： 渐变，false： 渐变(注：这两种状态看不出有任何变化)
 * width_mod   : 指示刻度的宽度
 */
lv_meter_indicator_t *lv_meter_add_scale_lines(lv_obj_t *obj,
											   lv_meter_scale_t *scale,
											   lv_color_t color_start,
											   lv_color_t color_end,
											   bool local,
											   int16_t width_mod);

/**
 * obj    : 指向仪表对象的指针
 * indic  : 指向刻度对象
 * value  : 起始值
 */
void lv_meter_set_indicator_start_value(lv_obj_t *obj,
										lv_meter_indicator_t *indic,
										int32_t value);

/**
 * obj   : 指向仪表对象的指针
 * indic : 指向刻度对象
 * value : 结束值
 */
void lv_meter_set_indicator_end_value(lv_obj_t *obj,
									  lv_meter_indicator_t *indic,
									  int32_t value);

例：

/* 添加指示刻度，起始颜色为浅蓝色，终止颜色为深蓝色，状态为true，指示刻度为10 */
indic = lv_meter_add_scale_lines(meter, scale,
                                 lv_palette_darken(LV_PALETTE_BLUE,1),
                                 lv_palette_darken(LV_PALETTE_BLUE, 4),
                                 true, 10);
/* 设置指示刻度起始值为50 */
lv_meter_set_indicator_start_value(meter, indic, 50);
/* 设置指示刻度终止值为100 */
lv_meter_set_indicator_end_value(meter, indic, 100);

4.3 仪表弧线指示器

仪表弧线指示器也是一样比较常见的仪表功能，该功能和指示刻度具有相似的效果，主要用于引导和提示用户，其示意图如下所示：

关于这个功能，LVGL 官方提供了三个函数，如下表所示：

上表中第二、三个函数前面已经介绍过，下面看第一个函数：

/**
 * obj   : 指向仪表对象的指针
 * scale : 指向刻度对象
 * width : 弧线宽度
 * color : 弧线颜色
 * r_mod : 偏移值
 */
lv_meter_indicator_t *lv_meter_add_arc( lv_obj_t *obj,
										lv_meter_scale_t *scale,
										uint16_t width,
										lv_color_t color,
										int16_t r_mod)

例：

/* 添加弧线指示器，弧线宽度为10，颜色为红色，偏移10 */
indic = lv_meter_add_arc(meter, scale, 10,
                         lv_palette_main(LV_PALETTE_RED), 10);
lv_meter_set_indicator_start_value(meter, indic, 80);
lv_meter_set_indicator_end_value(meter, indic, 100);

5、API 函数