/*
 * 模块名称：UI Content Page (内容页框架)
 * 模块功能：菜单叶子节点进入的内容页（独立全屏页面）框架——
 *           屏/容器按需建毁生命周期 + 焦点 + 切屏、按键分发（内置 ↑↓/ESC + key_cb 钩子）、
 *           描述符驱动通用绘制（浅 V + 标题/副标题 + 行 + 选中带 + 页脚 + draw_cb）；
 *           不持任何页面数据：各页数据/几何/钩子由 ui_page_xxx 模块经 content_page_def_t
 *           接入框架描述符表（架构见 内容页架构.md）；
 *           进入时切屏并获焦、ESC 返回菜单屏并还原焦点；
 *           不持有导航状态——由逻辑层 ui_menu.c 在 ENTER 叶子节点时驱动
 * 适用平台：STM32F407ZGTx / PC 模拟器（两端共用）
 * 作者：王建锋
 * 创建日期：2026-09-09
 * 修改记录：
 *     2026-09-09  王建锋  创建：装置信息/交流量/直流量三页（参考图 10/20/21）
 *     2026-09-09  王建锋  "浅 V"装饰几何提取至共享 ui_deco 模块（不再本地重复定义）
 *     2026-09-09  王建锋  拆分为"框架 + 页面插件"模型（内容页架构.md）：三页数据移入
 *                        ui_page_xxx 模块；本文件只留描述类型与 API；描述符新增
 *                        4 个扩展钩子（refresh/count_cb/draw_cb/key_cb）
 *     2026-09-09  王建锋  密码页（用户密钥）：描述符新增 title_y/hide_deco/hide_footer/key_intercept
 *                        4 字段 + 新 API ui_content_page_invalidate；← 键可每页拦截
 *                        （ESC 恒不可拦截）
 *     2026-09-09  王建锋  权限模型：open() 增授予权限实参（ui_perm_t，逻辑层按
 *                        是否过密码页/所输密码决定）；描述符新增 edit_capable（页面
 *                        是否支持编辑模式）+ 新 API ui_content_page_is_editable
 *                        （页面钩子据以决定编辑行为：edit_capable 且修改权限）
 */
#ifndef UI_CONTENT_PAGE_H
#define UI_CONTENT_PAGE_H

#include <stdint.h>
#include <stdbool.h>

#include "lvgl.h"

/*
 * 内容页 ID：与菜单叶子节点一一对应（映射见 ui_menu.c menu_content_page_for）；
 * CONTENT_PAGE_COUNT 兼作"无内容页/未打开"哨兵值
 */
typedef enum {
    CONTENT_PAGE_DEVICE_INFO = 0u,   /* 装置信息（node 1）：静态键值行 + 副标题，单页 */
    CONTENT_PAGE_AC,                 /* 交流量（node 3）：数据列表，24 项 / 8 项每页 */
    CONTENT_PAGE_DC,                 /* 直流量（node 4）：数据列表，3 项单页 */
    CONTENT_PAGE_PASSWORD,           /* 用户密钥（密码页）：3 位密码，表单/操作页首个实例 */
    CONTENT_PAGE_NET_CFG,            /* 网口设置（node 30）：地址列表 + 保存行，可编辑（修改权限） */
    CONTENT_PAGE_COUNT               /* 哨兵：无效 ID / 未打开 */
} content_page_id_t;

/* 行数据：左列名 + 右列值（Flash 字面量，不 strdup） */
typedef struct {
    const char *name;
    const char *value;
} cp_row_t;

/*
 * 页面描述符：一页 = 一个 Flash const 结构（几何 + 数据源 + 可选钩子）
 * 由各 ui_page_xxx 页面模块提供，框架描述符表 s_defs[] 按页 ID 引用
 */
