107 lines
6.3 KiB
C
107 lines
6.3 KiB
C
/*
|
||
* meow_lazygrid.h — SDK 2 维虚拟化宫格（§12.4：meow_lazygrid，M7.4 主界面前置）。
|
||
*
|
||
* 定位：给「卡片/图标宫格」提供**二维虚拟化**——应用入口宫格、图标墙、设置快捷卡等。
|
||
* 只实例化**可见行**（视口内），行高/列几何 + gap；滚动复用 §12.3 meow_scroll（fling/snap），
|
||
* 与 meow_listview 同款惯性；命中 meow_lazygrid_hit/tap_at 把滚动+网格坐标映射回 item idx。
|
||
*
|
||
* 设计（仿 meow_listview 的 vsource 思想 + meow_scroll 滚动 + meow_box 列几何）：
|
||
* - 数据源：count_fn() 返回总项数（任意长），bind_fn(index, item) 仅当 item「进入视口」
|
||
* （绑定到固定池槽）时调一次；回滚命中同槽不重绑（同 listview 池语义）。
|
||
* - 固定 item 池：池容量 = 视口行数 + 2（× cols），静态有界（≤MEOW_LAZYGRID_POOL_MAX）。
|
||
* - 列几何：cols + cell_w + cell_h + gap；行高 row_h = cell_h + gap；按 scroll offset 推可见行。
|
||
* - 渲染：默认 renderer 画「圆角卡片（icon+名+状态）」；App 也可经 set_item_draw 完全自绘
|
||
* （主界面卡片宫格用：icon+名+后台标注）。支持选中高亮/禁用变淡/空态占位。
|
||
* - 滚动：接 meow_scroll（meow_lazygrid_scroll 返回会话；track/fling/snap 与 listview 同款）。
|
||
*
|
||
* 内存纪律（M7 §5.2）：静态有界 item 池（冷路径 create/set_vsource 分配，热路径 draw/hit/scroll
|
||
* 零 malloc），与 listview 池同源；不常驻 count 个 item 对象。
|
||
*
|
||
* 非 meow_widget：lazygrid 是**自包含控件**（不注册进 z 序/绘制注册表），由宿主（launcher session）
|
||
* 在 draw 阶段调 meow_lazygrid_draw、命中阶段调 meow_lazygrid_hit/tap_at、滚动喂 meow_scroll——
|
||
* 与 meow_scroll/meow_box 同为「正交模块」，不侵入 struct meow_widget（全追加式）。
|
||
*/
|
||
#ifndef MEOW_UI_LAZYGRID_H
|
||
#define MEOW_UI_LAZYGRID_H
|
||
|
||
#include "meow_ui_types.h" /* meow_img 前向 + 基础类型（子头不引伞头，避免相对路径依赖） */
|
||
#include "meow_ui_theme.h" /* meow_theme（draw 取语义色） */
|
||
#include "meow_ui_scroll.h" /* meow_scroll（滚动集成；子头引依赖子头，同 widgets.h→theme.h） */
|
||
|
||
#ifdef __cplusplus
|
||
extern "C" {
|
||
#endif
|
||
|
||
typedef struct meow_lazygrid meow_lazygrid;
|
||
|
||
/* ---- cell / item ---- */
|
||
/* 单格数据（bind 回调填充；SDK 固定池持有；App 跨 bind 用 user 存业务态/图/index）。 */
|
||
typedef struct meow_lazygrid_item {
|
||
const char *title; /* 主文本（名；必填，NULL 视为空格） */
|
||
const char *subtitle; /* 副文本（状态/后台标注），可空 */
|
||
const meow_img *icon; /* 可选：格内图标（NULL=无） */
|
||
int enabled; /* 1=可交互；0=变淡不响应 */
|
||
void *user; /* App 私有（跨 bind 保存业务态；SDK 不碰） */
|
||
} meow_lazygrid_item;
|
||
|
||
/* 数据源：count 返回总项数（>=0，任意长）；bind 在 item 进入视口时调一次填充 item。
|
||
* 二者均不常驻 item 对象；count 每帧实时查（支持动态长度/搜索过滤）。 */
|
||
typedef int (*meow_lazygrid_count_fn)(void *ctx);
|
||
typedef void (*meow_lazygrid_bind_fn)(int index, meow_lazygrid_item *item, void *ctx);
|
||
|
||
/* 完全自绘回调（覆盖默认 renderer）：index=项号；x,y,w,h=格矩形（已裁剪到宫格视口）；
|
||
* state=MEOW_LAZYGRID_ST_* 状态位（选中/禁用组合）。App 用 §3 绘制 API 自绘整格。 */
|
||
typedef void (*meow_lazygrid_draw_fn)(int index, int x, int y, int w, int h,
|
||
int state, void *ctx);
|
||
/* state 位（draw 回调收到）。 */
|
||
#define MEOW_LAZYGRID_ST_SELECTED (1u<<0)
|
||
#define MEOW_LAZYGRID_ST_DISABLED (1u<<1)
|
||
|
||
/* 命中/点击回调（idx=项号；App 在 tap_at 命中后触发动作）。 */
|
||
typedef void (*meow_lazygrid_tap_fn)(int idx, void *ctx);
|
||
|
||
#define MEOW_LAZYGRID_POOL_MAX 96 /* 池容量上限（固定；保证静态有界） */
|
||
|
||
/* ---- 生命周期（冷路径 create/free；热路径 draw/hit/scroll 零 malloc）----
|
||
* cols=列数（>=1，越界 clamp）；cell_w/cell_h=格宽高；gap=格间距（水平与垂直同用）。 */
|
||
meow_lazygrid *meow_lazygrid_create(int x, int y, int w, int h, int cols,
|
||
int cell_w, int cell_h, int gap);
|
||
void meow_lazygrid_free(meow_lazygrid *g);
|
||
|
||
/* ---- 几何配置 ---- */
|
||
void meow_lazygrid_set_rect(meow_lazygrid *g, int x, int y, int w, int h); /* 视口矩形（绝对坐标） */
|
||
void meow_lazygrid_set_cols(meow_lazygrid *g, int cols);
|
||
void meow_lazygrid_set_cell(meow_lazygrid *g, int cell_w, int cell_h, int gap);
|
||
|
||
/* ---- 数据源 + 渲染 ---- */
|
||
int meow_lazygrid_set_vsource(meow_lazygrid *g, meow_lazygrid_count_fn count,
|
||
meow_lazygrid_bind_fn bind, void *ctx);
|
||
int meow_lazygrid_set_item_draw(meow_lazygrid *g, meow_lazygrid_draw_fn draw,
|
||
void *ctx); /* NULL=用默认卡片 renderer */
|
||
int meow_lazygrid_set_empty_text(meow_lazygrid *g, const char *text);
|
||
|
||
/* ---- 滚动（像素级；可视行数按 offset 实时推） ---- */
|
||
void meow_lazygrid_set_scroll(meow_lazygrid *g, int off);
|
||
void meow_lazygrid_scroll_by(meow_lazygrid *g, int dy);
|
||
int meow_lazygrid_scroll(meow_lazygrid *g);
|
||
int meow_lazygrid_max_scroll(meow_lazygrid *g); /* max(0, 内容高 - 视口高) */
|
||
int meow_lazygrid_row_h(const meow_lazygrid *g); /* 行高（=cell_h+gap） */
|
||
/* 便捷：包一个 meow_scroll 会话（set/max/get/redraw 指回本宫格；redraw 只刷视口区）。
|
||
* App 在 on_touch_move 喂 meow_scroll_track、松手 meow_scroll_fling。返回 NULL=池满。 */
|
||
meow_scroll *meow_lazygrid_scroll_attach(meow_lazygrid *g);
|
||
|
||
/* ---- 选中 / 命中 ---- */
|
||
void meow_lazygrid_set_on_tap(meow_lazygrid *g, meow_lazygrid_tap_fn cb, void *ctx);
|
||
void meow_lazygrid_set_sel(meow_lazygrid *g, int idx); /* 越界 clamp；<0 清除；标脏 */
|
||
int meow_lazygrid_sel(const meow_lazygrid *g);
|
||
int meow_lazygrid_hit(meow_lazygrid *g, int x, int y); /* 命中项 idx（滚动+网格坐标映射）；-1=未命中/禁用 */
|
||
int meow_lazygrid_tap_at(meow_lazygrid *g, int x, int y); /* 命中：置选中 + 回调 + 返回 idx/-1 */
|
||
|
||
/* ---- 绘制 ---- */
|
||
void meow_lazygrid_draw(meow_lazygrid *g, const meow_theme *th);
|
||
|
||
#ifdef __cplusplus
|
||
}
|
||
#endif
|
||
#endif /* MEOW_UI_LAZYGRID_H */
|