菜单

STTBar.h 使用手册

下载

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
cpp 复制代码 
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 是框架回调，一般不直接调用。
最近修改: 2026-10-21Powered by