SDK 文档 / 14 · 文本输入(输入框 + 键盘 + 拼音)

14 · 文本输入(输入框 + 键盘 + 拼音)

实现:sdk/bbapp_ime.c · 从 API v2 开始有 · 默认就有,不用配

14.1 为什么必须自己做

这台设备的 weston 没有 wl_seat,wayland 客户端收不到键盘事件,系统输入法(fcitx / ibus)在这套环境里接不上。bbui 自己的中文输入法(src/ime.c)就是因此从零写的:词库、候选算法、候选条全在进程内。

SDK 把这套搬过来,应用侧只需要一个输入框,键盘自动弹。

14.2 三行用法

static bbapp_ui_input_t name = BBAPP_UI_INPUT_INIT;

static void draw(cairo_t *cr, int W, int H)
{
    bbapp_ui_begin(cr, W, H);

    int ih = bbapp_ui_ime_height();      /* 键盘占多高,0 = 没弹出 */

    if (bbapp_ui_input(bb_rect(20, 20, W - 40, 44), &name, "输入名字", BBAPP_IME_TEXT))
        bbapp_kv_set("name", name.text);  /* 返回 1 = 内容变了 */

    /* 下面的内容要让出 ih,否则被键盘盖住 */

    bbapp_ui_ime();                       /* 放最后画,盖在最上面 */
    bbapp_ui_end();
}

点输入框弹键盘(和安卓一样),点「收起」或「↵」收起来。

14.3 输入框

typedef struct {
    char   text[192];   /* UTF-8,始终以 \0 结尾,直接当字符串用 */
    int    len;         /* 字节数(不是字符数) */
    int    max_len;     /* 最多多少字节,0 = 用默认 191 */
    int    focused;
    ...
} bbapp_ui_input_t;

#define BBAPP_UI_INPUT_INIT { {0}, 0, 0, 0, 0, 0 }
函数 说明
bbapp_ui_input(r, in, placeholder, mode) 画输入框;返回 1 = 这一帧文本变了
bbapp_ui_input_focus(in) 手动聚焦;传 NULL 收起键盘
bbapp_ui_input_put(in, "字") 追加一段(UTF-8 安全)
bbapp_ui_input_back(in) 删一个字符(不是删一个字节)
bbapp_ui_input_clear(in) 清空

长度按字节算:text[192] 意味着中文最多 63 个汉字。超了 put 直接不写,不会截半个字符。

14.4 默认键盘

┌──────────────────────────────────────────────────────────┐
│ pinyin  你 泥 拟 逆 妮 倪 腻 …                       收起 │  30
├──────────────────────────────────────────────────────────┤
│  q  w  e  r  t  y  u  i  o  p                            │  38
│   a  s  d  f  g  h  j  k  l                              │  38
│  ⇧  z  x  c  v  b  n  m  ⌫                               │  38
│  123  中/英   [    空格    ]   。  ,  ↵                  │  38
└──────────────────────────────────────────────────────────┘

总高 188px(400 高的屏幕上不到一半)。

行为 说明
第一次弹出 有词库就默认中文,中文用户不用每次手动切
中/英键 切换;没词库时点了会提示「没有拼音词库」
中文模式打字母 进拼音串,不直接上屏,候选条出现
空格 中文有候选 → 上屏第一个;没候选 → 拼音原样上屏;英文 → 空格
↵ 有候选先上屏;否则收起键盘
123 切数字/符号页(第二页有 ()[]{}%*=@ 等)
⇧ 大小写(只影响英文)
退格 中文有拼音先退字母;否则删输入框一个字符
候选条 最多显示 8 个,第一个高亮,点一下上屏

键盘会挡住下面的控件:弹出时,键盘区域内的按钮和列表都不响应触摸,不会出现「点键盘顺带点了内容」。

14.5 让内容给键盘让位

int ih = bbapp_ui_ime_height();     /* 0 或 188(或自定义输入法的高度) */
double content_h = H - ih;

它读的是上一帧的焦点状态:点输入框那一帧还是 0,下一帧才变成 188。差一帧,视觉上会闪一下——安卓的 adjustResize 也有动画延迟,这个量级可以接受。

