SDK 文档 / 13 · 控件层(列表 / 按钮 / 开关 / 滑块)
13 · 控件层(列表 / 按钮 / 开关 / 滑块)
实现:
sdk/bbapp_ui.c· 声明:sdk/bbapp.h后半段 · 从 API v2 开始有
13.1 为什么有这一层
安卓应用不写手势,不是因为安卓没有手势,而是因为手势被封装在控件里:setOnClickListener 背后是 getScaledTouchSlop()(位移超过 8dp 才算滑动),setOnLongClickListener 背后是一个 500ms 的 CheckForLongPress runnable,RecyclerView 背后是 OverScroller 算惯性。
SDK v1 只有原始事件(tap/move/up),等于把上面这些全丢给写应用的人。一个滚动列表光手势就要两百行,还没算惯性、回弹、按下高亮、滚动条。
这一层就是把这些做掉:应用只写"这一行画什么"。
应用代码 控件层
───────────────────────────── ──────────────────────────
bbapp_ui_list_begin(...) → 收事件、算偏移、处理阻尼和惯性
for 可见的每一行: → 告诉你是哪几行、每行 y 多少
画它 (你只画内容)
bbapp_ui_list_end() → 画滚动条、继续出帧
list.clicked / long_pressed ← 这一帧谁被点了 / 谁被长按了
13.2 五条规则
- 每帧
begin/end配对。 这是即时模式:界面每帧重新描述一遍,不留控件对象。 - 列表状态必须是
static。bbapp_ui_list_t里存着滚动偏移和惯性速度,放栈上每帧清零就等于每次都从顶部开始。 - 用了控件层,
app->tap / move / up / long_press就不再被调用。两套二选一,SDK 里判断bbapp_ui__used()。想完全自己控制(绘图、游戏)就别用这层。 - 返回键永远是 SDK 的。 控件层不会把左上角那块交出去。
- 改数据放到 draw 之后。
list.clicked是本帧开始时结算的上一次触摸结果,draw 里看到它就可以改数据,下一帧生效。
13.3 按钮
void draw(cairo_t *cr, int W, int H)
{
bbapp_ui_begin(cr, W, H);
if (bbapp_ui_button(bb_rect(20, 20, 120, 44), "确定", 1))
do_something();
if (bbapp_ui_button(bb_rect(20, 80, 120, 44), "取消", 0))
do_other();
bbapp_ui_end();
}
| 参数 | 说明 |
|---|---|
r |
矩形(bb_rect(x, y, w, h)) |
label |
文字,居中 |
primary |
1 = 强调色(主操作),0 = 普通 |
返回 1 的条件:按下和抬起都在这个矩形里,且整次按压的位移没超过 8px。按住时会有高亮,拖出去高亮消失、抬起也不算点击——和安卓一致。
13.4 列表(核心)
最小用法
static bbapp_ui_list_t list = BBAPP_UI_LIST_INIT; /* 必须是 static */
static void draw(cairo_t *cr, int W, int H)
{
bbapp_ui_begin(cr, W, H);
bbapp_ui_list_begin(&list, bb_rect(0, 44, W, H - 44), n_items, 50);
for (int i = list.first; i < list.last; i++) {
double y = bbapp_ui_list_y(&list, i);
bbapp_panel(cr, 10, y + 4, W - 20, 42, 0.06);
bbapp_text(cr, items[i], 22, y + 28, 14, 0, BB_C_TXT_R, BB_C_TXT_G, BB_C_TXT_B);
}
bbapp_ui_list_end(&list);
bbapp_ui_end();
if (list.clicked >= 0) open_item(list.clicked);
if (list.long_pressed >= 0) delete_item(list.long_pressed);
}
就这些。滚动、惯性、边缘橡皮筋、滚动条、按下判定全在框架里。
字段
| 字段 | 方向 | 说明 |
|---|---|---|
off |
读写 | 已向上滚了多少像素。可以自己赋初值恢复位置,也可以读出来存盘 |
vel |
读写 | 惯性速度 px/s,一般不用碰 |
first / last |
读 | 本帧要画的行是 [first, last) |
clicked |
读 | 本帧点中的行号,-1 = 没有 |
long_pressed |
读 | 本帧长按的行号,-1 = 没有 |
dragging |
读 | 正在拖(可以用来隐藏其他浮层) |
其余 _ 开头 |
— | 内部状态,别动 |
函数
| 函数 | 用途 |
|---|---|
bbapp_ui_list_begin(L, area, n, row_h) |
开始,指定可视区、行数、行高 |
bbapp_ui_list_row(L, i) |
这一行在屏上吗(不想自己算 first/last 时用) |
bbapp_ui_list_y(L, i) |
第 i 行的顶边 y |
bbapp_ui_list_end(L) |
结束,画滚动条 |
bbapp_ui_list_scroll_to(L, row, 0) |
跳到某一行(目前是直接跳,不带动画) |
bbapp_ui_list_max_off(L) |
最大可滚动距离(想自己画滚动条时用) |
行为细节
| 场景 | 表现 |
|---|---|
| 位移 < 8px 抬起 | 算点击,clicked 被设置 |
| 位移 ≥ 8px | 转成拖动,clicked 不会被设置(滑动时不会误点) |
| 按住不动 500ms | long_pressed 被设置;之后一旦移动就取消长按 |
| 拖过顶部/底部 | 有 0.35 的阻尼(橡皮筋),松手后 0.30 的系数回弹 |
| 松手时速度 > 60 px/s | 继续滑,每秒把速度衰减到 1/50 |
| 内容不满一屏 | 不能滚,off 自动回到 0 |
| 行数变少(比如删除了) | 下一次 begin 会把超出的 off 拉回来 |
限制(明确不做)
- 行高固定:不支持变高行。需要的话自己按最大的来算,行内布局自己排。
- 只有竖向:横向列表没有。相机屏宽 712,横向滚动的场景很少。
- 没有分组头 / 分隔线:要的话在行里自己画。
- 没有拖动排序:不打算做。
scroll_to不带动画:一下子跳过去。
13.5 开关 / 滑块 / 进度条
static int night_mode = 0;
static double volume = 0.6;
bbapp_ui_switch(bb_rect(20, 20, 320, 44), "夜间模式", &night_mode);
bbapp_ui_slider(bb_rect(20, 80, 320, 52), "音量", &volume, 0.0, 1.0);
bbapp_ui_progress(bb_rect(20, 150, 320, 8), 0.42); /* 纯画,没有交互 */
bbapp_ui_switch返回 1 = 用户拨了,新值已经写回*valuebbapp_ui_slider拖动中每一帧返回 1,值写回*value(已经 clamp 到[lo, hi])bbapp_ui_progress只画,不交互
13.6 布局游标
不用每次算 y:
bb_rect_t page = bb_rect(0, 44, W, H - 44);
double cursor = 12;
bbapp_ui_button(bbapp_ui_row(page, &cursor, 44, 12), "第一行", 1);
bbapp_ui_button(bbapp_ui_row(page, &cursor, 44, 12), "第二行", 0);
bbapp_ui_switch(bbapp_ui_row(page, &cursor, 44, 12), "开关", &flag);
bbapp_ui_row(area, &cursor, h, inset) 每次返回一条 x = area.x + inset、w = area.w - inset*2 的矩形,并把游标往下推 h + 8。
13.7 内部参数(想调的话)
都在 sdk/bbapp_ui.c 顶部:
| 宏 | 默认 | 含义 |
|---|---|---|
UI_SLOP |
8.0 |
超过这么多像素算拖动而不是点击 |
UI_EDGE_DAMP |
0.35 |
拖过边界时的阻尼系数 |
UI_FLING_STOP |
30.0 |
惯性低于这个速度(px/s)就停 |
长按阈值用的是 bbapp.h 里的 BBAPP_LONGPRESS_MS(500),点击阈值 BBAPP_TAP_SLOP(12)是给不用控件层的原始事件模式用的,两者不是同一个数。
13.8 测试
控件层的逻辑(点击/拖动/长按/惯性/边界)有本机测试,不需要设备也不需要 cairo:
zig cc -Itools/test -Isdk tools/test/uitest.c sdk/bbapp_ui.c -o uitest -lm
./uitest
19 条断言,覆盖:按下不立即算点击、小抖动仍算点击、拖动转滚动、拖动后抬起不触发点击、惯性继续滑并最终停下、长按 500ms 触发、拖动取消长按、越界阻尼、松手回弹、列表外按下不接管、可见范围计算、行数变少后位置归位。
状态:本机 19 条断言 + 真机(712×400,fts_ts_3269)都验过 ——列表滚动、长按删除、点击命中、惯性手感均正常,默认参数不需要调。
13.9 还没做
| 缺 | 影响 | 替代做法 |
|---|---|---|
| 文本输入 | ✅ 已实现,见 14 文本输入 | —— |
| 对话框 / 确认框 | 删除确认要自己做 | 用"点两下确认"(管理页就这么干的) |
| 分段控件、下拉菜单 | 设置页少点花样 | 用一排按钮 |
scroll_to 动画 |
跳转生硬 | —— |
| 横向列表、网格 | 相册类界面做不了 | 自己算 |