333 lines
8.6 KiB
C
333 lines
8.6 KiB
C
/**
|
||
**********************************************************************************************************************
|
||
* @file menu_api.h
|
||
* @brief 菜单组件对外API接口定义
|
||
* @author menu_component
|
||
* @date 2025-12-19
|
||
**********************************************************************************************************************
|
||
*/
|
||
|
||
#ifndef MENU_API_H
|
||
#define MENU_API_H
|
||
|
||
/* Includes ----------------------------------------------------------------------------------------------------------*/
|
||
#include "../src/core/menu_config.h"
|
||
#include "../src/core/menu_types.h"
|
||
|
||
/* 宏定义 -----------------------------------------------------------------------------------------------------------*/
|
||
#define MENU_API_VERSION "1.0.1"
|
||
|
||
/* 函数声明 ---------------------------------------------------------------------------------------------------------*/
|
||
|
||
/* 菜单初始化与反初始化 ---------------------------------------------------------------------------------------------*/
|
||
|
||
/**
|
||
* @brief 初始化菜单组件
|
||
* @return 错误码
|
||
*/
|
||
MenuErrCode menu_init(void);
|
||
|
||
/**
|
||
* @brief 反初始化菜单组件
|
||
* @return 错误码
|
||
*/
|
||
MenuErrCode menu_deinit(void);
|
||
|
||
/* 菜单节点管理 -----------------------------------------------------------------------------------------------------*/
|
||
|
||
/**
|
||
* @brief 注册菜单节点
|
||
* @param node_id 节点ID（0表示自动分配）
|
||
* @param parent_id 父节点ID
|
||
* @param name 节点名称
|
||
* @param enter_cb 进入回调
|
||
* @param exit_cb 退出回调
|
||
* @return 实际分配的节点ID
|
||
*/
|
||
MenuNodeId menu_register_node(MenuNodeId node_id, MenuNodeId parent_id, const char* name, MenuCallback enter_cb, MenuCallback exit_cb);
|
||
|
||
/**
|
||
* @brief 批量注册菜单节点
|
||
* @param nodes 节点数组
|
||
* @param count 节点数量
|
||
* @return 错误码
|
||
*/
|
||
MenuErrCode menu_register_nodes(const struct MenuNode* nodes, uint16_t count);
|
||
|
||
/**
|
||
* @brief 注销菜单节点
|
||
* @param node_id 节点ID
|
||
* @return 错误码
|
||
*/
|
||
MenuErrCode menu_unregister_node(MenuNodeId node_id);
|
||
|
||
/**
|
||
* @brief 更新菜单节点
|
||
* @param node_id 节点ID
|
||
* @param name 节点名称（NULL表示不更新）
|
||
* @param enter_cb 进入回调（NULL表示不更新）
|
||
* @param exit_cb 退出回调（NULL表示不更新）
|
||
* @return 错误码
|
||
*/
|
||
MenuErrCode menu_update_node(MenuNodeId node_id, const char* name, MenuCallback enter_cb, MenuCallback exit_cb);
|
||
|
||
/**
|
||
* @brief 查找菜单节点
|
||
* @param node_id 节点ID
|
||
* @return 节点指针，未找到返回NULL
|
||
*/
|
||
const struct MenuNode* menu_find_node(MenuNodeId node_id);
|
||
|
||
/* 菜单事件处理 -----------------------------------------------------------------------------------------------------*/
|
||
|
||
/**
|
||
* @brief 发送菜单事件
|
||
* @param event_type 事件类型
|
||
* @param priority 事件优先级（0-3，0最高）
|
||
* @return 错误码
|
||
*/
|
||
MenuErrCode menu_post_event(MenuEventType event_type, uint8_t priority);
|
||
|
||
/**
|
||
* @brief 发送带数据的菜单事件
|
||
* @param event_type 事件类型
|
||
* @param priority 事件优先级（0-3，0最高）
|
||
* @param data 事件数据
|
||
* @return 错误码
|
||
*/
|
||
MenuErrCode menu_post_event_with_data(MenuEventType event_type, uint8_t priority, void* data);
|
||
|
||
/* 菜单导航操作 -----------------------------------------------------------------------------------------------------*/
|
||
|
||
/**
|
||
* @brief 菜单主循环，处理事件和刷新显示
|
||
* @param tick 当前系统时间（ms）
|
||
* @return 错误码
|
||
*/
|
||
MenuErrCode menu_main_loop(uint32_t tick);
|
||
|
||
/**
|
||
* @brief 进入菜单
|
||
* @return 错误码
|
||
*/
|
||
MenuErrCode menu_enter(void);
|
||
|
||
/**
|
||
* @brief 退出菜单
|
||
* @return 错误码
|
||
*/
|
||
MenuErrCode menu_exit(void);
|
||
|
||
/**
|
||
* @brief 上移菜单项
|
||
* @return 错误码
|
||
*/
|
||
MenuErrCode menu_up(void);
|
||
|
||
/**
|
||
* @brief 下移菜单项
|
||
* @return 错误码
|
||
*/
|
||
MenuErrCode menu_down(void);
|
||
|
||
/**
|
||
* @brief 选择菜单项
|
||
* @param node_id 节点ID
|
||
* @return 错误码
|
||
*/
|
||
MenuErrCode menu_select(MenuNodeId node_id);
|
||
|
||
/**
|
||
* @brief 重置菜单，回到主菜单
|
||
* @return 错误码
|
||
*/
|
||
MenuErrCode menu_reset(void);
|
||
|
||
/* 菜单状态查询 -----------------------------------------------------------------------------------------------------*/
|
||
|
||
/**
|
||
* @brief 获取当前菜单状态
|
||
* @return 当前菜单状态
|
||
*/
|
||
MenuState menu_get_state(void);
|
||
|
||
/**
|
||
* @brief 获取当前选中的节点ID
|
||
* @return 当前节点ID
|
||
*/
|
||
MenuNodeId menu_get_current_node(void);
|
||
|
||
/**
|
||
* @brief 获取导航深度
|
||
* @return 导航深度
|
||
*/
|
||
uint8_t menu_get_nav_depth(void);
|
||
|
||
/**
|
||
* @brief 获取导航路径
|
||
* @param path 用于存储导航路径的数组
|
||
* @param max_depth 数组最大深度
|
||
* @return 实际获取的深度
|
||
*/
|
||
uint8_t menu_get_nav_path(MenuNodeId* path, uint8_t max_depth);
|
||
|
||
/* 状态机扩展接口 ---------------------------------------------------------------------------------------------------*/
|
||
|
||
#if MENU_CONFIG_ENABLE_STATE_MACHINE_EXT
|
||
/**
|
||
* @brief 注册自定义状态转换规则
|
||
* @param transition 状态转换规则
|
||
* @return 错误码
|
||
*/
|
||
MenuErrCode menu_state_register_transition(const MenuStateTransition* transition);
|
||
|
||
/**
|
||
* @brief 注销自定义状态转换规则
|
||
* @param current_state 当前状态
|
||
* @param event 触发事件
|
||
* @return 错误码
|
||
*/
|
||
MenuErrCode menu_state_unregister_transition(MenuState current_state, MenuEventType event);
|
||
|
||
/**
|
||
* @brief 切换到指定状态
|
||
* @param state 目标状态
|
||
* @return 错误码
|
||
*/
|
||
MenuErrCode menu_state_switch(MenuState state);
|
||
#endif
|
||
|
||
/* 内存监控接口 -----------------------------------------------------------------------------------------------------*/
|
||
|
||
#if MENU_CONFIG_ENABLE_MEM_MONITOR
|
||
/**
|
||
* @brief 获取已使用节点数量
|
||
* @return 已使用节点数量
|
||
*/
|
||
uint16_t menu_mem_get_used_nodes(void);
|
||
|
||
/**
|
||
* @brief 获取空闲节点数量
|
||
* @return 空闲节点数量
|
||
*/
|
||
uint16_t menu_mem_get_free_nodes(void);
|
||
|
||
/**
|
||
* @brief 获取最大节点数量
|
||
* @return 最大节点数量
|
||
*/
|
||
uint16_t menu_mem_get_max_nodes(void);
|
||
#endif
|
||
|
||
/* 权限管理接口 -----------------------------------------------------------------------------------------------------*/
|
||
|
||
#if MENU_CONFIG_ENABLE_PERMISSION
|
||
/**
|
||
* @brief 注册角色
|
||
* @param role 角色结构体指针
|
||
* @return 错误码
|
||
*/
|
||
MenuErrCode menu_permission_register_role(const MenuRole* role);
|
||
|
||
/**
|
||
* @brief 注销角色
|
||
* @param role_id 角色ID
|
||
* @return 错误码
|
||
*/
|
||
MenuErrCode menu_permission_unregister_role(MenuRoleId role_id);
|
||
|
||
/**
|
||
* @brief 设置当前角色
|
||
* @param role_id 角色ID
|
||
* @return 错误码
|
||
*/
|
||
MenuErrCode menu_permission_set_current_role(MenuRoleId role_id);
|
||
|
||
/**
|
||
* @brief 获取当前角色
|
||
* @return 当前角色ID
|
||
*/
|
||
MenuRoleId menu_permission_get_current_role(void);
|
||
|
||
/**
|
||
* @brief 更新节点权限级别
|
||
* @param node_id 节点ID
|
||
* @param permission_level 权限级别
|
||
* @return 错误码
|
||
*/
|
||
MenuErrCode menu_permission_update_node_level(MenuNodeId node_id, MenuPermissionLevel permission_level);
|
||
|
||
/**
|
||
* @brief 获取节点权限级别
|
||
* @param node_id 节点ID
|
||
* @return 节点权限级别
|
||
*/
|
||
MenuPermissionLevel menu_permission_get_node_level(MenuNodeId node_id);
|
||
|
||
/**
|
||
* @brief 检查节点是否可访问
|
||
* @param node_id 节点ID
|
||
* @return true表示可访问，false表示不可访问
|
||
*/
|
||
bool menu_permission_check_node_access(MenuNodeId node_id);
|
||
|
||
/**
|
||
* @brief 获取角色信息
|
||
* @param role_id 角色ID
|
||
* @return 角色结构体指针，NULL表示角色不存在
|
||
*/
|
||
const MenuRole* menu_permission_get_role(MenuRoleId role_id);
|
||
#endif
|
||
|
||
/* 状态持久化接口 ---------------------------------------------------------------------------------------------------*/
|
||
|
||
#if MENU_CONFIG_ENABLE_PERSISTENCE
|
||
/**
|
||
* @brief 注册持久化回调函数
|
||
* @param save_cb 保存回调函数
|
||
* @param restore_cb 恢复回调函数
|
||
* @return 错误码
|
||
*/
|
||
MenuErrCode menu_persistence_register_callback(MenuPersistenceCallback save_cb, MenuRestoreCallback restore_cb);
|
||
|
||
/**
|
||
* @brief 启用或禁用自动保存
|
||
* @param enable true表示启用，false表示禁用
|
||
* @return 错误码
|
||
*/
|
||
MenuErrCode menu_persistence_set_auto_save(bool enable);
|
||
|
||
/**
|
||
* @brief 获取自动保存状态
|
||
* @return true表示启用，false表示禁用
|
||
*/
|
||
bool menu_persistence_get_auto_save(void);
|
||
|
||
/**
|
||
* @brief 设置自动保存间隔
|
||
* @param interval 自动保存间隔（ms）
|
||
* @return 错误码
|
||
*/
|
||
MenuErrCode menu_persistence_set_auto_save_interval(uint32_t interval);
|
||
|
||
/**
|
||
* @brief 获取自动保存间隔
|
||
* @return 自动保存间隔（ms）
|
||
*/
|
||
uint32_t menu_persistence_get_auto_save_interval(void);
|
||
|
||
/**
|
||
* @brief 手动保存菜单状态
|
||
* @return 错误码
|
||
*/
|
||
MenuErrCode menu_persistence_save(void);
|
||
|
||
/**
|
||
* @brief 恢复菜单状态
|
||
* @return 错误码
|
||
*/
|
||
MenuErrCode menu_persistence_restore(void);
|
||
#endif
|
||
|
||
#endif /* MENU_API_H */
|