不想让内容动也行,把内容画成全屏、让键盘盖上去,代价是键盘下面那截看不见。

14.6 自己做输入法(像安卓换 IME)

默认键盘不合适的场景——只要数字(输入端口号)、只要几个预设选项、手写、日期选择、表情——都可以自己实现,SDK 把整块键盘区域交给你。

static void my_kb(cairo_t *cr, bb_rect_t area, bbapp_ui_input_t *in)
{
    static const char *keys[] = { "1","2","3","4","5","6","7","8","9","0" };

    double w = area.w / 5.0, h = area.h / 2.0;
    for (int i = 0; i < 10; i++) {
        double x = area.x + (i % 5) * w;
        double y = area.y + (i / 5) * h;
        bb_rect_t r = bb_rect(x + 4, y + 4, w - 8, h - 8);

        bbapp_panel(cr, r.x, r.y, r.w, r.h, 0.14);
        bbapp_text_c(cr, keys[i], r.x + r.w / 2, r.y + r.h / 2 + 6, 18, 0, 1, 1, 1);

        if (bbapp_ui_tap_in(r)) bbapp_ui_input_put(in, keys[i]);
    }
}

static const bbapp_ime_impl_t MY_IME = { "数字键盘", 150, my_kb };

bbapp_ime_use(&MY_IME);      /* 换成自己的 */
bbapp_ime_use(NULL);         /* 恢复默认中文键盘 */
字段 说明
name 只用于日志和 bbapp_ime_current()
height 键盘占多高,自己算;bbapp_ui_ime_height() 直接返回它
draw 每帧调用,画键盘 + 处理点击

你能用的:

SDK 负责的:键盘背景板、挡住下面控件的触摸、ime_height() 的返回值。你负责的:键的位置、长什么样、点了做什么。

bbapp_ime_use() 随时能调,立即生效。

14.7 拼音词库

项 说明
文件 pinyin.bin,约 2 MB
来源 bbui 的 data/pinyin/pinyin.bin(tools/mkpinyin.py 从 rime-ice 生成)
查找顺序 $BBAPP_PINYIN → /blackbox/data/pinyin/pinyin.bin → /mnt/media_rw/emulated/blackbox/data/pinyin/pinyin.bin → /blackbox/pinyin/pinyin.bin
找不到时 打一行日志,键盘退化纯英文,不会崩

检查设备上有没有:

adb shell ls -l /blackbox/data/pinyin/pinyin.bin

没有就推上去(2 MB):

adb push data/pinyin/pinyin.bin /blackbox/data/pinyin/pinyin.bin

本机调试时用环境变量指过去:

BBAPP_PINYIN=$PWD/data/pinyin/pinyin.bin ./notes

14.8 限制(说清楚,别指望)

没有 说明 变通
光标移动 只能在末尾追加/删除,点中间不会移动光标 需要编辑长文本就自己实现
选区 / 复制粘贴 没有 ——
英文联想 只补单字符 ——
多行输入 输入框是单行 用列表
手写 / 语音 —— 自己实现 bbapp_ime_impl_t
密码遮点 BBAPP_IME_PASSWORD 还没实现 自己画

14.9 测试

拼音逻辑有本机测试,用真实词库,不需要设备:

BBAPP_PINYIN=data/pinyin/pinyin.bin \
  zig cc -Itools/test -Isdk tools/test/imetest.c sdk/bbapp_ime.c -o imetest -lm
BBAPP_PINYIN=data/pinyin/pinyin.bin ./imetest

12 条断言:单音节(ni/wo/hao)、词语(nihao/zhongguo/xiexie/beijing)、长串首词(womendediannao → 我们)、空串、非法拼音、候选去重。全部通过。

状态:本机 12 条断言 + 真机全链路验过 ——点输入框弹键盘 → 打字出候选(ni → 你 尼 泥 逆…)→ 点候选上屏 → 写入 kv.conf。键盘 188px 高在 712×400 上不挤,键宽够点。

bbui 第三方应用 SDK · API 1 · 本文档随仓库 docs/sdk 自动生成