STTBar.h 使用手册
STTBar 是直线型进度条/柱状条,支持普通、对称和范围模式,继承 STTWidget 的位置、事件、显隐和变量绑定能力。
1. 创建与基本配置
cpp 复制代码#include "widgets/STTBar.h"
using namespace stt;
STTBar* bar = new STTBar(getRuntime(), parent, "barLevel");
bar->setMainArg(20, 40, 300, 36, 50, 0, 100);
bar->setMainStyle(8, 0xeeeeee, 0xdddddd, 2,
1, 0xaaaaaa, 0, 0x000000, "");
bar->setIndicStyle(8, 0x16a05d, 0x55c98b, 2,
0, 0x000000, "");
2. API 分组
| 分组 | 方法 |
|---|---|
| 初始化 | setMainArg、setMainStyle、setIndicStyle |
| 数值 | setValue、setStartValue、getValue、getStartValue |
| 范围 | setRange、setVariableLimit、getMinValue、getMaxValue |
| 模式 | setMode、getMode |
| 变量响应 | onDataChanged |
3. setMainArg
cpp 复制代码void setMainArg(
int x = 0, int y = 0, int w = 200, int h = 50,
int value = 50, int min = 0, int max = 100
);
当前实现先 setValue,再 setRange。若初值超出默认范围,LVGL 可能先截断,因此要求精确初始化时建议再调用一次:
cpp 复制代码bar->setRange(-100, 100)->setValue(-30, false);
4. 样式
setMainStyle 配置背景条、边框、阴影和可选图片;setIndicStyle 配置 LV_PART_INDICATOR。
cpp 复制代码bar->setMainStyle(
9999, 0xdddddd, 0xdddddd, 0,
0, 0x000000, 0, 0x000000, "res/bar_bg.png"
);
bar->setIndicStyle(
9999, 0x1a2b3c, 0x1a2b3c, 0,
0, 0x000000, "res/bar_value.png"
);
图片仅在 FileUtil::fileExists 为 true 时设置。主背景有图片时背景和边框透明;指示图片代码设置图片源时没有显式传 indicator selector,这是当前实现细节,若显示位置不正确,应优先使用纯色样式或检查 SDK 版本。
5. 数值、动画与模式
cpp 复制代码bar->getStyle()->p_anim->setTime(500);
bar->setValue(75, true);
anim=true 只在动画时间已配置时产生可见过渡。绑定变量的高频变化不建议开动画,否则会持续重启动画。
模式:
| mode | 说明 |
|---|---|
| 0 | 普通,从最小值方向绘制 |
| 1 | 对称,从 0 向两侧绘制,范围应跨越 0 |
| 2 | 范围,从 start value 绘制到当前 value |
bar->setMode(2)
->setRange(0, 100)
->setStartValue(25, false)
->setValue(80, true);
STTBar 不校验 mode,值会直接传给 LVGL。getMode 返回当前底层模式。
6. 动态上下限与绑定
cpp 复制代码bar->bindData(getRuntime()->getIVarMgr()->get("TankLevel"));
bar->setVariableLimit("TankLevelLow", "TankLevelHigh");
onDataChanged 将绑定变量转换为整数并 setValue。上下限变量变化时保留另一端范围。
当前 setVariableLimit 没有检查变量是否存在,错误变量名可能导致空指针访问;空字符串只表示该端不处理,不会解除之前的连接。
7. 读取当前状态
cpp 复制代码int value = bar->getValue();
int start = bar->getStartValue();
int minv = bar->getMinValue();
int maxv = bar->getMaxValue();
int mode = bar->getMode();
这些值来自 LVGL 当前状态,而不一定等于最后一次传入值,例如超出范围时可能已被截断。
8. 注意事项
- setRange 前应保证 min < max。
- 图片必须在调用时存在且生命周期可用。
- UI 方法在 LVGL 线程调用。
- 使用范围模式时先设置 mode=2,再设置 start/value。
- 动态上下限只能绑定已注册且可转整数的变量。
- onDataChanged 是框架回调,一般不直接调用。
需要确认型号或具体项目?联系技术支持 ↗