152 lines
4.9 KiB
C
152 lines
4.9 KiB
C
/**
|
||
* @file menu.h
|
||
* @brief 菜单组件对外暴露的核心接口（用户唯一需要包含的头文件）
|
||
* @note 工业级嵌入式菜单组件 - 对外API层
|
||
*/
|
||
#ifndef MENU_H
|
||
#define MENU_H
|
||
|
||
#include "menu_config.h"
|
||
#include <stdint.h>
|
||
#include <stdbool.h>
|
||
|
||
/************************** 全局类型导出 **************************/
|
||
/**
|
||
* @brief 菜单错误码（工业级错误处理：明确所有可能的错误类型）
|
||
*/
|
||
typedef enum {
|
||
MENU_OK = 0, ///< 操作成功
|
||
MENU_ERR_INVALID_PARAM, ///< 无效参数
|
||
MENU_ERR_OUT_OF_MEMORY, ///< 内存不足（静态内存池已满）
|
||
MENU_ERR_NODE_NOT_FOUND, ///< 菜单节点未找到
|
||
MENU_ERR_STACK_OVERFLOW, ///< 菜单栈溢出（导航层级超过配置）
|
||
MENU_ERR_STACK_UNDERFLOW, ///< 菜单栈下溢（已到根节点仍返回）
|
||
MENU_ERR_EVENT_QUEUE_FULL, ///< 事件队列已满
|
||
MENU_ERR_NOT_SUPPORTED, ///< 功能未启用（如未开启多语言）
|
||
MENU_ERR_HW_PORT_ERROR ///< 硬件端口层错误
|
||
} MenuErrCode;
|
||
|
||
/**
|
||
* @brief 菜单事件类型（事件驱动核心：解耦按键与菜单逻辑）
|
||
*/
|
||
typedef enum {
|
||
MENU_EVENT_NONE = 0, ///< 无事件
|
||
MENU_EVENT_KEY_UP, ///< 上键按下
|
||
MENU_EVENT_KEY_DOWN, ///< 下键按下
|
||
MENU_EVENT_KEY_ENTER, ///< 确认键按下
|
||
MENU_EVENT_KEY_BACK, ///< 返回键按下
|
||
MENU_EVENT_CUSTOM_BEGIN = 0x10, ///< 自定义事件起始标识（用户可扩展）
|
||
} MenuEventType;
|
||
|
||
/**
|
||
* @brief 菜单节点ID类型（统一标识）
|
||
*/
|
||
typedef uint16_t MenuNodeId;
|
||
|
||
/**
|
||
* @brief 菜单回调函数类型（菜单选中/退出时的执行逻辑）
|
||
* @param node_id 触发回调的菜单节点ID
|
||
* @return 错误码
|
||
*/
|
||
typedef MenuErrCode (*MenuCallback)(MenuNodeId node_id);
|
||
|
||
/************************** 核心接口声明 **************************/
|
||
/**
|
||
* @brief 菜单组件初始化（必须首先调用）
|
||
* @return 错误码
|
||
*/
|
||
MenuErrCode menu_init(void);
|
||
|
||
/**
|
||
* @brief 菜单主循环（需在用户主循环中调用，处理事件和刷新显示）
|
||
*/
|
||
void menu_main_loop(void);
|
||
|
||
/**
|
||
* @brief 发送事件到菜单事件队列（如按键事件、自定义事件）
|
||
* @param type 事件类型
|
||
* @param param 事件附加参数（可选，如按键长按时间）
|
||
* @return 错误码
|
||
*/
|
||
MenuErrCode menu_post_event(MenuEventType type, uint32_t param);
|
||
|
||
/**
|
||
* @brief 注册菜单节点（构建菜单树）
|
||
* @param parent_id 父节点ID（根节点填0）
|
||
* @param node_id 当前节点ID（唯一，不可重复）
|
||
* @param name_str 菜单名称字符串（或多语言索引）
|
||
* @param enter_cb 进入该菜单的回调函数（NULL表示无）
|
||
* @param exit_cb 退出该菜单的回调函数（NULL表示无）
|
||
* @return 错误码
|
||
*/
|
||
MenuErrCode menu_register_node(MenuNodeId parent_id, MenuNodeId node_id, const char* name_str, MenuCallback enter_cb, MenuCallback exit_cb);
|
||
|
||
/**
|
||
* @brief 获取当前选中的菜单节点ID
|
||
* @param node_id 输出参数，当前节点ID
|
||
* @return 错误码
|
||
*/
|
||
MenuErrCode menu_get_current_node(MenuNodeId* node_id);
|
||
|
||
/************************** 功能扩展接口声明（可裁剪） **************************/
|
||
#if MENU_CONFIG_ENABLE_PARAM
|
||
/**
|
||
* @brief 参数类型枚举
|
||
*/
|
||
typedef enum {
|
||
MENU_PARAM_TYPE_INT8,
|
||
MENU_PARAM_TYPE_UINT8,
|
||
MENU_PARAM_TYPE_INT16,
|
||
MENU_PARAM_TYPE_UINT16,
|
||
MENU_PARAM_TYPE_INT32,
|
||
MENU_PARAM_TYPE_UINT32,
|
||
MENU_PARAM_TYPE_FLOAT,
|
||
} MenuParamType;
|
||
|
||
/**
|
||
* @brief 注册参数到菜单节点（参数管理功能）
|
||
* @param node_id 菜单节点ID（参数与菜单绑定）
|
||
* @param param_id 参数ID（唯一）
|
||
* @param type 参数类型
|
||
* @param min_val 最小值（浮点型，内部自动转换）
|
||
* @param max_val 最大值（浮点型，内部自动转换）
|
||
* @param default_val 默认值（浮点型，内部自动转换）
|
||
* @param scale 缩放因子（如0.1表示保留1位小数）
|
||
* @return 错误码
|
||
*/
|
||
MenuErrCode menu_param_register(MenuNodeId node_id, uint16_t param_id, MenuParamType type, float min_val, float max_val, float default_val, float scale);
|
||
|
||
/**
|
||
* @brief 设置参数值
|
||
* @param param_id 参数ID
|
||
* @param value 新值（浮点型，内部自动转换）
|
||
* @return 错误码
|
||
*/
|
||
MenuErrCode menu_param_set_value(uint16_t param_id, float value);
|
||
|
||
/**
|
||
* @brief 获取参数值
|
||
* @param param_id 参数ID
|
||
* @param value 输出参数，当前值（浮点型）
|
||
* @return 错误码
|
||
*/
|
||
MenuErrCode menu_param_get_value(uint16_t param_id, float* value);
|
||
#endif // MENU_CONFIG_ENABLE_PARAM
|
||
|
||
#if MENU_CONFIG_ENABLE_LANG
|
||
/**
|
||
* @brief 设置当前语言
|
||
* @param lang_id 语言ID（如0-中文，1-英文）
|
||
* @return 错误码
|
||
*/
|
||
MenuErrCode menu_lang_set_current(uint8_t lang_id);
|
||
|
||
/**
|
||
* @brief 获取当前语言
|
||
* @param lang_id 输出参数，当前语言ID
|
||
* @return 错误码
|
||
*/
|
||
MenuErrCode menu_lang_get_current(uint8_t* lang_id);
|
||
#endif // MENU_CONFIG_ENABLE_LANG
|
||
|
||
#endif // MENU_H
|