typedef struct {
    const char *title;                          /* 标题（浅 V 区居中） */
    const char *subtitle;                       /* 副标题；NULL = 无（仅信息页有） */
    int32_t  subtitle_y;                        /* 副标题放置 y（仅 subtitle 非空时有效） */
    int32_t  title_y;                           /* 标题放置 y；0 = 框架默认（CP_TITLE_Y） */
    uint8_t  hide_deco;                         /* 1 = 不绘"浅 V"装饰（密码页跟随实机） */
    uint8_t  hide_footer;                       /* 1 = 不绘页脚页码（密码页跟随实机：无页脚） */
    uint8_t  selectable;                        /* 1 = 列表页（↑↓移选+分页）；0 = 信息页（静态行） */
    uint8_t  key_intercept;                     /* 1 = LV_KEY_LEFT 先交 key_cb（true = 页已处理不关页）；ESC 恒不可拦截 */
    uint8_t  edit_capable;                      /* 1 = 本页支持编辑模式（可编辑还须 UI_PERM_MODIFY 权限） */
    int32_t  top_y;                             /* 首行槽顶 y */
    int32_t  pitch;                             /* 行距（相邻行槽顶间距） */
    int32_t  band_h;                            /* 选中白带高（0 = 无选中带） */
    int32_t  text_dy;                           /* 文本放置相对行槽顶的垂直偏移 */
    int32_t  left_x;                            /* 左列 x（信息页=标签、列表页=名） */
    int32_t  right_x;                           /* 右列 x（值） */
    uint8_t  rows_per_page;                     /* 每页可见行数（0 = 不分页） */
    uint16_t row_count;                         /* 总行数（静态页；动态页用 count_cb） */
    const cp_row_t *rows;                       /* 静态数据表（Flash）；NULL = 动态页 */
    uint8_t  fixed_cur_page;                    /* 信息页页脚"第 X 页"固定显示值 */
    uint8_t  fixed_total_pages;                /* 信息页页脚"共 Y 页"固定显示值 */
    /* —— 扩展钩子（全可选；NULL = 纯内置行为；均运行在 uiTask 上下文）—— */
    void     (*init_cb)(void);                                        /* 开页后调一次（页面模块重置运行态） */
    void     (*refresh)(uint16_t row, char *name, char *value);       /* 动态行：逐行取数（名/值） */
    uint16_t (*count_cb)(void);                                       /* 动态行数（记录页） */
    void     (*draw_cb)(lv_layer_t *layer, const lv_area_t *clip);    /* 表单/操作页：自定义内容 */
    bool     (*key_cb)(lv_key_t key);                                 /* 页面自有键；true = 页已处理 */
} content_page_def_t;

/*
 * 函数功能：打开指定内容页（建屏 + 切屏 + 焦点置页面容器）
 * 入口参数：id   - 内容页 ID  content_page_id_t
 *           perm - 本次进入授予的权限  ui_perm_t（UI_PERM_VIEW/MODIFY；
 *                  由逻辑层按是否过密码页/所输密码决定，页面经
 *                  ui_content_page_is_editable 查询）
 * 返回值：true - 成功；false - 失败（ID 无效/已有页面打开/无描述符/对象创建失败）
 * 限定条件：ui_menu_init() 已完成（默认输入组与菜单屏存在）
 * 函数说明：1. 新建独立屏幕，全屏容器自绘全部内容（无子对象，池开销极小）
 *           2. 容器入默认输入组并获焦——按键由本模块处理（↑↓移选/ESC返回/页面钩子）
 *           3. 导航状态不压层：菜单 s_depth/s_sel 原样保留，ESC 返回即还原
 */
bool ui_content_page_open(content_page_id_t id, uint8_t perm);

/*
 * 函数功能：关闭当前内容页（焦点回菜单容器 + 切回菜单屏 + 销毁页面）
 * 入口参数：无
 * 返回值：无
 * 限定条件：ui_content_page_is_open() 为 true
 * 函数说明：先移焦再删屏，防输入组焦点悬空；LVGL 池内存随即回落
 */
void ui_content_page_close(void);

/*
 * 函数功能：失效当前打开的页面容器（触发整页重绘）
 * 入口参数：无
 * 返回值：无
 * 限定条件：有页面打开时生效
 * 函数说明：供页面模块（表单/操作页）自身状态变化后调用；无页打开时空操作
 */
void ui_content_page_invalidate(void);

/*
 * 函数功能：查询是否有内容页打开
 * 入口参数：无
 * 返回值：true - 有页面打开；false - 无
 * 限定条件：无
 * 函数说明：供逻辑层/调试判断当前处于菜单屏还是内容页
 */
bool ui_content_page_is_open(void);

/*
 * 函数功能：查询当前打开的页面是否可编辑
 * 入口参数：无
 * 返回值：true - 页面支持编辑模式且被授予修改权限；false - 其余（无页打开/
 *                  页面不支持编辑/仅只读权限）
 * 限定条件：无
 * 函数说明：供页面钩子（key_cb/draw_cb）决定编辑行为；权限由 ui_content_page_open
 *           的 perm 实参授予（逻辑层按密码页结果/无密码默认只读传入）
 */
bool ui_content_page_is_editable(void);

/*
 * 函数功能：查询当前列表页的选中行（全局下标，跨页连续）
 * 入口参数：无
 * 返回值：选中行下标；无页打开/非列表页 = 0  uint16_t
 * 限定条件：无
 * 函数说明：供页面钩子（key_cb/draw_cb）感知当前选中位置（编辑模式以
 *          选中行作用、绘制钩子定位选中行带）
 */
uint16_t ui_content_page_selected_row(void);

#endif /* UI_CONTENT_PAGE_H */