# cotMenu **Repository Path**: MagicBude/cot_menu ## Basic Information - **Project Name**: cotMenu - **Description**: 嵌入式设备常用的菜单框架模块组件代码(轻量级) - **Primary Language**: C - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 5 - **Forks**: 3 - **Created**: 2025-06-16 - **Last Updated**: 2026-11-13 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 轻量级菜单框架 本模块提供多级菜单管理、菜单项选择及回调调度。 原始项目:[大橙子疯的轻量级菜单框架](https://gitee.com/cot_package/cot_menu)。 ## 文件与职责 - `cot_menu.c/.h`:菜单层级管理、菜单项选择、回调调度及显示辅助接口。 - `language.c/.h`:中英文文本示例,提供文本 ID、系统语言设置和字符串查询。 - `LICENSE`:项目许可。 菜单框架维护当前菜单及父菜单链,菜单项以数组定义。显示回调负责绘制界面,可使用 LCD、OLED 或串口。 菜单描述联合体可保存字符串或文本 ID;文本 ID 通过语言模块转换为字符串。 ## 配置 配置位于 `cot_menu.h`,编译前统一设置: - `_COT_MENU_USE_MALLOC_`:定义时使用 `malloc/free`,否则使用静态控制器数组;默认不定义。 - `_COT_MENU_USE_SHORTCUT_`:定义时编译快捷导航实现;默认定义。 - `COT_MENU_MAX_DEPTH`:控制器层数上限,范围 1~255,默认 10,主菜单占用一层;静态和动态分配均受此限制。 - `COT_MENU_MAX_NUM`:每级菜单显示信息数组的容量,默认 20;范围为 1 至 UINT16_MAX 与 INT_MAX 的较小值。 调用者应提供非空菜单列表,每级项目数量不超过 `COT_MENU_MAX_NUM`,配置表及其引用的数据在使用期间保持有效。 `cotMenu_Bind` 保存列表指针,已有绑定不会被覆盖。 ## 初始化与任务调用 以下示例用字符串描述菜单,显示回调通过串口打印所选项。 示例中的 `printf` 输出需要由工程提供串口重定向。 ```c #include "cot_menu.h" #include static void ShowMainMenu(cotMenuShow_t *ptShowInfo); static void EnterMainMenu(const cotMenuItemInfo_t *pItemInfo); static cotMenuList_t sg_mainMenuList[] = { COT_MENU_ITEM_BIND("设置", NULL, NULL, NULL, NULL, NULL), COT_MENU_ITEM_BIND("信息", NULL, NULL, NULL, NULL, NULL), }; static cotMainMenuCfg_t sg_mainMenu = COT_MENU_ITEM_BIND("主菜单", EnterMainMenu, NULL, NULL, NULL, NULL); static void ShowMainMenu(cotMenuShow_t *ptShowInfo) { const char *pText = ptShowInfo->uItemsListDesc[ptShowInfo->selectItem].pTextString; printf("%s\n", pText); } static void EnterMainMenu(const cotMenuItemInfo_t *pItemInfo) { (void)pItemInfo; cotMenu_Bind(sg_mainMenuList, COT_GET_MENU_NUM(sg_mainMenuList), ShowMainMenu); } int menu_start(void) { if (cotMenu_Init(&sg_mainMenu) != 0) { return -1; } return cotMenu_MainEnter(); } ``` 启动后在主循环或任务中周期调用 `cotMenu_Task()`,将按键事件映射到下列操作: ```c /* 向前选择,允许首项循环到末项。 */ cotMenu_SelectPrevious(true); /* 向后选择,末项不循环。 */ cotMenu_SelectNext(false); /* 进入所选项。 */ cotMenu_Enter(); /* 返回父菜单,并将父菜单选择项复位到第一项。 */ cotMenu_Exit(true); ``` 每次按键事件只调用对应操作,并检查返回值。上述操作不应在一次按键事件中依次全部执行。 不再使用时调用 `cotMenu_DeInit()`。 ## 回调与子菜单 每个配置项可设置进入、退出、加载和周期运行回调,未使用的回调设为 `NULL`。 - 进入回调:进入该项时同步调用,子菜单可在此调用 `cotMenu_Bind` 绑定自己的列表及显示回调。 - 退出回调:返回父菜单时调用父菜单所选项的退出回调。 - 加载回调:进入菜单或从子菜单返回后,由后续 `cotMenu_Task` 调用一次。 - 运行回调:每次 `cotMenu_Task` 调用时执行,可用于当前菜单项的业务处理。 - 显示回调:当前菜单绑定列表后,由 `cotMenu_Task` 调用,接收菜单描述及菜单项显示信息。 子菜单配置方式与主菜单相同。新层级继承父菜单的显示回调;需要不同效果时,在绑定时传入自己的显示回调。 没有绑定列表的菜单项仍可通过周期运行回调处理业务,随后调用 `cotMenu_Exit` 返回。 菜单项信息和显示信息均为回调期间有效的临时对象,不能保存其指针供回调结束后使用。 主菜单退出回调收到的菜单项信息指针为 `NULL`。 显示回调调整的 `showBaseItem` 会保存至当前控制器;其他显示字段的修改不会写回。 ## 显示辅助与快捷导航 在显示回调中,可用 `cotMenu_LimitShowListNum(ptShowInfo, &showNum)` 调整显示窗口。 `showNum` 必须使用 `menusize_t` 类型,列表及期望显示项数应有效且非空。 从 `showBaseItem` 开始绘制调整后的 `showNum` 项即可。 启用快捷导航后,`cotMenu_ShortcutEnter(true, 2, 0, 1)` 表示先复位到主菜单,再处理索引 0、1。 索引从 0 开始,可变参数按 `int` 类型传入;各级进入回调需要绑定下一层列表。 使用 `false` 可从当前菜单开始。 ## 调用约束 调用时应满足以下条件: - 初始化不检查主菜单配置指针是否为空。进入和前后选择要求当前列表非空且索引有效。 - `cotMenu_Reset` 直接释放子菜单并复位主菜单选择项,不执行退出回调,保留主菜单显示起点;下一次任务执行主菜单加载回调(若已配置)。 - 快捷导航在索引无效或任一级进入失败时返回 -1;已发生的导航不回滚。 - `cotMenu_QueryParentMenu` 不检查输出指针,层数不足时可能已部分写入输出;层数为 0 时不写输出。 查询涉及的菜单描述、扩展数据及列表状态取自相应父菜单。 - `get_text_by_language` 不检查语言索引。语言及文本 ID 应来自有效枚举;文本 ID 大于等于上限时才返回 `"N/A"`。 不要将任意整数强转为枚举后传入查询接口。 - 菜单操作及回调在同一执行上下文中串行调用,不提供并发保护。 ## 验证范围 核心及语言模块已进行主机语法编译检查,覆盖静态/动态控制器分配与快捷导航开启/关闭的四种组合。这不代表菜单导航、回调时序、多语言输入边界或目标显示硬件已经通过运行验证。静态分配配置下存在 DeleteMenu 参数未使用的编译警告。 加载回调内可导航到其他层级,新产生的加载任务由下一次 cotMenu_Task 处理;回调不得重入任务或调用反初始化。容量配置超出计数类型范围时编译失败,合法容量仍须满足目标内存和栈空间限制。