/*
 * 模块名称：UI Menu (菜单导航逻辑层)
 * 模块功能：g_menu_tab 父子索引表驱动的横向级联菜单导航——持有导航状态
 *           （路径/选中/深度/滚动，共 17 B）与键语义（↑↓移选、→/ENTER 进、←/ESC 退），
 *           单向驱动显示层 ui_menu_view 建/毁/刷新级联框；本层不持有任何 LVGL 对象
 * 适用平台：STM32F407ZGTx / PC 模拟器（两端共用）
 * 作者：王建锋
 * 创建日期：2026-08-29
 * 修改记录：
 *     2026-08-29  王建锋  创建初始版本
 *     2026-09-02  王建锋  弃用已废弃的 lv_menu 控件，改为基元控件页面导航
 *     2026-09-04  王建锋  重构为"横向级联框"模型（菜单页面设计.md）：拆出显示层
 *                        ui_menu_view 与数据层 ui_menu_tab；本层只留导航状态机
 *     2026-11-02  DTU 项目组  新增 ui_menu_get_nav_state（#69 板端导航身份查询：
 *                        主机侧不再只靠像素认屏猜"在哪一列选中哪一项"）
 */
#ifndef UI_MENU_H
#define UI_MENU_H

#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

/*
 * 函数功能：构建菜单（横向级联框：右贴靠 + 自适应宽 + 顶/底对齐）
 * 入口参数：无
 * 返回值：0 - 成功，其他 - 失败（菜单表自检失败或对象创建失败）
 * 限定条件：ui_port_init()（或模拟器 sim_port_init）已成功调用，活动屏幕存在
 * 函数说明： 1. 数据表自检（parent 下标均有效，捕获表内笔误）
 *           2. 初始化显示层（样式/4 层持久容器/根框装饰与框体）
 *           3. 各层容器加入默认输入组，按键由逻辑层统一分发（显示层纯渲染）
 *           4. 构建根框（主界面 node 0 的子项）并置焦点
 */
int ui_menu_init(void);

/*
 * 函数功能：读取菜单导航状态（身份查询/调试消费的只读快照，Issue #69）
 * 入口参数：p_depth - 输出当前深度（0 = 根框）        uint8_t *，可为 NULL
 *           p_path  - 输出路径数组指针（节点下标）    const uint8_t **，可为 NULL
 *           p_sel   - 输出各层选中下标数组指针        const uint8_t **，可为 NULL
 * 返回值：无
 * 限定条件：与导航同上下文（uiTask/模拟器主循环）调用才有一致性语义；
 *           ui_menu_init() 前调用返回初始零值，不崩
 * 函数说明：输出指针指向本模块静态数组（共 17 B 导航状态，见设计 §7.2），
 *           调用方只读、最多读"深度+1"项（上限 MENU_PAGE_MAX）、不得改写；
 *           弹框被屏裁时像素认屏看不见选带，本接口是主机侧唯一的菜单真值出口
 */
void ui_menu_get_nav_state(uint8_t *p_depth, const uint8_t **p_path, const uint8_t **p_sel);

#ifdef __cplusplus
}
#endif

#endif /* UI_MENU_H */