应用设置项以及注册¶
1. 介绍¶
应用设置项是与特定应用绑定的配置入口，仅当对应应用存在时，设置项才会被注册并显示在系统设置菜单列表中。用户可通过点击设置项触发回调逻辑，实现应用配置页面的跳转与参数调整，是智能设备中应用个性化配置的核心交互载体。
2. 注册设置项¶
通过 SETTING_REGISTER 宏完成设置项注册，该宏统一管理设置项的标识、排序、显示及交互逻辑，语法如下：
SETTING_REGISTER(id, priority, name, thumb_img, callback)
参数说明:
参数名 |
类型 |
功能描述 |
|---|---|---|
|
字符串 |
设置菜单唯一标识 ID，框架通过该 ID 识别设置项，需保证全局唯一性 |
|
无符号整数 |
设置项显示优先级，数值越小优先级越高，在设置菜单中排列越靠前 |
|
多语言字符串 |
设置项显示名称，用于菜单界面展示，支持多语言切换（如通过 |
|
图片指针 |
设置项图标，用于菜单界面可视化展示，可通过 |
|
函数指针 |
点击回调函数，触发设置项对应的页面跳转或逻辑处理 |
3. 结构体说明¶
设置项的元数据与运行时状态通过以下两个结构体管理，分别对应注册描述与节点实例：
运行时节点结构体（setting_node_t） 用于存储设置项的运行时状态，由框架动态维护：
typedef struct
{
char id[MAX_SETTING_NAME_LEN]; /**< 设置菜单id名称 */
char *title; /**< 设置项名字,字符串,框架调度该设置项时使用 */
uint32_t prio; /**< 设置菜单优先级，值越小，优先级越高 */
const void *thumbnail; /**< 设置菜单缩略图 */
setting_cb_t cb; /**< 回调函数，点击菜单后页面跳转逻辑处理回调 */
void *mod; /**< 动态模块指针 */
void *mem_ptr; /**< setting菜单全局指针 */
void *user_data; /**< setting菜单user data */
rt_list_t list; /**< 链表 */
setting_built_type_t built_type; /**< 设置菜单类型, 动态菜单还是内置菜单 */
} setting_node_t;
注册描述结构体（setting_desc_t） 用于定义设置项的静态注册信息，作为注册时的参数载体：
typedef struct
{
const char *id_str; /**< 设置菜单id名称 */
const uint32_t prio; /**< 设置菜单优先级，值越小，优先级越高 */
setting_cb_t cb; /**< 回调函数，点击菜单后页面跳转逻辑处理回调 */
const void *thumbnail; /**< 设置菜单缩略图 */
uint32_t title; /**< 设置项名字,字符串,框架调度该设置项时使用 */
} setting_desc_t;
4.注册与开发流程¶
设置项的完整开发流程包含页面实现、回调绑定、设置项注册三个核心步骤，具体如下：
4.1 实现设置项对应的配置页面¶
配置页面需遵循应用页面生命周期规范，实现 on_start/on_resume/on_pause/on_stop 函数，完成页面创建、数据初始化、资源释放等逻辑：
// 定义设置项页面数据结构
typedef struct {
lv_obj_t *bg_parent; // 页面背景容器
lv_obj_t *slide_page; // 滑动列表页面（示例控件）
} aod_setting_t;
static aod_setting_t *p_aod_setting = NULL; // 全局页面指针
static app_aod_t *p_aod = NULL; // 应用核心数据指针
/**
* 页面初始化（仅调用一次）
* 功能：创建页面背景容器，申请基础资源
*/
static void on_start(void)
{
// 获取框架分配的全局内存
p_aod_setting = (aod_setting_t *)APP_GET_PAGE_MEM_PTR;
RT_ASSERT(p_aod_setting); // 校验内存分配有效性
// 创建全屏背景容器
lv_obj_t *bg_parent = lv_obj_create(lv_scr_act());
lv_obj_set_size(bg_parent, LV_HOR_RES_MAX, LV_VER_RES_MAX);
lv_obj_set_style_bg_color(bg_parent, LV_COLOR_BLACK, LV_PART_MAIN);
lv_obj_clear_flag(bg_parent, LV_OBJ_FLAG_SCROLLABLE);
lv_obj_center(bg_parent);
lv_obj_update_layout(bg_parent);
p_aod_setting->bg_parent = bg_parent;
}
/**
* 页面激活（每次显示时调用）
* 功能：创建交互控件，刷新页面数据
*/
static void on_resume(void)
{
// 获取应用核心数据（如AOD功能配置）
p_aod = aod_info_get();
// 创建具体配置控件（示例：AOD开关页面）
aod_setting_create_onoff_page(p_aod_setting->bg_parent);
}
/**
* 页面暂停（被切换至后台时调用）
* 功能：暂停动态控件（如滑动列表），保存临时状态
*/
static void on_pause(void)
{
if (p_aod_setting->slide_page) {
lv_multlist_on_pause(p_aod_setting->slide_page); // 暂停滑动列表交互
}
}
/**
* 页面销毁（退出时调用）
* 功能：释放全局指针，避免悬空引用
*/
static void on_stop(void)
{
p_aod_setting = NULL;
}
// 注册设置项对应的配置页面（绑定至"setting"应用下的"aod"子页面）
APP_PAGE_REGISTER("setting", "aod", sizeof(aod_setting_t));
4.2 实现设置项点击回调函数¶
回调函数用于响应菜单点击事件，实现从设置菜单到配置页面的跳转：
/**
* AOD设置项点击回调
* param：用户自定义参数（可选）
* 返回值：0表示成功，非0表示失败
*/
static int aod_setting_cb(void *param)
{
// 跳转至"setting"应用下的"aod"配置页面
gui_app_run_subpage("setting", "aod", NULL);
return 0;
}
4.2 注册设置项至系统菜单¶
通过 SETTING_REGISTER 宏将设置项添加到系统设置菜单，完成最终注册：
// 注册AOD设置项至系统菜单
SETTING_REGISTER(
aod_setting, // 设置项唯一ID
1, // 优先级（1级，显示靠前）
app_get_strid(key_aod_setting, "Aod setting"), // 多语言显示名称
APP_GET_IMG_FROM_APP(setting, img_screen_always_on), // 设置项图标
aod_setting_cb // 点击回调函数
);
5. 注意事项¶
唯一性保证： id 参数需保证全局唯一，避免与其他设置项冲突导致框架调度异常。
内存管理： 配置页面的全局内存由框架通过 APP_GET_PAGE_MEM_PTR 分配，其大小需与 APP_PAGE_REGISTER 中指定的 sizeof(页面结构体) 一致。
优先级设计： 核心配置项（如 “显示设置”）建议设置较低优先级数值（如 1-5），次要配置项可设置较高数值（如 10+），确保菜单排序符合用户预期。
多语言支持： name 参数需使用多语言接口（如 app_get_strid），避免硬编码字符串导致多语言适配问题。
资源清理： on_stop 函数中需将全局指针置空，避免内存泄漏；页面控件无需手动删除，框架会自动清理。