菜单

STTList使用手册

下载

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)。
最近修改: 2026-10-21Powered by