SDK 文档 / 09 · API 参考
09 · API 参考
头文件:
sdk/bbapp.h· API 版本:2(2026-11-03)· 实现:sdk/bbapp_run.c+sdk/bbapp_ui.c(源码分发,一起编译)全部符号都由 SDK 提供,应用只需#include "bbapp.h"。
9.0 符号总表
| 类别 | 符号 | 一句话 |
|---|---|---|
| 应用描述 | bbapp_app |
回调和标识的结构体 |
| 入口 | BBAPP_MAIN(app) |
宏,生成 main() |
| 入口 | bbapp_main(app) |
真正的主循环(宏展开后调用) |
| 画布 | bbapp_width() / bbapp_height() |
当前画布尺寸(712×400) |
| 时间 | bbapp_now() |
单调时钟(秒,double) |
| 路径 | bbapp_data_dir() |
可写目录 |
| 路径 | bbapp_assets_dir() |
只读资源目录 |
| 输出 | bbapp_log(fmt, ...) |
写 stderr + app.log |
| 输出 | bbapp_toast(fmt, ...) |
底部提示 2.5 秒 |
| 刷新 | bbapp_redraw() |
请求重绘 |
| 逃生 | bbapp_quit() |
回 bbui,不返回 |
| 进程 | bbapp_shell(cmd) |
后台跑一条 shell |
| 绘制 | bbapp_rrect() |
圆角矩形路径 |
| 绘制 | bbapp_panel() |
半透明面板(填充+描边) |
| 绘制 | bbapp_text() |
左对齐/指定 x 写文字 |
| 绘制 | bbapp_text_c() |
水平居中写文字 |
| 绘制 | bbapp_text_w() |
量文字宽度 |
| 输入 | down / move / up / long_press |
v2:带按压时长和拖动标记 |
| 生命周期 | pause / resume / destroy |
v2:后台 / 恢复 / 退出钩子 |
| 系统 | bbapp_battery() / bbapp_charging() |
电量 0..100 / 是否充电 |
| 系统 | bbapp_wifi() |
有没有网 |
| 时间 | bbapp_wall_now() |
墙钟(显示日期用) |
| 存储 | bbapp_kv_get / bbapp_kv_set / bbapp_kv_del |
持久化键值,重启还在 |
| 存储 | bbapp_kv_get_int / set_int / get_double / set_double |
数值便捷版 |
| 存储 | bbapp_kv_flush / bbapp_kv_clear |
立即落盘 / 清空 |
| 网络 | bbapp_http_get(url, cb, user) |
异步 GET,回调给状态码和 body |
| 网络 | bbapp_http_cancel / bbapp_http_busy |
取消 / 还在跑吗 |
| 控件 | bbapp_ui_begin / bbapp_ui_end |
控件层每帧的开始和结束 |
| 控件 | bbapp_ui_button / switch / slider / progress |
常用控件 |
| 控件 | bbapp_ui_list_* |
滚动列表(13 整章) |
| 控件 | bbapp_ui_row |
布局游标 |
| 输入 | bbapp_ui_input() |
输入框(点一下弹键盘) |
| 输入 | bbapp_ui_ime() / bbapp_ui_ime_height() |
画键盘 / 键盘占多高 |
| 输入 | bbapp_ui_input_put / back / clear |
改文本(UTF-8 安全) |
| 输入 | bbapp_ui_input_focus() |
聚焦 / 收起键盘 |
| 输入 | bbapp_ui_tap_in() |
这一帧某矩形里点了一下 |
| 输入 | bbapp_ime_use() / bbapp_ime_current() |
换输入法 / 当前用的哪个 |
| 绘制 | bbapp_clip_rrect() |
把裁剪区设成圆角 |
| 常量 | BBAPP_API_VERSION |
当前为 2 |
| 常量 | BB_C_BG_* / BB_C_TXT_* / BB_C_DIM_* / BB_C_ACC_* |
主题色 |
9.1 类型与入口
bbapp_app
应用描述结构体。静态常量定义,SDK 只读它,不会释放。
typedef struct {
const char *id; /* 只用于日志 */
const char *name; /* 只用于日志 + 窗口标题 */
int (*init)(void); /* 可选,非 0 = 启动失败 */
void (*draw)(cairo_t *cr, int w, int h); /* 必填 */
int (*tap)(int x, int y); /* 可选 */
void (*tick)(double now); /* 可选 */
} bbapp_app;
| 成员 | 必填 | 调用时机 | 说明 |
|---|---|---|---|
id |
否 | 启动时写一次日志 | 建议与 app.json 的 id 一致;NULL 时日志里是 ? |
name |
否 | 启动时写日志、wl_shell_surface 标题 |
不影响桌面显示(桌面用 app.json) |
init |
否 | surface/触摸就绪之后、首帧之前 | 返回非 0 → 记日志 → 回 bbui |
draw |
是 | 需要重绘时 | 缺了直接 return 2。cr 每帧都是新的 |
tap |
否 | 抬起且未拖动、且不在返回键区域 | 返回 1 = 消费(SDK 立即重绘);0 = 不重绘 |
tick |
否 | 每轮主循环(约 16 ms) | 注册即持续重绘,见 06 |
draw 里 w/h 与 bbapp_width()/height() 相同;不要假设它固定,BBAPP_ROT 会改变。
BBAPP_MAIN(app)
#define BBAPP_MAIN(app_ptr) int main(void) { return bbapp_main(app_ptr); }
用法:在文件末尾写一行 BBAPP_MAIN(&g_app)(注意没有分号,宏自带 main)。
不要在同一个进程里定义两个 BBAPP_MAIN——它展开成 main()。
bbapp_main
int bbapp_main(const bbapp_app *app);
主入口。初始化 wayland、触摸、缓冲区,进入帧循环,直到应用退出才返回(正常情况不返回)。
参数
| 参数 | 类型 | 说明 |
|---|---|---|
app |
const bbapp_app * |
指向静态生命周期的应用描述;NULL 或 draw == NULL 直接失败 |
返回值
| 值 | 含义 |
|---|---|
2 |
app 为 NULL 或没有 draw(此时 stderr 打印"没有 draw 回调") |
1 |
连不上 wayland(WAYLAND_DISPLAY 未设或合成器没起) |
0 |
帧循环因 wayland 断开而退出(罕见) |
其它失败路径(合成器缺 wl_compositor/wl_shm/wl_shell、建 buffer 失败、init 返回非 0)会直接 exec bbui 回桌面,不返回。
备注
- 内部会
mkdir(BBAPP_DATA)、注册SIGTERM/SIGINT/SIGHUP、忽略SIGCHLD/SIGPIPE; - 不要在调用前自己连 wayland 或开触摸设备,会打架。
示例
int main(void) { return bbapp_main(&g_app); } /* 等价于 BBAPP_MAIN(&g_app) */
9.2 画布与时间
bbapp_width / bbapp_height
int bbapp_width(void);
int bbapp_height(void);
当前画布尺寸(像素)。本机默认 712 × 400。
返回值:宽 / 高。永远 > 0,在 init() 里已经可用。
备注
- 受
BBAPP_W/BBAPP_H/BBAPP_ROT影响;不要把它编译期固定; - 和
draw(cr, w, h)的参数是同一份数据,二选一用即可。
示例
static void draw(cairo_t *cr, int w, int h) {
int cx = w / 2, cy = h / 2; /* 用参数,别用宏 */
bbapp_text_c(cr, "居中", cx, cy + 8, 20, 1, 1, 1, 1);
}
bbapp_now
double bbapp_now(void);
单调时钟(CLOCK_MONOTONIC),单位秒,double,带纳秒精度。
返回值:单调递增的秒数。起点是系统启动,绝对值没有意义,只用差值。
备注
- 不受用户改时间/时区影响,适合计时、动画、超时判断;
- 想显示"当前时间"得用
time(),SDK 不提供; tick(now)的参数就是这个值。
示例
static double t0;
static int running;
static void toggle(void) {
if (running) running = 0;
else { t0 = bbapp_now(); running = 1; }
}
static double elapsed(void) { return running ? bbapp_now() - t0 : 0.0; }
9.3 路径
bbapp_data_dir
const char *bbapp_data_dir(void);
可写目录,值是 $BBAPP_DATA(app-run.sh 注入为 <app>/data),跨次运行保留。
返回值:静态字符串,不需要也不应该 free。环境变量缺失时返回 "."。
备注
- 目录已由宿主创建(bbui 扫描时
mkdir -p),你可以直接写; - 升级(
unzip -o)不会覆盖它,因为安装包里没有data/; - 卸载(删应用目录)会连它一起删。
示例
char p[600];
snprintf(p, sizeof p, "%s/settings.txt", bbapp_data_dir());
FILE *f = fopen(p, "w");
if (!f) bbapp_log("打不开 %s 写设置", p);
拼路径用
snprintf+sizeof,别用sprintf:路径最长可到 512 字节。
bbapp_assets_dir
const char *bbapp_assets_dir(void);
只读资源目录,值是 $BBAPP_ASSETS(<app>/assets)。
返回值:静态字符串。环境变量缺失时返回 "."。
备注:目录不存在也算正常(应用可以没有资源)。读之前先判断 fopen 返回值。
示例
char p[600];
snprintf(p, sizeof p, "%s/logo.png", bbapp_assets_dir());
cairo_surface_t *img = cairo_image_surface_create_from_png(p);
9.4 输出
bbapp_log
void bbapp_log(const char *fmt, ...);
写一行日志:stderr 一份(前缀 [bbapp] ),$BBAPP_LOG 一份(前缀 [epoch] )。
参数
| 参数 | 说明 |
|---|---|
fmt, ... |
同 printf。单行最长 1023 字节,超出截断 |
返回值:无。
备注
- 每次调用都会
fopen/fclose一次日志文件——不重,但别在draw里每帧调用(会拖慢帧率,也会把日志刷爆); - 日志文件不存在(调试时未注入
BBAPP_LOG)就只写 stderr; - 不要在信号处理器里调用它(不是 async-signal-safe)。
示例
bbapp_log("init: 画布 %dx%d, data=%s", bbapp_width(), bbapp_height(), bbapp_data_dir());
bbapp_toast
void bbapp_toast(const char *fmt, ...);
在底部中央弹一条提示,2.5 秒后消失。
参数
| 参数 | 说明 |
|---|---|
fmt, ... |
同 printf。超过 191 字节截断 |
返回值:无。
备注
- 只有最后一条有效(覆盖,不排队);
- 自动请求重绘,不需要再调
bbapp_redraw(); - 位置固定在
y = h - 46、高 30,宽度 = 文字宽 + 28; - 会被后续
draw覆盖吗?不会——toast 在draw之后画,永远在上层; - 想在 toast 期间做动画,
tick会继续跑,两者不冲突。
示例
static int app_tap(int x, int y) {
bbapp_toast("点了 %d,%d", x, y);
return 1;
}
bbapp_redraw
void bbapp_redraw(void);
请求下一轮重绘。
返回值:无。
备注
- 注册了
tick的应用不需要它(每轮都会画); - 没有
tick的应用,在tap之外改了状态(例如bbapp_shell回来、内部定时器到点)必须调它,否则画面不动; - 从
tap里返回 1 也会触发重绘,等价于调一次。
示例
static int n;
static int app_tap(int x, int y) { (void)x; (void)y; n++; bbapp_redraw(); return 0; }
bbapp_shell
void bbapp_shell(const char *cmd);
在后台跑一条 shell 命令(fork + setsid + execl("/bin/sh","sh","-c",cmd)),立即返回。
参数
| 参数 | 说明 |
|---|---|
cmd |
交给 /bin/sh -c 的命令行。为 NULL 时子进程 _exit(127) |
返回值:无(拿不到退出码,也拿不到输出)。
备注
- 子进程在独立会话里,应用退出后它还活着——记得它可能变孤儿;
SIGCHLD被忽略,不会留僵尸;- 标准输入输出继承自应用(已被重定向到
app.log),所以命令的输出也会进日志; - 命令执行完不会通知你。需要"完成后刷新界面",自己在
tick里轮询结果文件。
示例
/* 在后台把当前时间写进 data/,不阻塞界面 */
char cmd[700];
snprintf(cmd, sizeof cmd, "date > %s/last_run.txt", bbapp_data_dir());
bbapp_shell(cmd);
bbapp_quit
void bbapp_quit(void);
主动退出:释放触摸独占 → 销毁 wl_shell_surface / wl_surface → flush →exec /blackbox/opt/bin/bbui。
返回值:不会返回(exec 成功后进程变成 bbui;两条 exec 都失败时 _exit(127))。
备注
- 正常情况下你不需要调它——左上角返回键已经替你做了;
- 有"完成/退出"按钮的应用可以调,行为与返回键完全一致;
- 调用前把要保存的数据写好:之后没有"保存回调"机会了;
- 如果只是想回桌面,不要用
exit(0):那会留下一块没销毁的 surface(见 05)。
示例
static int app_tap(int x, int y) {
if (x > 600 && y > 340) bbapp_quit(); /* 自定义"退出"按钮 */
return 1;
}
9.5 绘制助手
所有助手都只是对 cairo 的薄封装,没有隐藏状态。需要更复杂的效果时直接用 cairo。
bbapp_rrect
void bbapp_rrect(cairo_t *cr, double x, double y, double w, double h, double r);
在 cr 上建一条圆角矩形路径(不填充、不描边)。
参数
| 参数 | 类型 | 说明 |
|---|---|---|
cr |
cairo_t * |
当前帧的上下文 |
x, y |
double |
左上角 |
w, h |
double |
宽高(必须 > 0) |
r |
double |
圆角半径,自动夹到 min(w,h)/2 |
返回值:无。
备注
- 路径用
cairo_new_sub_path()开始,不会和已有路径接上; - 结束时不
close_path之外不做任何操作,所以调用后必须自己fill/stroke; - 半像素偏移(
+0.5)由调用者负责,见 06。
示例
bbapp_rrect(cr, 20, 20, 200, 56, 14);
cairo_set_source_rgba(cr, 0.34, 0.60, 0.98, 0.9);
cairo_fill(cr);
bbapp_panel
void bbapp_panel(cairo_t *cr, double x, double y, double w, double h, double alpha);
画一块"毛玻璃感"面板:白色 alpha 填充 + 亮度高 0.06 的 1px 圆角描边,圆角固定 10。
参数
| 参数 | 说明 |
|---|---|
alpha |
填充不透明度,建议 0.08 ~ 0.18。> 0.5 会很白、盖住背景 |
返回值:无。
备注
- 内部会改
cairo_set_source_rgba和cairo_set_line_width(1),调用后不恢复; - 必须在有背景的情况下用(SDK 已经铺了深蓝底);
- 想换圆角就自己用
bbapp_rrect+fill/stroke。
示例
bbapp_panel(cr, 16, 300, 680, 84, 0.10);
bbapp_text(cr, "设置", 34, 340, 18, 1, BB_C_TXT_R, BB_C_TXT_G, BB_C_TXT_B);
bbapp_text
void bbapp_text(cairo_t *cr, const char *s, double x, double baseline,
double size, int bold, double r, double g, double b);
从 x 开始写一行文字,字体固定文泉驿微米黑。
参数
| 参数 | 说明 |
|---|---|
s |
UTF-8 字符串。NULL 或空串直接返回 |
x |
左边缘(不是中心) |
baseline |
基线位置,不是顶边 |
size |
字号(px) |
bold |
非 0 = 粗体 |
r, g, b |
颜色,0..1 |
返回值:无。
备注
- 竖直居中常用
y + h/2 + size*0.36; - 不支持多行、不支持自动换行、不支持富文本;
- 每次调用都会重设字体(很轻,可以随便调)。
示例
bbapp_text(cr, "剩余 3 项", 24, 60, 16, 0, BB_C_DIM_R, BB_C_DIM_G, BB_C_DIM_B);
bbapp_text_c
void bbapp_text_c(cairo_t *cr, const char *s, double cx, double baseline,
double size, int bold, double r, double g, double b);
同上,但 cx 是水平中心(内部用 bbapp_text_w() 算宽度再左移一半)。
参数:除 cx 外同 bbapp_text。
返回值:无。
备注:居中会多一次文字度量,一帧里几十次也没问题;超长文本会左右都溢出。
示例
bbapp_text_c(cr, "12:34.56", w / 2.0, h * 0.30, 56, 1,
BB_C_TXT_R, BB_C_TXT_G, BB_C_TXT_B);
bbapp_text_w
double bbapp_text_w(cairo_t *cr, const char *s, double size, int bold);
量一段文字在给定字号下的前进宽度(cairo_text_extents().x_advance)。
返回值:像素宽度;s 为 NULL/空串时返回 0。
备注
- 结果包含字形的左右空隙,适合做布局和对齐,不适合做"精确裁剪边界";
- 需要
cr(度量依赖设备字体),所以只能在有cr的地方调用(draw里、tap里不行); - 中文和英文混排宽度按字形累加,不要用"字数 × 固定宽度"估算。
示例
static void draw_badge(cairo_t *cr, const char *s, double right, double y) {
double w = bbapp_text_w(cr, s, 13, 0);
double pad = 10;
bbapp_rrect(cr, right - w - pad * 2, y - 14, w + pad * 2, 22, 11);
cairo_set_source_rgba(cr, 0.36, 0.72, 1.0, 0.22);
cairo_fill(cr);
bbapp_text(cr, s, right - w - pad, y, 13, 0, BB_C_TXT_R, BB_C_TXT_G, BB_C_TXT_B);
}
9.6 宏与常量
BBAPP_API_VERSION
#define BBAPP_API_VERSION 1
当前 API 版本。bbui 不检查它,它只是给源码里的条件编译/未来兼容用的锚点。详见 11 版本与兼容。
主题色
| 宏 | 值 |
|---|---|
BB_C_BG_R/G/B |
0.055 / 0.075 / 0.145 |
BB_C_TXT_R/G/B |
0.88 / 0.92 / 0.98 |
BB_C_DIM_R/G/B |
0.58 / 0.65 / 0.78 |
BB_C_ACC_R/G/B |
0.36 / 0.72 / 1.00 |
都是 double 字面量,直接当参数传:
cairo_set_source_rgb(cr, BB_C_ACC_R, BB_C_ACC_G, BB_C_ACC_B);
9.7 输入回调(API v2)
| 回调 | 什么时候调 | 返回 1 表示 |
|---|---|---|
down(x, y) |
按下瞬间(坐标采样到之后) | 消费这次按下 |
move(x, y, dx, dy) |
拖动中,每帧最多一次 | 消费这次移动 |
up(x, y, held_ms, moved) |
抬起,带完整信息 | 消费 |
long_press(x, y) |
按住 ≥ BBAPP_LONGPRESS_MS(500)且没移动 |
消费 |
tap(x, y) |
v1 老接口:抬起且没拖动 | 消费 |
up 的两个额外参数:
held_ms:从按下到抬起过了多少毫秒(自己可以做 1 秒、2 秒的长按分级)moved:整次按压位移是否超过BBAPP_TAP_SLOP(12px)
static int on_up(int x, int y, int held_ms, int moved)
{
if (moved) { bbapp_log("滑动到 %d,%d", x, y); return 1; }
if (held_ms > 1200) { bbapp_toast("长按 1.2 秒"); return 1; }
bbapp_toast("点击 %d,%d(%dms)", x, y, held_ms);
return 1;
}
注意三点:
move是每帧最多一次,不是每个事件一次。触摸设备的采样比屏幕快,全转发会把应用淹了。- 按下点是在第一个
SYN_REPORT才确定的(原因见 07),所以down可能比手指真正落下晚一帧。 - 用了控件层(
bbapp_ui_*)之后,这五个回调都不会被调用。 两套二选一。
9.8 生命周期回调(API v2)
| 回调 | 时机 | 常见用途 |
|---|---|---|
init() |
surface 建好、触摸独占完成之后,第一次 draw 之前 | 读配置、开文件。返回非 0 = 启动失败 |
pause() |
进后台(surface 已销毁,不会再 draw) | 落盘、停定时器、停音频 |
resume() |
从后台回到前台(surface 已重建) | 重读状态、刷新 |
destroy() |
进程退出前,任何路径都会调一次(含 SIGTERM) | 收尾、落盘 |
destroy 里有 1 秒左右的余量(之后才 exec bbui),别在里面做重活。
9.9 系统状态
int bbapp_battery(void); /* 0..100;读不到返回 -1(第一次读不到就一直是 -1) */
int bbapp_charging(void); /* 1 充电中 / 0 放电中 / -1 判断不了 */
int bbapp_wifi(void); /* 1 wlan0 拿到 IP / 0 没有 */
bbapp_battery 会遍历 /sys/class/power_supply/*/capacity,不写死节点名(不同批次的电池驱动节点名不一样)。
char buf[32];
int b = bbapp_battery();
snprintf(buf, sizeof buf, b >= 0 ? "%d%%" : "--", b); /* 别把 -1 当 0 显示 */
读 sysfs 是有开销的(几次 open/read)。放 tick 里也要节流:
static double stat_at;
void tick(double now) {
if (now - stat_at < 2.0) return;
stat_at = now;
batt = bbapp_battery();
bbapp_redraw();
}
9.10 持久化 KV
存在 <data>/kv.conf,一行一条 key<TAB>value,进程重启后还在。
int bbapp_kv_get(const char *key, char *out, int cap); /* 返回完整长度,-1 = 不存在 */
int bbapp_kv_set(const char *key, const char *val); /* 0 ok */
int bbapp_kv_del(const char *key);
int bbapp_kv_get_int(const char *key, int def);
int bbapp_kv_set_int(const char *key, int v);
double bbapp_kv_get_double(const char *key, double def);
int bbapp_kv_set_double(const char *key, double v);
void bbapp_kv_flush(void); /* set 已经即时落盘了,这个只是保险 */
void bbapp_kv_clear(void);
int vol = bbapp_kv_get_int("volume", 60); /* 没有就用 60 */
if (bbapp_ui_slider(r, "音量", &vol_d, 0, 100))
bbapp_kv_set_int("volume", (int)vol_d);
| 限制 | 值 |
|---|---|
| 键数量 | 64 个 |
| 键长度 | 63 字节 |
| 值长度 | 511 字节(超了 set 返回 -1,不会静默截断) |
| 换行 | 可以存,落盘时转义成 \n |
| 原子性 | 写临时文件再 rename,断电不会留半截文件 |
| 卸载 | 应用目录整个删掉,data/ 一起没 |
每次 set 都会重写整个文件。要塞几十条就循环 set(你的数据量到不了"写坏闪存"的程度),但别在 tick 里每帧 set。
9.11 HTTP(异步 GET)
typedef void (*bbapp_http_cb)(int status, const char *body, int len, void *user);
int bbapp_http_get(const char *url, bbapp_http_cb cb, void *user); /* 返任务 id,-1 失败 */
void bbapp_http_cancel(int job);
int bbapp_http_busy(void);
static void on_json(int status, const char *body, int len, void *user)
{
(void)user;
if (status == 200) bbapp_toast("拿到 %d 字节", len);
else bbapp_toast("失败:%d", status);
bbapp_redraw();
}
/* 触发(比如点了个按钮) */
bbapp_http_get("https://example.com/data.json", on_json, NULL);
| 项 | 说明 |
|---|---|
| 实现 | fork 一个 curl(没有就退 wget)子进程,输出接到 pipe 上非阻塞读 |
| 阻塞吗 | 不阻塞,界面照常转;回调在主循环里执行 |
status |
HTTP 状态码;连不上 / 超时 / 没有 curl 和 wget → 0 |
| body 上限 | 2 MB,超了截断(len 是实际拿到的长度) |
| 并发 | 最多 4 个 |
| 超时 | 20 秒 |
| body 生命周期 | 只在回调期间有效,要留着就自己 strdup |
| 回调里能干什么 | 可以立刻再发一个请求(槽位已释放),也可以 bbapp_redraw() |
body 不是 null 结尾的保证?—— 是(SDK 会补 \0),但里面可能有二进制,len 为准。
9.12 完整可用符号清单(供复制)
/* 入口 */
int bbapp_main(const bbapp_app *app);
#define BBAPP_MAIN(app_ptr)
/* 运行时 */
int bbapp_width(void);
int bbapp_height(void);
double bbapp_now(void);
double bbapp_wall_now(void);
const char *bbapp_data_dir(void);
const char *bbapp_assets_dir(void);
void bbapp_log(const char *fmt, ...);
void bbapp_redraw(void);
void bbapp_shell(const char *cmd);
void bbapp_quit(void);
/* 系统状态 */
int bbapp_battery(void);
int bbapp_charging(void);
int bbapp_wifi(void);
/* 持久化 */
int bbapp_kv_get(const char *key, char *out, int cap);
int bbapp_kv_set(const char *key, const char *val);
int bbapp_kv_del(const char *key);
int bbapp_kv_get_int(const char *key, int def);
int bbapp_kv_set_int(const char *key, int v);
double bbapp_kv_get_double(const char *key, double def);
int bbapp_kv_set_double(const char *key, double v);
void bbapp_kv_flush(void);
void bbapp_kv_clear(void);
/* 网络 */
typedef void (*bbapp_http_cb)(int status, const char *body, int len, void *user);
int bbapp_http_get(const char *url, bbapp_http_cb cb, void *user);
void bbapp_http_cancel(int job);
int bbapp_http_busy(void);
/* 绘制 */
void bbapp_rrect(cairo_t *cr, double x, double y, double w, double h, double r);
void bbapp_clip_rrect(cairo_t *cr, double x, double y, double w, double h, double r);
void bbapp_panel(cairo_t *cr, double x, double y, double w, double h, double alpha);
void bbapp_text (cairo_t *cr, const char *s, double x, double baseline,
double size, int bold, double r, double g, double b);
void bbapp_text_c(cairo_t *cr, const char *s, double cx, double baseline,
double size, int bold, double r, double g, double b);
double bbapp_text_w(cairo_t *cr, const char *s, double size, int bold);
void bbapp_toast(const char *fmt, ...);
/* 控件层(详见 13-ui.md) */
typedef struct { double x, y, w, h; } bb_rect_t;
static inline bb_rect_t bb_rect(double x, double y, double w, double h);
void bbapp_ui_begin(cairo_t *cr, int w, int h);
void bbapp_ui_end(void);
int bbapp_ui_button(bb_rect_t r, const char *label, int primary);
int bbapp_ui_switch(bb_rect_t r, const char *label, int *value);
int bbapp_ui_slider(bb_rect_t r, const char *label, double *value, double lo, double hi);
void bbapp_ui_progress(bb_rect_t r, double v);
bb_rect_t bbapp_ui_row(bb_rect_t area, double *cursor, double h, double inset);
/* 文本输入(详见 14-ime.md) */
#define BBAPP_IME_TEXT 0
#define BBAPP_IME_NUMBER 1
#define BBAPP_IME_PASSWORD 2
typedef struct { char text[192]; int len, max_len, focused, _blink_at, _dirty; } bbapp_ui_input_t;
#define BBAPP_UI_INPUT_INIT
int bbapp_ui_input(bb_rect_t r, bbapp_ui_input_t *in, const char *placeholder, int mode);
void bbapp_ui_input_focus(bbapp_ui_input_t *in);
void bbapp_ui_ime(void);
int bbapp_ui_ime_height(void);
void bbapp_ui_input_put(bbapp_ui_input_t *in, const char *s);
void bbapp_ui_input_back(bbapp_ui_input_t *in);
void bbapp_ui_input_clear(bbapp_ui_input_t *in);
int bbapp_ui_tap_in(bb_rect_t r);
typedef struct {
const char *name;
int height;
void (*draw)(cairo_t *cr, bb_rect_t area, bbapp_ui_input_t *in);
} bbapp_ime_impl_t;
void bbapp_ime_use(const bbapp_ime_impl_t *impl);
const char *bbapp_ime_current(void);
typedef struct { ... } bbapp_ui_list_t;
#define BBAPP_UI_LIST_INIT
void bbapp_ui_list_begin(bbapp_ui_list_t *L, bb_rect_t area, int n, double row_h);
int bbapp_ui_list_row(bbapp_ui_list_t *L, int i);
double bbapp_ui_list_y(const bbapp_ui_list_t *L, int i);
void bbapp_ui_list_end(bbapp_ui_list_t *L);
void bbapp_ui_list_scroll_to(bbapp_ui_list_t *L, int row, int animate);
double bbapp_ui_list_max_off(bbapp_ui_list_t *L);
头文件里只有这些。看到别处提到
bbapp_*而这里没有的,那是旧文档或旧版本,以sdk/bbapp.h为准。
下一步 → 10 调试与排错。