STTQRCode.h 使用手册
STTQRCode 封装 LVGL 二维码对象,可显示文本或任意字节序列。虽然头文件包含 STTCanvas.h,但类本身继承 STTWidget。
1. 必须先初始化
构造函数只初始化类型和内部指针,并不创建底层二维码 object。必须先调用一次 setMainArg:
cpp 复制代码#include "widgets/STTQRCode.h"
using namespace stt;
STTQRCode* qr = new STTQRCode(getRuntime(), parent, "qrOrder");
qr->setMainArg(
20, 20, 180, 180,
0xffffff,
0x000000,
"ORDER:20261020-001"
);
在 setMainArg 之前调用 update、setSize 或析构一个未完成初始化的对象,都可能访问空 object。创建后应立即完成 setMainArg。
2. setMainArg 行为
cpp 复制代码void setMainArg(
int x = 0, int y = 0, int w = 100, int h = 100,
int background = 0xffffff,
int foreground = 0x000000,
const char* data = "www.simtutai.com"
);
第一次调用时:
- 实际二维码边长使用 max(w, h),小于等于 0 时使用 100。
- 创建底层对象、设置颜色和位置。
- 使用 strlen(data) 更新二维码,所以 data 必须是非空、以零结尾的字符串。
后续再次调用 setMainArg 只执行 setSize(w, h),不会更新位置、颜色或 data。这是当前实现的重要差异,不应把第二次调用当作完整重新配置。
3. 更新内容
字符串重载:
cpp 复制代码uint8_t rc = qr->update("https://example.com/order/001");
字节重载:
cpp 复制代码const char payload[] = {'A', 'B', '\0', 'C'};
uint8_t rc = qr->update(payload, sizeof(payload));
签名:
cpp 复制代码uint8_t update(const void* data, int data_len);
uint8_t update(const string& data);
返回值直接来自 lv_qrcode_update。头文件写“1 成功、0 失败”,但 LVGL 版本的 lv_res_t 枚举语义可能相反或不同,应以本工程所用 LVGL 定义为准,不要硬编码 rc==1。至少可在真机上用已知短文本验证。
void* 重载还会把 data 当 C 字符串保存到内部 string,因此即便 data_len 支持二进制,中间零字节后的缓存内容会截断;控件改变尺寸后重绘只会使用截断后的缓存。需要二进制二维码时,尺寸变更后应再次传完整数据。
4. 尺寸接口
cpp 复制代码qr->setSize(220, 220);
setSize 会重新分配 1 bit canvas 缓冲区并用缓存内容重绘。二维码通常应保持正方形。
当前实现:
cpp 复制代码qr->setWidth(200); // 空操作
qr->setHeight(200); // 空操作
setWidth 和 setHeight 的底层调用已被注释,虽然返回 this,但不会改变尺寸。必须使用 setSize。
缓冲区 realloc 没有显式检查失败;避免频繁以大尺寸反复缩放。
5. 变量绑定
cpp 复制代码Ivariable code = getRuntime()->getIVarMgr()->get("OrderQRCode");
if (code != nullptr) {
qr->bindData(code);
}
onDataChanged 直接用 data->toStr() 更新二维码。变量文本过长可能因当前尺寸和二维码容量不足而更新失败。
6. 完整示例
cpp 复制代码STTQRCode* qr = new STTQRCode(getRuntime(), panel, "qrTrace");
qr->setMainArg(32, 32, 200, 200, 0xffffff, 0x111111, "INIT");
string trace = "TRACE|SN=ABCD1234|DATE=20261020";
uint8_t status = qr->update(trace);
// 需要调整时使用 setSize,不使用 setWidth/setHeight
qr->setSize(240, 240);
7. 注意事项
- 构造后必须先调用 setMainArg。
- data 指针不能为 nullptr,C 字符串必须以零结尾。
- setWidth/setHeight 当前无效。
- 第二次 setMainArg 不会更新颜色、位置和内容。
- update 返回值应按当前 LVGL 的 lv_res_t 定义解释。
- 控件内容越长,所需二维码版本越高;尺寸太小会影响生成或扫描。
- onDataChanged 属于框架回调,一般不直接调用。