AskaEth/MeowOS-SDK
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

sync(SDK): 增量同步主仓 M6.37–M6.39 至公开 SDK 仓

Browse Source 
sdk/：
- 同步 meow_ui_widget/input/gfx/lazygrid/audio/media/img 等源码与头
  （SDK 默认列表/容器控件默认 MD3 — meow_list_set_container 可回退；
   全局 App 内底部上滑回桌面 — meow_ui_input_is_home_swipe 系统保留手势；
   LazyGrid/LazyColumn/LazyRow MD3 化；叠加让位自抑改 app_id 判定；
   DSD 音频格式等）
- 新增独立模块源码 meow_img_color / meow_lyric / meow_lyric_view 及对应宿主 test_*.c
- 保留公开仓自包含适配：vendored meow_font.c/meow_font.h/meow_notif.h 不动；
  build_sdk.sh 自包含版本不动；meow_ui_gfx.c 仅改 meow_font.h include 路径；
  meow_ui_internal.h 去除 FreeType 内部声明
- meow_ipc.h 同步到主仓 launcher 版本（含 AUDIO_FMT_DOP/媒体歌词/蓝牙输出协议）
- 不含 FreeType 矢量字 meow_ft_*（需 freetype vendor，公开仓以位图 meow_font
  自包含）；不含 mipsel 二进制 / .o / .a / 固件 / 密钥 / devdocs

examples/hello/：
- 新增 ui/demo/sdk2/sdk2.c；build_hello.sh 纳入该文件（保持自包含）

docs / README / .gitignore：
- docs/MEOW_APP_SDK.md 补 §12.5（默认 MD3 容器 + 底部上滑回桌面 + 两个新 API）
- README 能力清单补「默认 MD3 容器」与「底部上滑回桌面」
- .gitignore 补新增宿主测试二进制

验证：sdk/meow_ui.a 与 examples/hello/hello 交叉编译均 0 warning；工作区无生成物。
This commit is contained in:
AskaEth committed 2026-09-04 18:05:36 +08:00
1 parent a1687486bc
commit c0396e40ce
45 files changed
+4665 -175
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

