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 五条规则

  1. 每帧 begin / end 配对。 这是即时模式:界面每帧重新描述一遍,不留控件对象。
  2. 列表状态必须是 static。 bbapp_ui_list_t 里存着滚动偏移和惯性速度,放栈上每帧清零就等于每次都从顶部开始。
  3. 用了控件层,app->tap / move / up / long_press 就不再被调用。两套二选一,SDK 里判断 bbapp_ui__used()。想完全自己控制(绘图、游戏)就别用这层。
  4. 返回键永远是 SDK 的。 控件层不会把左上角那块交出去。
  5. 改数据放到 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 拉回来

限制(明确不做)

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);   /* 纯画,没有交互 */

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 动画 跳转生硬 ——
横向列表、网格 相册类界面做不了 自己算
bbui 第三方应用 SDK · API 1 · 本文档随仓库 docs/sdk 自动生成