主菜单¶
1. 介绍¶
主菜单作为系统的核心应用入口，承担着聚合所有应用、提供直观交互的功能。其支持多样化APP图标风格自定义、灵活配置应用显示顺序，并可实现多类型主菜单的动态切换，适配不同用户交互习惯与设备场景需求。
2. 图标风格管理¶
主菜单默认提供两种图标风格，并支持灵活扩展新风格，满足个性化视觉设计需求。
2.1 默认图标风格¶
方案预置两种图标资源风格，可直接调用使用：
Style 1：圆形图标风格
Style 2：方形图标风格
两种风格的图标分别对应资源目录与代码配置，在应用注册时自动关联适配。
2.2 新增图标风格¶
若需扩展自定义图标风格（如圆角矩形、异形图标等），按以下步骤操作：
步骤1：添加风格资源¶
在资源目录 \resource\images\ 下创建新的风格资源文件夹，命名格式为 mainmenuX（X 为风格序号，如 mainmenu3 对应 Style 3），并将该风格的所有APP图标资源放入此文件夹。
步骤2：配置风格索引¶
在代码根目录 \solution\framework\gui_fwk\reg_fwk\app_reg.c 中，添加新风格的类型索引，确保框架可识别并加载该风格资源。
步骤3：更新注册接口¶
在主菜单应用注册宏 APPLICATION_REGISTER 中，新增自定义风格的注册逻辑，关联风格索引与对应资源：
#define APPLICATION_REGISTER(key_str, img, app_name, ptr_size) \
APP_PAGE_REGISTER(app_name, "root", ptr_size); \
APPLICATION_MAIN(app_name, ptr_size); \
BUILTIN_APP_EXPORT(key_str, APP_GET_IMG_FROM_APP(mainmenu, img), app_name, app_main, 1); \
BUILTIN_APP_EXPORT(key_str, APP_GET_IMG_FROM_APP(CONCAT_2(mainmenu, 2), CONCAT_2(img, 2)), app_name, app_main, 2); \
BUILTIN_APP_EXPORT(key_str, APP_GET_IMG_FROM_APP(CONCAT_2(mainmenu, 3), CONCAT_2(img, 3)), app_name, app_main, 3); \
// 可继续添加 Style 4、Style 5 等自定义风格注册
示例中 mainmenu3 对应新风格目录，img3 对应该风格下的 APP 图标资源，3 为新风格索引。
3. 自定义主菜单¶
主菜单支持通过标准化接口注册自定义类型（如列表式、网格式等），实现个性化交互布局。
3.1 注册接口¶
自定义主菜单通过 APP_MAINMENU_REGISTER 宏注册至框架，该宏统一管理主菜单的标识、显示及消息处理逻辑：
APP_MAINMENU_REGISTER(id, name, icon, callback)
参数说明：
参数名 |
类型 |
功能描述 |
|---|---|---|
|
字符串 |
主菜单唯一标识，框架通过该 ID 识别并调度菜单，需保证全局唯一性 |
|
多语言字符串 |
主菜单显示名称，用于设置页面的菜单选择项（如通过 |
|
图片指针 |
主菜单图标，用于设置页面中标识该菜单类型 |
|
函数指针 |
消息处理回调函数，响应菜单生命周期事件（启动、恢复、暂停、停止） |
3.2 开发示例：列表式主菜单¶
以下为创建列表式（List）主菜单的完整实现示例：
步骤 1：实现菜单生命周期函数： 定义菜单启动、恢复、暂停、停止等状态的处理逻辑
// 声明全局变量（按需定义，存储菜单页面资源）
static lv_obj_t *list_menu_parent = NULL;
/**
* 菜单启动回调（仅调用一次）
* 功能：初始化页面容器，申请基础资源
*/
static void on_start(void)
{
// 创建菜单背景容器
list_menu_parent = lv_obj_create(lv_scr_act());
lv_obj_set_size(list_menu_parent, LV_HOR_RES_MAX, LV_VER_RES_MAX);
lv_obj_set_style_bg_color(list_menu_parent, LV_COLOR_WHITE, LV_PART_MAIN);
lv_obj_clear_flag(list_menu_parent, LV_OBJ_FLAG_SCROLLABLE);
}
/**
* 菜单恢复回调（每次显示时调用）
* 功能：加载APP图标列表，刷新显示内容
*/
static void on_resume(void)
{
// 此处可调用图标加载接口（如 builtin_app_read_all）加载APP列表并渲染
}
/**
* 菜单暂停回调（被切换至后台时调用）
* 功能：暂停动态交互，保存临时状态
*/
static void on_pause(void)
{
// 暂停列表滑动、动画等资源消耗操作
}
/**
* 菜单停止回调（退出时调用）
* 功能：释放资源，清理全局指针
*/
static void on_stop(void)
{
list_menu_parent = NULL;
}
步骤 2：实现消息处理回调： 统一处理菜单生命周期消息，关联对应状态的处理函数
static void msg_handler(gui_app_msg_type_t msg, void *param)
{
switch (msg)
{
case GUI_APP_MSG_ONSTART:
on_start();
break;
case GUI_APP_MSG_ONRESUME:
on_resume();
break;
case GUI_APP_MSG_ONPAUSE:
on_pause();
break;
case GUI_APP_MSG_ONSTOP:
on_stop();
break;
default:
break;
}
}
步骤 3：注册自定义主菜单： 通过宏将列表式菜单注册至系统
// 注册列表式主菜单（ID：List，名称：List，图标：img_menu_list，消息处理：msg_handler）
APP_MAINMENU_REGISTER(List, app_get_strid(key_mainmenu_list, "List"), img_menu_list, msg_handler);
4. APP 图标排序配置¶
主菜单支持通过排序表自定义 APP 的显示顺序，满足用户对高频应用的快捷访问需求。
4.1 排序接口¶
void builtin_app_read_all(builtin_app_read_app_cb cb, app_list_sort_t *sort_tab, uint16_t size, uint16_t style, void *user_data)
参数说明
参数名 |
类型 |
功能描述 |
|---|---|---|
|
函数指针 |
APP 读取回调函数，每加载一个 APP 会触发该回调 |
|
排序表指针 |
存储 APP 排序顺序的数组，按数组索引从小到大排列（NULL 表示使用默认顺序） |
|
无符号整数 |
排序表中 APP 的数量 |
|
无符号整数 |
加载的图标风格索引（如 1 对应 Style 1，2 对应 Style 2） |
|
通用指针 |
私有数据，可传递给回调函数用于上下文管理 |
4.2. 排序实现示例¶
例如在list菜单中调整APP的排序顺序，可在调用builtin_app_read_all前构造一个排序表，并传递给该接口函数。
呈现结果如下图所示
5. 主菜单切换¶
主菜单框架应用管理所有主菜单，动过加载或切换不同主菜单，实现不是的主菜单视图。
主菜单框架注册了一个"main"的主菜单应用。该应用读取当前设定的菜单ID，决定加载或切换到对应的菜单。
可调用app_menu_current_regist接口函数，设定当前需要激活的主菜单。
切换前需确保目标主菜单已通过 APP_MAINMENU_REGISTER 完成注册。
rt_err_t app_menu_current_regist(const char *id)
参数说明：
id 需要激活的主菜单ID号
6. 注意事项¶
资源唯一性：主菜单 ID、图标风格索引需保证全局唯一，避免冲突导致加载异常；
多语言适配：菜单显示名称需使用 app_get_strid 等多语言接口，避免硬编码文本；
风格一致性：新增图标风格时，需保证同风格下所有 APP 图标的尺寸、圆角、配色统一，提升视觉体验。