sdk/include/meow_ipc.h
+89 -8
View File
@@ -81,6 +81,7 @@ enum {
MSG_PICKER_RESULT = 0x0071, /* ↑ picker 返回值（候选结果回 A；→launcher→amsd） */
MSG_META = 0x0072, /* ↑ 媒体会话上报元数据/进度/状态（阶段 D 附录 B） */
MSG_PLAYCTL = 0x0073, /* ↓ 播放控制下发/↑ 控制器转发到最近活跃媒体会话 */
MSG_META_LYRIC = 0x0074, /* ↑ 媒体会话上报当前曲歌词 lrc/tlrc（阶段 D · 批3，分片） */
/* ---- amsd 控制（AMSD_DESIGN §4.2）：amsd→launcher，申请拉起/终止某 App ----
* 语义：amsd 为「启动/终止」决策者 → launcher（执行器）执行。payload 见下。 */
MSG_AMS_START = 0x00A0, /* → 请求 launcher 拉起某 App（pkg + 可选 activity） */
@@ -99,6 +100,10 @@ enum {
MSG_AUDIO_STATE = 0x00C8, /* ↓ 状态快照文本（NUL 结尾；当前流/参数/帧数/underrun/路由/音量） */
MSG_AUDIO_ROUTE = 0x00C9, /* ↑ 手动路由（u32 port：0=auto 2=3.5 3=4.4；调试/面板用） */
MSG_AUDIO_VOLUME = 0x00CA, /* ↑ 音量（i32 pct：-1=查询 0-100=设置；v1 透传写 DAC numid=1/2） */
/* P2 蓝牙（BLUETOOTH_FULL_OVERHAUL_PLAN §五）：输出目标切换。audiod 读 settings.conf
* `audio.output_bt`(0/1) 或收本消息改写目标（0=OUT_DAC 1=OUT_BT），重配 PCM。
* 与物理路由 numid=9 解耦：蓝牙非物理端口，不写 numid=9、不触发 FPGA 烧录。 */
MSG_AUDIO_OUTPUT = 0x00CB, /* ↑ 输出目标（u32 target：0=DAC 1=BT；ui/CLI 下发） */
/* ---- meow_powermgr 功耗管理服务（devdocs/plan/POWER_MANAGER_DESIGN.md §6.1）：0x00D0-0x00D7 ----
* 语义：功耗维度的查看/分析/管理（svc_power 管动作、svc_perf 管性能，powermgr 管功耗）。
* 独立 socket /usr/data/meow_pm.sock（--sock/MEOW_PM_SOCK 覆盖）。鉴权分级同 svc_power：
@@ -274,6 +279,29 @@ typedef struct m_playctl {
int64_t seek_ms; /* cmd=5: 目标位置 ms；否则 0 */
} m_playctl_t; /* 4 (+4 pad) + 8 = 16 B（mipsel int64 8 对齐） */
/* ---- 媒体会话歌词上报（阶段 D · 批3：live lyric 数据源框架）----
* App 播放时把当前曲歌词（lrc 原文 + tlrc 翻译）上报到 meow_media 会话，供桌面歌词页/播放页
* 随播放位置实时滚动。约束：launcher 环缓冲 `payload[MEOW_IPC_CARGO(1024)]` 为单帧入队上限，
* 故歌词按分片传输（每片 ≤ MEOW_LYRIC_CHUNK 字节）。
* - seq = 歌曲代际（换歌/换词自增；launcher 见新 seq 清旧词缓存，同曲分片共用）
* - kind = 0 原文 lrc / 1 翻译 tlrc
* - total= 该 kind 总字节数（不含 NUL；0=清空该 kind）
* - off/len = 本片起始偏移 / 有效字节（首片 off=0；分片按序发送）
* 边界：lrc 上限 MEOW_MEDIA_LRC_MAX / tlrc 上限 MEOW_MEDIA_TLRC_MAX（会话内每 App 一份缓冲，
* 超限截断）。payload 定长且 == MEOW_IPC_CARGO（即 sizeof(m_lyric_t)=1024）。 */
#define MEOW_MEDIA_LRC_MAX 3584u /* 会话内歌词原文缓冲上限 */
#define MEOW_MEDIA_TLRC_MAX 1568u /* 会话内歌词翻译缓冲上限 */
#define MEOW_LYRIC_CHUNK (MEOW_IPC_CARGO - 44u) /* 单分片数据上限（44=头：32+4+2+2+2+2） */
typedef struct m_lyric {
char app_id[MEOW_APP_ID_MAX]; /* 32: 上报源头（与 HELLO/META 的 app_id 一致） */
uint32_t seq; /* 歌曲代际（新歌/新词自增；分片同 seq） */
uint16_t kind; /* 0=原文 lrc；1=翻译 tlrc */
uint16_t total; /* 该 kind 总字节数（不含 NUL；0=清空该 kind） */
uint16_t off; /* 本片起始偏移（≤ total；首片=0） */
uint16_t len; /* 本片有效字节（≤ MEOW_LYRIC_CHUNK） */
char data[MEOW_LYRIC_CHUNK]; /* 本片内容（len 后 NUL 结尾，接收侧再截断） */
} m_lyric_t; /* 44 + 980 = 1024 B = MEOW_IPC_CARGO */
/* MSG_NOTIFY ↑：推送/更新通知（freedesktop 对齐 + MeowOS 扩展；定长 LE）。
* - summary/body/app_icon/expire_timeout 直通 freedesktop 字段；app_icon 即 SDK `icon`
* （icon name 或 path；映射为空串时 launcher 用该 app 默认图标回退）；
@@ -457,24 +485,32 @@ typedef struct m_picker_result {
/* ================= audiod 独占音频服务（AUDIOD_DESIGN.md） = */
/* PCM 格式枚举（客户端原生 fmt 与 grant_fmt 共用）：1=S16_LE 2=S24_LE 3=S32_LE 4=FLOAT_LE。
* v1 实装 S16/S32（S16 直通 + S32 升位）；S24 按 32-in-32 处理；FLOAT v1 拒绝。 */
/* PCM 格式枚举（客户端原生 fmt 与 grant_fmt 共用）：1=S16_LE 2=S24_LE 3=S32_LE 4=FLOAT_LE
* 5=AUDIO_FMT_DOP（DoP DSD 透明容器格式）。v1 实装 S16/S32（S16 直通 + S32 升位）；S24 按 32-in-32
* 处理；FLOAT v1 拒绝。AUDIO_FMT_DOP 为 **独立格式值**（A3+DSD 定案：避免 S24 名义(3B)/实际(4B)歧义），
* 仅在 MSG_AUDIO_OPEN.flags 带 AUDIO_FLAG_DSD 时合法；audiod 只做 DoP 容器透传（不引 dsd2pcm）。 */
enum {
AUDIO_FMT_S16 = 1,
AUDIO_FMT_S24 = 2,
AUDIO_FMT_S32 = 3,
AUDIO_FMT_FLOAT = 4
AUDIO_FMT_FLOAT = 4,
AUDIO_FMT_DOP = 5 /* DoP DSD（32-bit 容器：bits[31:16]=16bit DSD 数据，bits[15:8]=标记 0xFA/0x05，bits[7:0]=0），
容器率 = DSD 位率/16（DSD64→176400 / DSD128→352800 / DSD256→705600） */
};
/* MSG_AUDIO_OPEN.flags 位（预留曾恒 0；A3+DSD 起使用） */
#define AUDIO_FLAG_DSD 0x00000001u /* fmt==AUDIO_FMT_DOP：本流为 DoP DSD（App 侧已解码），audiod 只透传 */
/* MSG_AUDIO_OPEN ↑：请求开流（App 原生声源参数）。grant_*（ACK）回 audiod 实际授权给客户端的
* 产出格式（率/声道/位深）——客户端必须按 grant 格式产出 PCM（SDK meow_ui_audio 负责归一：
* mono→stereo 复制 / S16↔S32 定值升降位）。ch>2 或 FLOAT → ERR_INVAL。 */
* mono→stereo 复制 / S16↔S32 定值升降位）。ch>2 或 FLOAT → ERR_INVAL。fmt==AUDIO_FMT_DOP
* 须带 AUDIO_FLAG_DSD（否则 ERR_INVAL）；DSD 经 DoP 透传，audiod 不引 dsd2pcm。 */
typedef struct m_audio_open {
char app_id[MEOW_APP_ID_MAX]; /* 32 */
uint32_t rate; /* 原生采样率（应用源，如 44100/48000） */
uint32_t rate; /* 原生采样率（应用源，如 44100/48000；DSD 容器率） */
uint16_t ch; /* 原生声道数（1=mono 2=stereo） */
uint16_t fmt; /* 原生格式（AUDIO_FMT_*） */
uint32_t flags; /* 预留（0） */
uint16_t fmt; /* 原生格式（AUDIO_FMT_*；DSD 用 AUDIO_FMT_DOP） */
uint32_t flags; /* AUDIO_FLAG_DSD 等 */
} m_audio_open_t; /* 32+4+2+2+4 = 44 B */
/* MSG_AUDIO_OPEN_ACK ↓：授权结果。err=MEOW_OK 才有效（stream_id>0 且 grant_* 为实际授权值）；
@@ -505,11 +541,24 @@ typedef struct m_audio_route {
} m_audio_route_t; /* 4 B */
/* MSG_AUDIO_VOLUME ↑：音量查询/设置。pct<0（-1）=查询当前音量；0-100=设置（写 DAC numid=1/2
* + 持久化 settings.conf `audio.volume`，与 watchdog/launcher 同源同键）。 */
* + **DSD_VOLUME（音量收编 v2 泛化双组写，保证 DSD↔PCM 切换连续/防爆音）** + 持久化 settings.conf
* `audio.volume`，与 watchdog/launcher 同源同键）。BT 输出目标时**不下发 DAC 音量反转**
* （音量由 AVRCP/耳机侧控，见 BLUETOOTH_FULL_OVERHAUL_PLAN §五）。 */
typedef struct m_audio_volume {
int32_t pct; /* -1=查询；0-100=设置 */
} m_audio_volume_t; /* 4 B */
/* 输出目标枚举（msg AUDIO_OUTPUT / settings.conf `audio.output_bt` 共用；亦用于 CLI output） */
enum {
AUDIO_OUT_DAC = 0, /* 本地 DAC（hw:0,0，独占/period=1024×4/FPGA numid=9/音量反转） */
AUDIO_OUT_BT = 1 /* 蓝牙 A2DP source（pcm.bluealsa 播放向，透传+格式归一，AVRCP 控音量） */
};
/* MSG_AUDIO_OUTPUT ↑：切换输出目标（ui/CLI 下发）。0=DAC 1=BT。audiod 侧重配 PCM。 */
typedef struct m_audio_output {
uint32_t target; /* AUDIO_OUT_DAC / AUDIO_OUT_BT */
} m_audio_output_t; /* 4 B */
/* ================= meow_netmgrd 网络管理服务（devdocs/plan/NETMGR_DESIGN.md §3/§10）=====
* 语义：接口统一层（WiFi/BT/USB-eth/rfkill/IP/路由/DNS 只读）查询与控制的系统权威。
* 独立 socket /usr/data/meow_net.sock（--sock/MEOW_NET_SOCK 覆盖）。进程形态对齐 powermgr：
@@ -607,6 +656,38 @@ typedef struct m_net_dns_result {
char text[MEOW_IPC_MAX - 8];
} m_net_dns_result_t;
/* ---- 期 3：管控层（NETMGR_DESIGN §6；默认 allow，按实体手动 block + 域名白/黑）----
* 0x00EA MSG_NET_POLICY（同时承载 GET/SET，op 区分）。GET=读级任意；SET=写级仅系统身份
* （SO_PEERCRED → /usr/bin/meow_* / os.meow.* / MeowPanel）。防自锁实体（dropbear/wpa_supplicant/
* udhcpc/meow_netmgrd/meow_svcd/meow_sysui/init）拒绝置 block（服务端硬校验）。
* 策略持久化：`/data/meow/netmgrd/net_policy.conf`（/data=/usr/data 符号链接），读改写单键原子写。 */
enum { /* 与主 enum 分列，追加式不改既有行 */
MSG_NET_POLICY = 0x00EA, /* ↑ op=0 查询 / op=1 写（set net / set domain / del） */
MSG_NET_POLICY_RESULT = 0x00EB /* ↓ 策略文本/结果 */
/* 0x00EE 事件推送（预留，期2 订阅制）/ 0xEF 余量（均为预留） */
};
/* MSG_NET_POLICY 操作码 */
enum {
NET_POLICY_SHOW = 0, /* show [entity]：entity 空=全部 */
NET_POLICY_SET_NET = 1, /* set <entity> allow|block */
NET_POLICY_SET_DOMAIN = 2, /* domain <entity> +host|-host */
NET_POLICY_DEL = 3 /* del <entity> */
};
typedef struct m_net_policy {
uint32_t op; /* NET_POLICY_* */
char entity[48]; /* app:<pkg> | svc:<svc> | proc:<comm> | global；空=适用 SHOW 的全量 */
char arg[64]; /* SET_NET:allow|block；SET_DOMAIN:+host|-host；其余空 */
} m_net_policy_t; /* 120 B */
typedef struct m_net_policy_result {
uint32_t code; /* MEOW_OK / MEOW_ERR_PERM / MEOW_ERR_INVAL / (防自锁)MEOW_ERR_PERM */
uint16_t text_len;
uint16_t pad;
char text[MEOW_IPC_MAX - 8];
} m_net_policy_result_t;
/* ---- 期 4：SDK 网络自愿通道（NETMGR_DESIGN §6.3/§4；0xEE/0xEF）----
* 一、meow_net_policy_check(host)：框架 App 联网前自查 host 是否被 netmgrd 策略放行——
* 服务端以调用方 app_id（msg.app_id）→ 实体 app:<pkg>，评估 policy_net_blocked(entity)
sdk/include/meow_ui_audio.h
+9
View File
@@ -38,6 +38,7 @@ typedef struct meow_audio_state {
int paused; /* 当前流是否暂停 */
int route_port; /* 当前路由口（-1 未知） */
int vol; /* 当前音量 0-100 */
int dsd; /* 当前流是否为 DoP DSD（fmt==AUDIO_FMT_DOP 且 audiod 已授权） */
} meow_audio_state;
/* 被抢占回调：by_app=抢占者 app_id（非空）。ctx 由 on_preempt 注册时传入。 */
@@ -48,6 +49,10 @@ typedef void (*meow_audio_preempt_fn)(const char *by_app, void *ctx);
* MEOW_ERR_NODEV=无可用 PCM 设备；MEOW_ERR_* 常量本身即负值）。open 后客户端须按内部记录的
* grant 格式产出 PCM。 */
int meow_audio_open(int rate, int ch, int fmt);
/* 开流（带 flags）。flags=AUDIO_FLAG_DSD 且 fmt=AUDIO_FMT_DOP 时为 DoP DSD 流（A3+DSD 定案）：
* App 侧须把 DSD 解码封装为 DoP（每样本 32-bit 容器：16bit DSD 数据 + 标记 + 0），audiod 只透传
* （不引 dsd2pcm、不做 DOP_EN 之外的任何处理）。DSD 打不开/不支持 → open 返回负错误码（报错关流）。 */
int meow_audio_open_ex(int rate, int ch, int fmt, uint32_t flags);
/* 写 PCM。pcm=native fmt/ch 样本（open 传的参数），frames=帧数；内部归一成 grant 并分批发送。
* 返回写入帧数；<0=流已死（被抢占/audiod 断开），App 应重新 open。阻塞（socket 背压）。 */
int meow_audio_write(const void *pcm, int frames);
@@ -57,6 +62,10 @@ int meow_audio_pause(int sid, int paused);
int meow_audio_close(int sid);
/* 查询 audiod 快照（填充 out）。返回 0 成功；<0 失败。 */
int meow_audio_query(meow_audio_state *out);
/* 设置音量 0-100（audiod 唯一权威：写 DAC numid=1/2 + DSD_VOLUME 双组保切换连续 + 持久化
* settings.conf audio.volume，与 launcher/watchdog 同源同键）。BT 输出目标时音量由 AVRCP 侧控，
* audiod 不下发 DAC 反转。返回 0 成功；<0 失败（audiod 不在）。 */
int meow_audio_set_volume(int pct);
/* 注册被抢占回调（可选；内部读线程分发）。重复调用幂等。 */
void meow_audio_on_preempt(meow_audio_preempt_fn cb, void *ctx);
sdk/include/meow_ui_image.h
+5 -2
View File
@@ -22,8 +22,11 @@ meow_img *meow_img_load_file(const char *path); /* 内部读文件 + stb 解
meow_img *meow_img_load_mem(const void *buf, int len);
void meow_img_free(meow_img *img);
int meow_img_w(meow_img *img);
int meow_img_h(meow_img *img);
int meow_img_w(const meow_img *img);
int meow_img_h(const meow_img *img);
/* 访问器：取 RGBA 像素指针（4 通道 straight alpha；供取色/直读像素）。meow_img 对外 opaque，
* 本函数为其唯一像素读入口；NULL 返回 NULL。 */
const unsigned char *meow_img_pixels(const meow_img *img);
void meow_ui_img(int x, int y, meow_img *img); /* 原始尺寸 */
/* 内存瘦身：最近邻等比缩放到最长边 ≤maxdim，返回新图；原图已 ≤maxdim 返回 NULL。
sdk/include/meow_ui_input.h
+7
View File
@@ -36,6 +36,13 @@ void meow_ui_request_exit(void); /* 请求退出（相当于返回/
* x<=0 时清掉此前画的条（填回背景色）。不发 flush，由调用方 meow_ui_flush_region 上屏。 */
void meow_ui_swipe_hint(int x);
/* 批②（2026-09-04）：底部热区上滑 → 回桌面（home）判定，镜像 launcher np_gesture.h
* np_home_gesture 同口径。down_x/down_y=抬手原点，dx/dy=抬手位移（释放-原点），
* fb_h=屏高（SDK 传 meow_ui_height()）。命中=起点在底部热区（最后 HOME_EDGE_H≈28px）且
* **不在左缘**（down_x>=EDGE_W，与左缘返回互斥）+ 上移 ≥HOME_SWIPE(65px) + 竖向主导（adx<-dy）。
* 供宿主单测直调；触摸状态机（meow_ui_input.c touch_release）与 App 内判据共用，避免两端漂移。 */
int meow_ui_input_is_home_swipe(int down_x, int down_y, int dx, int dy, int fb_h);
/* ============================================================ */
/* §6.3 通用长按（2026-08-31） */
/* ============================================================ */
sdk/include/meow_ui_widgets.h
+21
View File
@@ -49,6 +49,7 @@ int meow_btn_pressed(meow_widget *w); /* 应用在 on_tap 命中后
/* ---- §5.8.2 Modifier 式通用 Options（轻量结构体，非链式 DSL）----
* 经 meow_widget_set_opts 一次性挂载，作用于任意控件（标准/自定义）。全部控件共用。
* 哨兵语义：bg/fg==0=用控件/主题默认；stroke==0=无描边；stroke_w=描边宽；
* 控件语义：W_PROGRESS 用 bg=轨道（0=surfaceVariant）、fg=填充（0=primary）；见 meow_ui_widget.c 批5b；
* radius==-1=控件默认（如按钮 10），>=0=指定圆角（0=直角）；pad/margin=0=无；
* disabled/selected=1=置位（立即反映到状态机位）。 */
typedef struct meow_widget_opts {
@@ -145,6 +146,17 @@ enum {
meow_widget *meow_btn_create_variant(int x, int y, int w, int h, const char *label, int variant);
int meow_btn_set_variant(meow_widget *w, int variant); /* 越界 clamp；0=成功 */
/* ---- MD3 shape 层级（§5.8.6，Material You 圆角体系，单位 px）----
* 组件按角色落到五档 + 胶囊：按钮=full（全高一半）、对话框=extra-large(28)、卡=large(16)、
* 输入框=small(8)、勾选=extrasmall(4)。theme.radius/radius_card 为风格族默认；App 可经
* opts.radius 逐控件覆盖。全高一半用 MEOW_SHAPE_FULL(h) 宏（控件的胶囊圆角）。 */
#define MEOW_SHAPE_EXTRASMALL 4 /* 勾选 Checkbox/Radio */
#define MEOW_SHAPE_SMALL 8 /* 输入框 TextField */
#define MEOW_SHAPE_MEDIUM 12 /* 主题默认 radius（列表卡/通用控件） */
#define MEOW_SHAPE_LARGE 16 /* 卡片/容器（theme.radius_card 默认） */
#define MEOW_SHAPE_EXTRA_LARGE 28 /* 对话框 Dialog（MD3 标准 extra-large） */
#define MEOW_SHAPE_FULL(h) ((h) / 2) /* 全形=胶囊（按钮/导航等） */
/* ---- TextField（单行文本输入，接 IME §5.1）---- */
/* placeholder=提示文案；buf=App 持有的文本缓冲（组件不回拷，只绘制/编辑其上）；maxlen=含 NUL 预算 */
meow_widget *meow_textfield_create(int x, int y, int w, int h, const char *placeholder,
@@ -254,6 +266,10 @@ int meow_list_selected(meow_widget *w);
typedef void (*meow_list_tap_fn)(int idx, void *ctx);
void meow_list_set_on_tap(meow_widget *w, meow_list_tap_fn cb, void *ctx); /* 命中行→回调 */
int meow_list_tap_at(meow_widget *w, int x, int y); /* 命中行：置选中+回调，返回 idx/-1 */
/* MD3 容器模式（W_LIST 共用，§5.5/§5.8.6）：0=扁平满宽项+分隔线（回退）；1=每项外套 surfaceContainer
* 圆角卡+项间空隙（去分隔线），选中=primaryContainer/按压=primary α26（卡内 tonal）。
* 覆盖 meow_list_create / meow_lazycolumn_create / meow_lazyrow_create。返回 0=成功；无效=负值。 */
int meow_list_set_container(meow_widget *w, int on);
/* ============================================================ */
/* §5.5 设计模板 A② 结构化列表（W_LISTVIEW）：行=图标+标题+副标题+右侧操作 + 选中
@@ -383,6 +399,11 @@ int meow_listview_set_item_tier(meow_widget *lv, int lines);
/* 完全自绘：设 draw_item 回调（覆盖默认 renderer）；NULL=用默认 renderer。返回 0=成功。 */
int meow_listview_set_item_draw(meow_widget *lv, meow_listview_draw_fn draw,
void *ctx);
/* MD3 容器模式（默认 renderer 可选，P0 对齐）：0=扁平满宽行+分隔线（默认，兼容）；
* 1=每行外套 surfaceContainer 圆角卡(12dp)+行间空隙，选中=primaryContainer/按压=primary α
* （tonal，非满幅实心），去冗余分隔线；段头=surface 上的 primary 段标签（无卡无分隔线）。
* 注意：仅对默认 renderer（未 set_item_draw）生效；完全自绘行由 App self-draw 自理。 */
int meow_listview_set_container(meow_widget *lv, int on);
/* 空态占位：count==0 时视口内居中画 empty_text（NULL 不画）。返回 0=成功。 */
int meow_listview_set_empty_text(meow_widget *lv, const char *text);