STTSpinner.h 使用手册
STTSpinner 是持续旋转的圆弧加载/转速指示控件,可固定速度旋转,也可按绑定变量映射转速和方向。
1. 创建
cpp 复制代码#include "widgets/STTSpinner.h"
using namespace stt;
STTSpinner* spinner = new STTSpinner(getRuntime(), parent, "spinnerMotor");
spinner->setMainArg(
20, 20, 100, 100,
2000, // 每圈毫秒
60, // 指示弧角度
true // 顺时针
);
2. 样式
cpp 复制代码spinner->setMainStyle(16, 0xdddddd, nullptr);
spinner->setIndicStyle(16, 0x1687d9, nullptr);
setMainStyle 配置背景圆环,背景本身会设为透明;setIndicStyle 配置旋转圆弧并强制圆头。img 是 LVGL 图片源指针,必须保持有效。
3. 动画控制
cpp 复制代码void setAnim(
int angle = 60,
int time = 2000,
bool clockwise = true,
int repeat = -1,
int startangle = 0
);
cpp
复制代码
spinner->setAnim(90, 1200, true, -1, 0);
参数:
| 参数 | 说明 |
|---|---|
| angle | 指示弧长度,建议 1..360 |
| time | 转一圈耗时,毫秒 |
| clockwise | true 顺时针,false 逆时针 |
| repeat | -1 无限,0 不重复,大于 0 为重复次数 |
| startangle | 起始角,用于停止后继续 |
setAnim 会先删除该 object 上匹配的动画,再分别启动终点角和起点角两个动画。time、angle 没有范围校验,不要传 0、负数或极端值。
停止和恢复:
cpp 复制代码int angle = spinner->getCurrentAngle();
spinner->stopAnim();
// 使用停止角继续,减少跳回 0 的视觉突变
spinner->setAnim(60, 2000, true, -1, angle);
GetAnim 返回内部 lv_anim_t 指针,仅用于即时检查,不应缓存或释放;setAnim/stopAnim 后原指针可能失效。
4. setValue 的含义
cpp 复制代码void setValue(int time);
与多数控件不同,STTSpinner 的 value 是“每圈耗时毫秒”,不是速度或业务数值:
cpp 复制代码spinner->setValue(1000); // 约 1 秒一圈
setValue 会按当前弧长和方向重建无限动画。
5. 变量到转速的映射
cpp 复制代码void setRanges(int minv, int maxv, int mins, int maxs);
minv/maxv 是变量范围,mins/maxs 是对应速度,单位为圈/10 秒。
cpp 复制代码spinner->setRanges(-100, 100, -20, 20);
Ivariable speed = getRuntime()->getIVarMgr()->get("MotorSpeed");
if (speed != nullptr) {
spinner->bindData(speed);
}
映射公式:
text 复制代码curS = (value - minV) / (maxV - minV) × (maxS - minS) + minS
每圈耗时(ms) = 10000 / curS
负 curS 表示逆时针,正值顺时针,0 会用 2147483647 ms 模拟近似停止。
实现细节:
- 内部用整数并放大 1000 计算,存在截断。
- value 不会被限制到 minV..maxV,超范围会外推速度。
- onDataChanged 先调用一次 setValue(value),随后又按映射结果 setAnim,第一次重建动画是冗余动作。
- minV==maxV 时使用 minS 和 maxS 的平均速度。
6. API 汇总
| 方法 | 作用 |
|---|---|
| setMainArg | 位置、尺寸并启动动画 |
| setMainStyle | 背景圆环样式 |
| setIndicStyle | 指示圆弧样式 |
| setAnim | 设置弧长、圈时、方向和重复 |
| stopAnim | 停止并记录当前角 |
| GetAnim | 获取临时内部动画指针 |
| getCurrentAngle | 运行时读 current_value,停止后读缓存角 |
| setValue | 把输入当每圈毫秒重启动画 |
| setRanges | 设置变量值到转速的映射 |
| onDataChanged | 应用绑定变量 |
7. 注意事项
- time 必须为正数。
- 高速时 time 过小可能造成高刷新负载。
- 速度为 0 时并不删除动画,而是设置极长周期;要真正停止请调用 stopAnim。
- GetAnim 返回非拥有指针,禁止 delete。
- 变量映射前先调用 setRanges。
- UI/动画方法应在 LVGL 线程执行。
- onDataChanged 是框架回调。
需要确认型号或具体项目?联系技术支持 ↗