菜单

STTMeter使用手册

下载

STTMeter.h 使用手册

STTMeter 封装 LVGL Meter，可使用底层 scale/indicator API 自由组合，也提供 Gauge、Needle 和 LineMeter 三套便捷初始化流程。

1. 两种使用方式

1.1 自由组合

cpp 复制代码 
#include "widgets/STTMeter.h"

using namespace stt;

STTMeter* meter = new STTMeter(getRuntime(), parent, "meterCustom");
meter->setPos(20, 20)->setSize(240, 240);

LvMeterScale* scale = meter->addScale();
meter->setScaleRange(scale, 0, 100, 270, 135);
meter->setScaleTicks(scale, 21, 3, 10, 0x999999);
meter->setScaleMajorTicks(scale, 5, 5, 16, 0x333333, 12);

LvMeterIndicator* needle =
    meter->addNeedleLine(scale, 5, 0xff0000, -10);
meter->setIndicatorValue(needle, 60);

1.2 便捷预设

Gauge：

cpp 复制代码 
meter->setGaugeMainArg(20, 20, 240, 240,
                       80, 0, 100, 270,
                       true, true, 1, 135, 16);
meter->setGaugeMainStyle();
meter->setGaugeTickStyle();
meter->setGaugeMajorTickStyle();
meter->setGaugeNeedleStyle(0xff0000, 50);
meter->setGaugeCircleStyle();

Needle：

cpp 复制代码 
meter->setNeedleMainArg(20, 20, 240, 240, 0, 100, 270, 135, 16);
meter->setNeedleNeedleStyle(0xff0000, 50);
meter->setNeedleCircleStyle();

LineMeter：

cpp 复制代码 
meter->setLineMeterMainArg(20, 20, 240, 240, 0, 100, 270, 135);
meter->setLineMeterMainStyle();
meter->setLineMeterTickStyle(
    0x00aa00, 0xffff00, 0xdddddd,
    4, 6, 10, 41, 70
);

三种 main 初始化不要在同一个实例上叠加调用，否则会持续添加 scale/indicator 并覆盖内部指针。

2. Scale API

方法 作用
addScale 新增标尺，返回借用指针
setScaleTicks 设置普通刻度数量、宽、长、色
setScaleMajorTicks 每 nth 个刻度设置主刻度和标签
setScaleRange 设置 min/max、角度跨度、旋转

scale 必须来自当前 meter，且 meter 销毁后失效。cnt 应大于 2；nth、范围等由调用方验证。

3. Indicator API

创建：

cpp 复制代码 
LvMeterIndicator* needle =
    meter->addNeedleLine(scale, 6, 0xff0000, -8);
LvMeterIndicator* imageNeedle =
    meter->addNeedleImg(scale, imageSrc, pivotX, pivotY);
LvMeterIndicator* arc =
    meter->addArc(scale, 10, 0x00aa00, -4);
LvMeterIndicator* ticks =
    meter->addScaleLines(scale, 0x00aa00, 0xff0000, true, 0);

赋值：

cpp 复制代码 
meter->setIndicatorValue(needle, 50);
meter->setIndicatorStartValue(arc, 20);
meter->setIndicatorEndValue(arc, 75);

setIndicatorValue 适合针；start/end 适合弧或刻度段。

4. setValue、动画与读取

cpp 复制代码 
meter->setAnimTimeMs(500);
meter->setValue(75);
int value = meter->getValue();

setValue 同时更新内部 needle 和 tick，哪个存在就更新哪个。getValue 优先返回 needle 的 end_value，其次 tick，否则 0。

动画实现使用内部 info->needle 或 info->tick，而忽略传给 setIndicatorValue/setIndicatorEndValue 的 indic 参数。因此打开动画后，自由组合的第二个/额外 indicator 不能可靠动画；动画只适合便捷模式内置指针/刻度。

setAnimTimeMs 不校验负值；只有大于 0 才动画。

5. Gauge 专用接口

方法 作用
setGaugeMainArg 创建 scale、正常/报警刻度段和 needle
setGaugeMainStyle 背景、边框、阴影
setGaugeNeedleStyle 线针或图片针
setGaugeFont 标签颜色、字体
setGaugeTickStyle 正常渐变和报警段刻度
setGaugeMajorTickStyle 主刻度与标签间距
setGaugeCircleStyle 中心圆

setGaugeMajorTickStyle 内部计算：

text 复制代码 
nth = (tickCount - 1) / (labelCount - 1)

cnt_label=1 会除零；tickCount/labelCount 组合还可能得到 nth=0。调用方至少保证 cnt_label>1 且不大于有效刻度分段数。

setGaugeNeedleStyle 直接访问内部 lv_meter_indicator_t 字段，依赖当前 LVGL ABI；必须在 setGaugeMainArg 后调用。

6. 动态范围与报警

cpp 复制代码 
meter->setVariableLimit("MeterLow", "MeterHigh");
meter->setVariableAlarm("MeterAlarm");
meter->setRange(0, 120);
meter->setAlarmValue(90);

这些便捷接口依赖 setGaugeMainArg 已创建：

  • setRange 使用 info->scale，并直接访问 tick_indic。
  • setAlarmValue 使用 tick 和 tick_indic。
  • Needle 模式没有 tick/tick_indic，调用会空指针。
  • LineMeter 模式也不保证 tick_indic 存在。

动态变量查询没有 nullptr 检查，只能传已注册、可转整数的变量。空字符串不会解除旧连接。

7. 角度查询

cpp 复制代码 
LvMeterScale* scale = meter->getScale();
LvMeterIndicator* needle = meter->getNeedle();
int start = meter->getStartAngle();
int end = meter->getEndAngle();
int angle = meter->getValueAngle();

便捷模式初始化前 getScale/getNeedle 可能为 nullptr。getValueAngle 计算中除以 max-min，范围相等会除零；它也不归一化大于 360 的结果。

8. 变量绑定

cpp 复制代码 
meter->bindData(getRuntime()->getIVarMgr()->get("Pressure"));

onDataChanged 把变量转整数并 setValue。来源是当前控件时跳过。

9. 图片指针

cpp 复制代码 
meter->setGaugeNeedleStyle(
    0xff0000, 50, 6,
    needleImage,
    1,
    pivotX, pivotY,
    -10
);

图片应指向右侧，pivot 指定轴心。图片源必须在 meter 存活期间有效。recolor_mode>0 时设置 indicator 图片重着色。

10. 注意事项

  • 先调用对应 MainArg，再调用其专用样式、范围和报警方法。
  • 一个实例只选择一种便捷模式。
  • scale/indicator 是借用指针，禁止释放。
  • 析构处仍有 TODO 注释，依赖 LVGL 对象统一释放子结构。
  • 动画只可靠作用于内部 needle/tick。
  • cnt_label>1，min 必须小于 max。
  • 动态变量必须存在。
  • 所有操作在 LVGL 线程执行。
最近修改: 2026-10-21Powered by