STTDropdown.h 使用手册

STTDropdown 是带键值数据源的下拉框。每项通常包含 id 和 name：界面显示 name，业务值使用 id。它支持内置 JSON 表、外部 TTable/TTableView/TRecipe 和普通变量双向绑定。

1. 创建

#include "widgets/STTDropdown.h"

using namespace stt;

STTDropdown* dropdown =
    new STTDropdown(getRuntime(), parent, "ddMode");

dropdown->setMainArg(
    20, 20, 180, 40,
    R"([{"id":"auto","name":"自动"},{"id":"manual","name":"手动"}])",
    0,
    ScrollDir::BOTTOM,
    nullptr,
    180,
    true
);

h_list>0 时限制弹出列表高度。dir 常用 LEFT=1、RIGHT=2、TOP=4、BOTTOM=8。

2. 选项数据

2.1 JSON 内置表

dropdown->setOptions(
    R"([{"id":"1","name":"低速"},{"id":"2","name":"高速"}])",
    0
);
dropdown->addOption("3", "检修");

setOptions 会重建内部 TTable，随后 setSelected(selectedIndex, false)。selectedIndex 是行序号，不是 id。

addOption 只对正在使用内部表时有效，允许重复 id。字符串由 JSON 解析，输入应是可信 JSON。

2.2 清除和计数

int rows = dropdown->getOptionCount();
int shown = dropdown->getOptionCnt();
dropdown->clearOptions();

• getOptionCount 返回数据源行数。
• getOptionCnt 返回 LVGL 当前显示项数。
• clearOptions 同时清数据源 rows 和 LVGL 项；getData 为 nullptr 时会崩溃，应在初始化数据源后调用。

2.3 数据源

TTable* data = dropdown->getData();

使用内部表时返回内部拥有的 TTable；绑定表变量时返回 bindVar 强转的表。都是借用指针，调用方不得 delete。

3. 选择与取值

dropdown->setSelected(1, true);

int index = dropdown->getSelectedIndex();
string text = dropdown->getSelectedText();
string value = dropdown->getSelectedValue();

notify=true 会：

1. 更新内部表或绑定表的 selectedIndex，或把 id 写回普通变量。
2. 主动发送 LV_EVENT_VALUE_CHANGED。

越界 index 被静默忽略。getSelectedText 使用固定 64 字节缓冲区，较长文本可能被截断。getSelectedValue 取数据源第 0 列。

4. 绑定变量

绑定表：

dropdown->bindData(tableVariable);

表类型会用其 label 列构造显示项，并同步 selectedIndex。表没有已选项且有数据时，当前实现自动选择第 0 行并回写表。

绑定普通变量：

dropdown->setOptions(options, 0);
dropdown->bindData(getRuntime()->getIVarMgr()->get("ModeId"));

普通变量的文本会与数据源第 0 列 id 比较；命中时切换显示。用户选中后把 id 写回变量。

5. 样式和字体

dropdown->setMainStyle(
    6, 0xffffff, 0xf5f5f5, 1,
    1, 0xcccccc, 0, 0x000000
);
dropdown->setListSelectedStyle(
    4, 0x1687d9, 0x1687d9, 0,
    0, 0x000000
);
dropdown->setFonts(
    0x222222, 16, "", false,
    0xffffff, 16, "", 0, 0
);

getListStyle 返回弹出列表的 STTStyle，可做进一步设置。该样式绑定到底层 list object，控件销毁或 LVGL 重建后不可继续使用。

6. 方向、图标和展开

dropdown->setDir(ScrollDir::BOTTOM);
dropdown->setSymbol(ICON::get(ICON::DOWN), true);
dropdown->setSelectedHightlight(true);

dropdown->expand();
dropdown->collapse();

getDir、getSymbol、getSelectedHightlight 可读取底层状态。

setSymbol：

• nullptr 或空字符串移除图标。
• isself=true 使用 Runtime 字体管理器的内置图标字体。
• isself=false 沿用当前 indicator 字体，传入指针必须为 LVGL 可识别符号或图片源。

7. 确认模式

通过 STTWidget::setConfirm 开启后，取消会恢复 lastSelectedIndex，确认会重新构造 VALUE_CHANGED 事件并完成写变量/回调。onConfirm 为框架内部入口。

8. 注意事项

• JSON 项建议固定为 id/name 两列。
• selected 参数是序号，不是 id。
• getSelectedText 最多读取 63 字节加结尾零。
• addOption 允许重复 id，普通变量匹配时取第一个。
• clearOptions 前确保 getData 非空。
• setSelected(notify=true) 会主动发事件，避免在事件回调中无条件再次调用造成递归。
• getData/getListStyle/getSymbol 都返回借用数据。