菜单

STTSwitch使用手册

下载

STTSwitch.h 使用手册

STTSwitch 是双态开关控件，支持变量双向绑定、确认框、蜂鸣和操作日志。通用能力由 STTWidget 提供。

1. 创建

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

using namespace stt;

STTSwitch* sw = new STTSwitch(getRuntime(), parent, "swPump");
sw->setMainArg(20, 20, 64, 32, false, true);

参数 ison 为初始状态，isbeep 控制用户操作蜂鸣。setMainArg 只在 ison=true 时添加 CHECKED 状态；重复调用时传 false 不会主动关闭旧状态，需显式 off。

2. 状态 API

cpp 复制代码 
sw->on();
sw->off();
sw->toggle();

bool enabled = sw->isOn();

on/off 通过 LV_STATE_CHECKED 控制状态。程序直接调用这些方法通常不会走用户 VALUE_CHANGED 确认和日志流程；若还需同步变量，应按业务显式写变量。

3. 样式

cpp 复制代码 
sw->setMainStyle(
    9999, 0xcccccc, 0xbbbbbb, 2,
    1, 0x999999, 0, 0x000000
);

sw->setIndicStyle(
    9999, 0x16a05d, 0x55c98b, 2,
    0, 0x000000, 0, 0x000000
);

sw->setKnobStyle(
    9999, 0xffffff, 0xeeeeee, 1,
    1, 0xaaaaaa, 1, 0x888888
);
方法 作用的 LVGL selector
setMainStyle LV_PART_INDICATOR 的未选中状态
setIndicStyle LV_PART_INDICATOR 与 CHECKED 状态
setKnobStyle LV_PART_KNOB

参数依次为圆角、主色、渐变色、渐变方向、边框宽/色、阴影宽/色。

4. 变量绑定

cpp 复制代码 
Ivariable pump = getRuntime()->getIVarMgr()->get("PumpEnable");
if (pump != nullptr) {
    sw->bindData(pump);
}

用户切换时，控件将 "0" 或 "1" 写回 bindVar。变量变化时：

  • 字符串 "0" 或 "false" 关闭。
  • 其他任何文本开启，包括 "False"、空文本或非数字文本。

如果变量可能产生多种布尔格式，应在数据层统一为 0/1。

5. 确认、日志与事件

cpp 复制代码 
sw->setConfirm(true, "确认切换水泵状态？");
sw->setOpLog(true);
sw->onEventHandler(LV_EVENT_VALUE_CHANGED, this,
                   (EHandler)&Frm01::onPumpChanged);

启用确认后，用户操作先显示确认框：

  • 取消时恢复原 CHECKED 状态。
  • 确认时写变量、写操作日志，然后调用注册回调。

操作日志动作名为 "switch"，信息记录旧/新值。日志由 OpLogMgr 异步落盘。

当前确认事件队列是 cpp 文件级全局 vector，不属于单个控件。多个开关同时打开确认流程可能互相清空或消费队列，应避免并发弹出多个开关确认框。

6. 完整示例

cpp 复制代码 
void Frm01::setupPumpSwitch(STTWidget* panel) {
    STTSwitch* sw = new STTSwitch(getRuntime(), panel, "swPump");
    sw->setMainArg(20, 20, 72, 36, false, true);
    sw->setConfirm(true, "确认修改水泵启停状态？");
    sw->setOpLog(true);

    Ivariable value = getRuntime()->getIVarMgr()->get("PumpEnable");
    if (value != nullptr) {
        sw->bindData(value);
    }
}

7. 注意事项

  • 重复 setMainArg(false) 不会清除已开启状态，应调用 off。
  • onDataChanged 对布尔字符串大小写敏感。
  • 确认队列为全局共享，不适合多个开关同时确认。
  • onConfirm 与 onDataChanged 是框架回调，通常不直接调用。
  • UI 和状态方法应在 LVGL 线程执行。
  • 程序直接 on/off 后如需变量同步，要显式更新绑定变量。
最近修改: 2026-10-21Powered by