/*
 * 模块名称：UI Menu View (菜单显示模型渲染层)
 * 模块功能：以 LVGL 基元控件实现《菜单页面设计.md》§四⑧"横向级联子框"显示模型：
 *           右贴靠（子框左缘=父框右缘、共享边框列）+ 框宽内容自适应 +
 *           顶对齐/底对齐上移；持有全部 LVGL 对象（样式/4 层容器/框/根框装饰），
 *           不持有任何导航状态——状态由逻辑层 ui_menu.c 经本接口驱动
 * 适用平台：STM32F407ZGTx / PC 模拟器（两端共用）
 * 作者：王建锋
 * 创建日期：2026-09-04
 * 修改记录：
 *     2026-09-04  王建锋  创建：自旧 ui_menu.c 单页模型拆分出显示层（高内聚低耦合）
 *     2026-09-08  王建锋  行改自绘（节点下标注册 + 框体 DRAW_MAIN 自绘 + 虚拟滚动），接口不变
 */
#ifndef UI_MENU_VIEW_H
#define UI_MENU_VIEW_H

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

#include "lvgl.h"

#define MENU_PAGE_MAX   4   /* 页面深度上限（根框 + 3 级子框） */
#define MENU_ITEM_MAX   16  /* 单框最大条目数 */

#define MENU_SCREEN_W   160 /* 屏幕宽（px，与 ui_port.h / 模拟器一致） */
#define MENU_SCREEN_H   160 /* 屏幕高（px） */

/*
 * 函数功能：初始化显示层（样式 + 4 层持久容器 + 根框装饰 + 根框框体）
 * 入口参数：无
 * 返回值：0 - 成功，其他 - 失败（对象创建失败）
 * 限定条件：LVGL 已初始化且活动屏幕存在（ui_port_init / sim_port_init 已完成）
 * 函数说明：1. 4 层容器每深度一个、全屏覆盖、持久不删（焦点/键入口，防悬空）
 *           2. 根框装饰（浅 V + 状态行）与根框框体只属根层（d=0）
 *           3. 行数据由逻辑层经 ui_menu_view_frame_build 注册，框体自绘行
 */
int ui_menu_view_init(void);

/*
 * 函数功能：取指定深度的持久容器
 * 入口参数：depth - 深度 0..MENU_PAGE_MAX-1  uint8_t
 * 返回值：容器对象  lv_obj_t *  越界返回 NULL
 * 限定条件：ui_menu_view_init() 已完成
 * 函数说明：逻辑层在容器上绑定输入组与键事件（显示层不碰输入）
 */
lv_obj_t *ui_menu_view_container(uint8_t depth);

/*
 * 函数功能：构建指定深度的框（几何现算 + 行数据注册 + 选中/滚动应用）
 * 入口参数：depth  - 深度（0=根框）  uint8_t
 *           node   - 本框展示节点（行 = 其子项）  uint8_t
 *           sel    - 本框选中行  uint8_t
 *           scroll - 本框滚动偏移（px，0=顶部）  uint16_t
 * 返回值：无
 * 限定条件：depth>0 时 depth-1 层框已建（父框几何是其对齐依据）
 * 函数说明： 1. d=0：根框框体已存在，仅（重）注册行数据
 *           2. d>0：右贴靠父框右缘；顶边=父框选中行行顶，超屏底则
 *              上移使本框底边对齐父框选中行行底，仍超顶则钳制顶部并改框内滚动
 *           3. 框宽 = 最宽行（文本 + ▶ + 左右留白）+ 边框；条目现算不落地
 */
void ui_menu_view_frame_build(uint8_t depth, uint8_t node, uint8_t sel, uint16_t scroll);

/*
 * 函数功能：销毁指定深度的框（框体连自绘回调整体删除，容器保留）
 * 入口参数：depth - 深度  uint8_t
 * 返回值：无
 * 限定条件：depth>0（根框持久不可销毁）
 * 函数说明：返回（关最右框）时调用，LVGL 池内存随即回落
 */
void ui_menu_view_frame_destroy(uint8_t depth);

/*
 * 函数功能：刷新指定深度框的选中高亮
 * 入口参数：depth - 深度  uint8_t
 *           sel   - 新选中行  uint8_t
 * 返回值：无
 * 限定条件：ui_menu_view_frame_build(depth,…) 已完成
 * 函数说明：只改选中数据 + 跟随滚动、重绘框体，不重建对象
 */
void ui_menu_view_frame_refresh(uint8_t depth, uint8_t sel);

/*
 * 函数功能：应用指定深度框的滚动偏移
 * 入口参数：depth  - 深度  uint8_t
 *           scroll - 滚动偏移（px）  uint16_t
 * 返回值：无
 * 限定条件：该层框已建
 * 函数说明：行重建后按此还原用户滚动位置
 */
void ui_menu_view_set_scroll(uint8_t depth, uint16_t scroll);

/*
 * 函数功能：读取指定深度框当前滚动偏移
 * 入口参数：depth - 深度  uint8_t
 * 返回值：滚动偏移（px）  uint16_t  未建框返回 0
 * 限定条件：无
 * 函数说明：跟随滚动后由逻辑层读回，写入导航状态持久化
 */
uint16_t ui_menu_view_get_scroll(uint8_t depth);

/*
 * 函数功能：焦点移至指定深度的容器
 * 入口参数：depth - 深度  uint8_t
 * 返回值：无
 * 限定条件：ui_menu_view_init() 已完成且容器已加入输入组
 * 函数说明：焦点=最右框；进/退时由逻辑层调用
 */
void ui_menu_view_focus(uint8_t depth);

#endif /* UI_MENU_VIEW_H */