MeowOS
fa268c0fce
meow_ui.a d814d0ed→7e20f10e; hello 0a1c96a5→2ce09466 宿主验证: test_p1p2p3_repro P1c/P2/P3 ALL PASS; test_meow_ui_widgets ALL PASS 无回归; mipsel -Wall -Wextra 0 warning
99 lines
5.2 KiB
C
99 lines
5.2 KiB
C
/*
|
||
* meow_ui_view.h — SDK 视图/页面框架（meow_view，嵌套容器 + 生命周期 + 事件路由）。
|
||
*
|
||
* 源：devdocs/plan/SDK_VIEW_FRAMEWORK_DESIGN.md §A。本文件为机制 ABI（结构 + 生命周期钩子 +
|
||
* 页面导航包装），与 z 序绘制物注册表（meow_ui_draw.c，§C/§6.2）协同：
|
||
* - meow_view 是**薄壳**：容器 + 生命周期 + 事件路由；叶子仍是 meow_widget（不改）。
|
||
* - on_draw 是回调，view 不缓存像素（非保留）；重绘由 meow_ui_invalidate 触发。
|
||
* - opt-in：不调用 meow_view_* 的 App 完全照旧（widget/activity/flush 不动）。
|
||
* - z 深度源 = view 树（parent/children 深度）；叶子 widget 深度 = 所属 view 深度 + 1。
|
||
*
|
||
* 页面模型（定案 b，预留 a）：顶层页切换仍由 activity 栈（meow_view_page_push/pop/replace 包装），
|
||
* 不做页内子导航栈；meow_view_sub_push/pop 为将来扩展位（仅在一个 ACTIVITY view 内维护子栈）。
|
||
*/
|
||
#ifndef MEOW_UI_VIEW_H
|
||
#define MEOW_UI_VIEW_H
|
||
|
||
#include "meow_ui.h"
|
||
|
||
#ifdef __cplusplus
|
||
extern "C" {
|
||
#endif
|
||
|
||
typedef struct meow_view meow_view;
|
||
|
||
typedef enum { MEOW_VIEW_ACTIVITY = 0, MEOW_VIEW_CONTAINER = 1 } meow_view_type;
|
||
typedef enum {
|
||
MEOW_VIEW_STATE_CREATED = 1u << 0,
|
||
MEOW_VIEW_STATE_ENTERED = 1u << 1,
|
||
MEOW_VIEW_STATE_DIRTY = 1u << 2,
|
||
} meow_view_state;
|
||
|
||
/* 生命周期/事件钩子（on_create→on_enter→(事件循环)→on_leave→on_destroy + on_layout）。
|
||
* 均以 view 自身 + ctx（=视图控制器，业务-UI 绑定点）为参。可 NULL。 */
|
||
typedef void (*meow_view_fn)(meow_view *v, void *ctx);
|
||
typedef int (*meow_view_ev_fn)(meow_view *v, int ev, int a, int b, void *ctx);
|
||
typedef void (*meow_view_draw_fn)(meow_view *v, const meow_theme *th, void *ctx);
|
||
|
||
typedef struct meow_view_hooks {
|
||
meow_view_fn on_create; /* 建 view 后跑一次（分配视图态/初始布局） */
|
||
meow_view_fn on_enter; /* 页面进入（push/replace 后；回页面自动恢复零重建） */
|
||
meow_view_fn on_leave; /* 页面离开（pop/replace 前；默认不销毁子 view/widget） */
|
||
meow_view_fn on_destroy; /* meow_view_free 释放（递归）时跑 */
|
||
meow_view_fn on_layout; /* 布局（on_create/page_push 后跑一次，算子控件绝对坐标） */
|
||
meow_view_draw_fn on_draw; /* 绘制回调（非保留；由 meow_ui_invalidate 触发） */
|
||
meow_view_ev_fn on_event; /* 事件路由（可 NULL；先发后代按 z 降序，命中即消费） */
|
||
} meow_view_hooks;
|
||
|
||
#define MEOW_VIEW_MAX_CHILD 16
|
||
#define MEOW_VIEW_MAX_WIDGET 32
|
||
|
||
struct meow_view {
|
||
int type; /* MEOW_VIEW_ACTIVITY / MEOW_VIEW_CONTAINER */
|
||
int id; /* 页面/视图 id（App 命名的稳定值；= page_push 用的 id） */
|
||
int x, y, w, h; /* 自身坐标（相对父内容原点；子 view 默认占满，叠放由 z 排） */
|
||
meow_view *parent;
|
||
meow_view *children[MEOW_VIEW_MAX_CHILD];
|
||
int nchildren;
|
||
meow_widget *widgets[MEOW_VIEW_MAX_WIDGET]; /* 叶子控件（直接挂本 view） */
|
||
int nwidgets;
|
||
int z; /* 显式 z（meow_view_set_z）；0=未设（由子/注册表推导） */
|
||
unsigned state; /* meow_view_state 位掩码 */
|
||
meow_view_hooks hooks;
|
||
void *ctx; /* 视图控制器（biz-UI 绑定点） */
|
||
};
|
||
|
||
/* ---- 生命周期 ---- */
|
||
meow_view *meow_view_create(int id, meow_view_type type,
|
||
const meow_view_hooks *hooks, void *ctx);
|
||
void meow_view_free(meow_view *v); /* 递归 on_destroy + widget_free 叶子 + 注销 z 序 */
|
||
|
||
/* ---- 嵌套（组合视图树）---- */
|
||
int meow_view_add_child(meow_view *parent, meow_view *child); /* 任意深挂子 view；0/负=结果 */
|
||
int meow_view_add_widget(meow_view *v, meow_widget *w); /* 挂叶子控件（登记 z 深度源） */
|
||
void meow_view_set_z(meow_view *v, int z); /* 显式 z（999 置顶）；影响其绘制物 z */
|
||
int meow_view_z(const meow_view *v);
|
||
|
||
/* ---- 页面导航（包装 activity 栈，唯一驱动 on_enter/on_leave——单一入口，App 不再分别调）----
|
||
* 顶层页切换走 activity 栈；页内子导航为预留（见设计定案 b）。 */
|
||
void meow_view_page_push(int id); /* activity_push + 旧top on_leave + 新页 on_enter */
|
||
void meow_view_page_pop(void); /* 旧top on_leave + activity_pop + 新top on_enter */
|
||
void meow_view_page_replace(int id); /* 旧top on_leave + 新页 on_enter（目标页须已 create） */
|
||
|
||
/* ---- 页内子导航（预留扩展位 a；本批为空实现/桩，仅在 ACTIVITY view 内维护子栈）---- */
|
||
int meow_view_sub_push(meow_view *v, meow_view *sub); /* 预留；返回 0（未实现于本批） */
|
||
meow_view *meow_view_sub_pop(meow_view *v); /* 预留；返回 NULL（未实现于本批） */
|
||
|
||
/* ---- 坐标：view 相对父内容原点的累计（父坐标链求和 → 屏幕绝对坐标）---- */
|
||
int meow_view_screen_x(const meow_view *v);
|
||
int meow_view_screen_y(const meow_view *v);
|
||
|
||
/* ---- 查询 ---- */
|
||
meow_view *meow_view_parent(const meow_view *v);
|
||
int meow_view_get_state(const meow_view *v); /* MEOW_VIEW_STATE_* 位掩码 */
|
||
|
||
#ifdef __cplusplus
|
||
}
|
||
#endif
|
||
#endif /* MEOW_UI_VIEW_H */
|