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 |
每帧调用,画键盘 + 处理点击 |
你能用的:
bbapp_ui_tap_in(r)—— 这一帧在这个矩形里完成了一次点击(按下和抬起都在里面、没拖动)bbapp_ui_input_put / back / clear—— 改文本,UTF-8 安全bbapp_ui_input_focus(NULL)—— 收起键盘- 画图用
bbapp_panel / bbapp_text / bbapp_rrect,和别处一样
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 上不挤,键宽够点。