STTList.h 使用手册
STTList 是纵向按钮列表,支持内置键值表、外部表变量、普通变量双向绑定以及直接添加原生按钮。数据项模式和 addButton 模式不能混用。
1. 创建与样式
cpp 复制代码#include "widgets/STTList.h"
using namespace stt;
STTList* list = new STTList(getRuntime(), parent, "listRecipe");
list->setMainArg(20, 20, 220, 300, true);
list->setMainStyle(4, 0xffffff, 0xf7f7f7, 1, 1, 0xcccccc);
list->setFonts(0x222222, 0xffffff, 16, "", 0);
list->setButtonStyleSelected(3, 0x1687d9, 0x1687d9, 0, 0);
setOptions 应放在字体和按钮样式之后,因为它会创建子按钮。
2. 数据项模式
cpp 复制代码list->setOptions(
R"([{"id":"r1","name":"配方一"},{"id":"r2","name":"配方二"}])"
);
list->addOption("r3", "配方三");
bool removed = list->removeOption("r2");
行为:
- addOption 仅对内部表有效,允许重复 id。
- 如果内部表尚不存在,addOption 会手工拼 JSON,id/name 中的引号未转义,不能使用未验证文本。
- removeOption 删除第一个命中 id,仅内部表有效。
- clearOptions 清除数据源 rows,onDataChanged 会负责重建显示;外部表时会直接修改绑定表数据。
读取:
cpp 复制代码int rows = list->getOptionCount();
int buttons = list->getOptionCnt();
vector<KV_Str_Str> options = list->getOptions();
vector<string> ids = list->getIds();
vector<string> names = list->getNames();
TTable* data = list->getData();
getOptionCount 是数据行数,getOptionCnt 是当前子按钮数。getData 返回借用指针。
3. 选择
cpp 复制代码list->setSelected(1, true);
int index = list->getSelectedIndex();
string name = list->getSelectedText();
string id = list->getSelectedValue();
notify=true 会同步数据表 selectedIndex 或普通绑定变量,并分发事件。越界 index 的实际处理受子按钮数量和实现检查影响,调用方应先验证。
设置单项显示:
cpp 复制代码list->setItemTextColor(0, 0xff0000);
list->setItemTextAlign(0, 1); // 0 左,1 中,2 右
索引不存在时方法会静默返回。单项设置覆盖默认字体颜色/对齐。
4. 变量绑定
表绑定:
cpp 复制代码list->bindData(tableVariable);
表的 label 列用于按钮文字,第 0 列用于 value。表 selectedIndex 变化时列表同步。
普通变量:
cpp 复制代码list->setOptions(options);
list->bindData(getRuntime()->getIVarMgr()->get("RecipeId"));
普通变量文本与第 0 列比较;用户选择后把 id 写回变量。
5. addButton 模式
cpp 复制代码void* rawButton = list->addButton("res/add.png", "新建");
addButton 只创建界面子按钮,不修改数据源,因此 setSelected/getSelectedValue 等数据项语义不适用。返回的是 lv_obj_t* 借用指针,不能 delete,应由父 LVGL 对象管理。
不要与 addOption/setOptions 混用,否则子控件索引与数据行会不一致。
6. 使能与确认
cpp 复制代码list->setEnable(false);
该重载同时给容器和所有当前子按钮设置 DISABLED,并增删 CLICKABLE 标志。禁用后新增按钮不会自动继承之前遍历的状态,应在增项后再次 setEnable。
开启 STTWidget 确认后,取消恢复 lastSelectedIndex,确认执行 currentClickIndex 对应选择。onConfirm 是内部回调。
7. 注意事项
- setOptions 在样式设置之后调用。
- 数据项模式与 addButton 模式不要混用。
- addOption 手工拼 JSON,id/name 必须可信且不含未转义引号。
- clearOptions 可能直接清空外部绑定表。
- getData 和 addButton 返回值均为非拥有指针。
- 选择事件中避免再次无条件 setSelected(notify=true)。
- 新增子按钮后如列表已禁用,应重新 setEnable(false)。
需要确认型号或具体项目?联系技术支持 ↗