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 回桌面,不返回。

备注

示例

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() 里已经可用。

备注

示例

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,带纳秒精度。

返回值:单调递增的秒数。起点是系统启动,绝对值没有意义,只用差值。

备注

示例

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。环境变量缺失时返回 "."。

备注

示例

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 字节,超出截断

返回值:无。

备注

示例

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 字节截断

返回值:无。

备注

示例

static int app_tap(int x, int y) {
    bbapp_toast("点了 %d,%d", x, y);
    return 1;
}

bbapp_redraw

void bbapp_redraw(void);

请求下一轮重绘。

返回值:无。

备注

示例

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)

返回值:无(拿不到退出码,也拿不到输出)。

备注

示例

/* 在后台把当前时间写进 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))。

备注

示例

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

返回值:无。

备注

示例

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 会很白、盖住背景

返回值:无。

备注

示例

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

返回值:无。

备注

示例

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。

备注

示例

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 的两个额外参数:

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;
}

注意三点:

  1. move 是每帧最多一次,不是每个事件一次。触摸设备的采样比屏幕快,全转发会把应用淹了。
  2. 按下点是在第一个 SYN_REPORT 才确定的(原因见 07),所以 down 可能比手指真正落下晚一帧。
  3. 用了控件层(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 调试与排错。

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