MeowOS
f44e3bc6d0
git-subtree-dir: sdk git-subtree-mainline:17a972d46fgit-subtree-split:2e7561d74f
73 lines
4.5 KiB
C
73 lines
4.5 KiB
C
/*
|
||
* meow_ui_zorder.h — SDK 绘制物注册表 / z 序 / 区域重画（§6.2，合并 SDK_Z_ORDER_DESIGN）。
|
||
*
|
||
* 原 meow_ui.h 拆分的一部分（zorder/draw 注册表）。非保留模型（§5.8.7）下，把「清底 + 按 z
|
||
* 重画重叠区完整 z 栈」下沉到 SDK，让所有 App 自动获得正确的局部重画。全部 opt-in：
|
||
* 不调用本节的既有 App（widget/activity/flush 均不动）行为完全不变。
|
||
*/
|
||
#ifndef MEOW_UI_ZORDER_H
|
||
#define MEOW_UI_ZORDER_H
|
||
|
||
#include "meow_ui_types.h"
|
||
|
||
#ifdef __cplusplus
|
||
extern "C" {
|
||
#endif
|
||
|
||
/* ============================================================ */
|
||
/* §6.2 绘制物注册表 / z 序 / 区域重画（合并 SDK_Z_ORDER_DESIGN，源:2026-08-31）
|
||
* ------------------------------------------------------------
|
||
* 非保留模型（§5.8.7）下，把「清底 + 按 z 重画重叠区完整 z 栈」下沉到 SDK，让所有 App
|
||
* 自动获得正确的局部重画（根治 P1：下层动态控件局部重绘会把重叠区上层 chrome 抹掉）。
|
||
* - 控件（meow_widget）创建即自动注册进绘制物注册表；rect 实时读 w->x/y/w/h；
|
||
* - App 直绘的非控件内容（meow_ui_text/fill_rect 等）须显式 meow_draw_custom_register
|
||
* 注册（声明 bbox + 绘制回调），否则区域重画会漏画（非保留模型固有代价）；
|
||
* - z 自动推导（子>父、同层注册先序）；显式 meow_widget_set_z(999/MEOW_Z_TOP) 置顶（粘滞）。
|
||
* 用法：meow_ui_invalidate(x,y,w,h) 局部重画（清底+按 z 升序重画所有相交绘制物+上屏），
|
||
* 不整帧；meow_ui_paint_full() 整帧按 z 序重画。默认底=meow_theme bg（set_page_bg 覆盖）。
|
||
* 兼容：新 API 全部 opt-in；不调用本节的既有 App（widget/activity/flush 均不动）行为完全不变。 */
|
||
/* ============================================================ */
|
||
|
||
/* 绘制物种类：控件（自动注册）/ App 直绘内容（显式注册）。 */
|
||
typedef enum { MEOW_ITEM_WIDGET = 0, MEOW_ITEM_CUSTOM = 1 } meow_draw_kind;
|
||
typedef void (*meow_draw_fn)(void *ctx); /* CUSTOM 绘制回调（ctx 由 App 持有） */
|
||
|
||
/* ---- 层级常量（保证"子>父" + 值域远小于置顶值）---- */
|
||
#define MEOW_Z_STRIDE 16 /* 每层容器嵌套的 z 步进（子层至少 +16） */
|
||
#define MEOW_Z_DEPTH_MAX 7 /* 自动推导最大嵌套深度（0..6，>7 折叠） */
|
||
#define MEOW_Z_PER_LEVEL_MAX 15 /* 每层最多 16 槽（seq 0..15，超出折叠按注册序） */
|
||
#define MEOW_Z_AUTO_MAX (MEOW_Z_STRIDE * MEOW_Z_DEPTH_MAX + MEOW_Z_PER_LEVEL_MAX) /* 127 */
|
||
#define MEOW_Z_TOP 1000 /* 惯例"置顶"值；≥(MEOW_Z_AUTO_MAX+1)=128 即超一切自动值 */
|
||
|
||
/* 控件显式置层：z 为任意非负整数（0..INT_MAX，无上限），越大越上；z>所有其它控件即恒在最上。
|
||
* 惯例设 999（或 MEOW_Z_TOP）即"置顶"。显式 z 存于绘制注册表（按 w 反查 entry，不改
|
||
* struct meow_widget——零 ABI 破坏）且**粘滞**：不被后续自动推导覆盖；clear_z 才回退。 */
|
||
void meow_widget_set_z(meow_widget *w, int z);
|
||
int meow_widget_z(const meow_widget *w); /* 当前生效 z（显式=其值，否则=自动推导） */
|
||
void meow_widget_clear_z(meow_widget *w); /* 清除显式 z，回退自动推导 */
|
||
|
||
/* ---- 非控件直绘内容注册为绘制物（CUSTOM）----
|
||
* App 声明 bbox + 绘制回调 + 显式 z（任意非负；999=置顶）；区域重画/整帧重画会画到它。
|
||
* 返回 id（供 meow_draw_unregister / meow_draw_set_z）；注册表满返回 0。
|
||
* 生命周期契约：App 持有 ctx；widget 类内容不必注册（自动）；离开页面前 unregister。 */
|
||
int meow_draw_custom_register(int z, int x, int y, int w, int h,
|
||
meow_draw_fn cb, void *ctx);
|
||
void meow_draw_unregister(int id); /* 注销（id 失效，勿再用） */
|
||
int meow_draw_set_z(int id, int z); /* 改 custom 显式 z；无效 id 返回 -1 */
|
||
|
||
/* 页面背景色（区域重画/整帧清底用）；默认 meow_theme bg。 */
|
||
void meow_ui_set_page_bg(uint32_t color);
|
||
uint32_t meow_ui_page_bg(void);
|
||
|
||
/* 声明某区域内容已变化 → 清底(page_bg) + 按 z 升序重画所有相交绘制物 + 上屏。
|
||
* 局部（只画相交绘制物，完整 bbox——见 SDK_Z_ORDER_DESIGN §5），不整帧、不冲状态栏。 */
|
||
void meow_ui_invalidate(int x, int y, int w, int h);
|
||
|
||
/* 整帧按 z 序重画全部（set_page_bg 清底 + 全注册表按 z 升序 + 上屏）。 */
|
||
void meow_ui_paint_full(void);
|
||
|
||
#ifdef __cplusplus
|
||
}
|
||
#endif
|
||
#endif /* MEOW_UI_ZORDER_H */
|