表盘（WF)¶

本文说明表盘功能的配置、资源组织和应用接入方式。

1. 参考代码¶

文件	作用
`solution\framework\gui_fwk\wf_fwk\wf_fwk.c`	管理表盘页面生命周期和事件分发
`solution\framework\gui_fwk\reg_fwk\wf_reg.c`	注册表盘入口和资源信息
`solution\framework\gui_fwk\dyn_fwk\watchface\dynamic_watchface.c`	加载和运行动态表盘资源

2. 应用例程¶

场景	文件	调用接口
跟随表盘页面	`app_wf_follow.c`	`app_icon_event_handler()`、`service_current_time_get()`
表盘编辑页面	`wf_edit_gui.c`	`wf_edit_list_init()`、`wf_edit_create_tile()`
表盘编辑业务处理	`wf_edit_proc.c`	`wf_set_last_id()`、`wf_list_get()`、`wf_list_reorder()`

3. 简介¶

表盘是挂载在平铺应用上的子应用，由wf_fwk框架进行管理，作为智能穿戴设备（如手表）的核心主界面，用于展示时间、日期及个性化信息（如步数、天气等），支持静态或动态样式，可通过内置或外置方式更换。

表盘功能通过APP_WF_USED使能，准确配置路径为：menuconfig (Top) → Gui Framework Config → Tileview Config → Enanle tileview style (APP_TLV_USED) → WF Config → Enable watchface manager (APP_WF_USED)。WF Config 依赖 APP_TLV_USED，因此必须先启用平铺框架；APP_WF_USED 本身无额外直接 depends on，默认关闭。Gui Framework Config 仅由 HCPU 与 PC Simulator 配置树引入，LCPU 工程不显示该项。
支持多种开发方式：可选择 C 语言、QJS（Quick JavaScript）以及 SiFli GUI Builder 来实现表盘。
启用 APP_WF_USED 后，Solution 框架将提供自动注册以及调度机制。APP_WF_USED 是 Kconfig 配置符号，由构建系统生成对应配置宏，不应在源码或配置头中手工定义：
- 内置表盘在编译阶段自动关联至专属代码段，系统启动后框架可直接识别并加载
- 外置表盘则通过框架的动态管理能力实现自动适配。
- 外置表盘支持完整的装入和卸载流程，从资源分配到状态同步均由框架封装处理，用户无需关心底层的注册逻辑、生命周期调度及资源清理细节，能够很容易地进行表盘的开发、扩展与更新。

4. C注册内置表盘¶

4.1 注册宏定义¶

使用WF_REGISTER宏来注册内置表盘，语法如下：

WF_REGISTER(priority, id, name, thumb_img, ptr_size)

参数说明：

priority：表盘优先级，表盘在选择界面中按优先级从高（数值小）到低排列。内置表盘的顺序可动态调整，修改管理链表（通过wf_list_get()获取）中的优先级即可。
id：表盘名字，为字符串类型，框架调度该应用时使用，需要保证唯一性。
name：表盘显示标题，为多语言字符串，仅作显示用。
thumb_img：表盘缩略图，在表盘编辑等场景时使用。
ptr_size：表盘全局内存大小，该内存由框架申请和释放，页面可直接使用，通过WF_GET_NODE_MEM_PTR宏来获取。
ops（隐式）：on_init/on_pause/on_resume/on_deinit

4.2 帧率相关的注意事项¶

对于 NOR Flash 方案，为了提高表盘指针渲染效率，需要把指针放入缓存中，使用app_cache_copy_alloc对指针图片进行缓存操作，需要注意缓存空间分PSRAM/SRAM，SRAM足够的条件下可以将秒针放入SRAM（CACHE_SRAM），其他旋转速度慢的直接放入PSRAM（CACHE_PSRAM）即可
对于 NAND Flash 方案，图片资源已经在 PSRAM 上，无需再重复缓存，仅在 SRAM 足够的条件下，缓存秒针即可。
指针动画功能可通过clock_pointer_anim_create函数开启，开启后激活表盘时，指针可以从之前的位置通过一个动画旋转到当前时刻。

4.3 状态机相关¶

由于表盘是平铺应用的一个子应用，其状态机与平铺应用是一致的。

4.4 示例¶

以下是创建一个优先级为 3 的simple表盘的示例代码：

// 定义表盘相关结构体
typedef struct {
    // 表盘相关成员变量
} clock_simple_t;
static clock_simple_t *p_clk_simple = NULL;

// 初始化函数
static rt_int32_t on_init(void *param)
{
    p_clk_simple = (clock_simple_t *) WF_GET_NODE_MEM_PTR();
    RT_ASSERT(p_clk_simple);
    // 初始化表盘相关资源等操作
    ...
    return RT_EOK;
}

// 暂停函数
static rt_int32_t on_pause(void *param)
{
    // 暂停相关操作
    ...
    return RT_EOK;
}

// 恢复函数
static rt_int32_t on_resume(void *param)
{
    // 恢复相关操作
    ...
    return RT_EOK;
}

// 反初始化函数
static rt_int32_t on_deinit(void *param)
{
    // 释放资源等操作
    ...
    p_clk_simple = NULL;
    return RT_EOK;
}

// 注册内置表盘
BUILTIN_WF_REGISTER(3, wf_simple, app_get_strid(key_clk_simple, "Simple"), thum, 0);

具体例程可以参见solution\examples\watch\application\watchface\wf_follow。

5. C注册外置表盘¶

C 外置表盘通过APP_DLMODULE_WF_USED使能，路径为：menuconfig (Top) → Gui Framework Config → Dynamic_app config → Enable dynamic watchface (APP_DLMODULE_WF_USED)。该选项默认开启，但始终依赖 RT_USING_DFS 与 APP_WF_USED，并且还要求 RT_USING_MODULE 或 PC Simulator；PC Simulator 仅替代模块加载条件，仍必须启用文件系统和表盘框架。

5.1 注册流程¶

在外置表盘应用源码首行定义 DYN_WF，声明此表盘的资源通过外置方式获取。DYN_WF 是应用源码宏，不是 menuconfig 配置项；它不能替代 APP_DLMODULE_WF_USED：

    #define DYN_WF

注册宏定义外置表盘的注册宏和内置表盘是一样的。

WF_REGISTER(priority, id, name, thumb_img, ptr_size)

5.2 示例¶

//外置表盘，资源通过外置方式获取
#define DYN_WF
#include "global.h"

#define _MODULE_NAME_   "wf_simple" /*外置表盘在模拟器中使用时需要定义`_MODULE_NAME_`，值必须和外置表盘APP_ID相同*/
#include "app_module.h"             /*资源使用接口的头文件包含*/

// 定义表盘相关结构体（假设）
typedef struct {
    // 表盘相关成员变量
} clock_simple_t;
static clock_simple_t *p_clk_simple = NULL;

// 初始化函数
static rt_int32_t on_init(void *param)
{
    // 初始化表盘相关资源等操作
    ...
    return RT_EOK;
}

// 暂停函数
static rt_int32_t on_pause(void *param)
{
    // 暂停相关操作
    ...
    return RT_EOK;
}

// 恢复函数
static rt_int32_t on_resume(void *param)
{
    // 恢复相关操作
    ...
    return RT_EOK;
}

// 反初始化函数
static rt_int32_t on_deinit(void *param)
{
    // 释放资源等操作
    ...
    return RT_EOK;
}

WF_REGISTER(3, "wf_simple", app_get_strid(key_clk_simple, "Simple"), thum, sizeof(clock_simple_t));

具体例程可以参见solution\examples\_dynamic_app\c\wf\wf_dog。

6. QJS外置表盘¶

QJS 外置表盘支持通过 JavaScript 快速开发扩展表盘。

QJS 外置表盘通过QUICKJS_LVGL使能，准确配置路径为：menuconfig (Top) → QuickJS && Micro-Python Config → Enable Quick JS (PKG_USING_QUICKJS) → QuickJS: Enable LVGL v7/v8 support (QUICKJS_LVGL)。QuickJS && Micro-Python Config 是 Solution 框架直接加入根菜单的入口，仅在 HCPU 或 PC Simulator 工程中显示。PKG_USING_QUICKJS 与 QUICKJS_LVGL 默认均为关闭；先启用前者，后者才会显示，且无额外直接 depends on。
客户可通过Quick JavaScript 编写Quick Java Script来编写外置表盘了解详细开发流程。

具体例程可以参见solution\examples\_dynamic_app\qjs\qjs_wf\JW_wf1。

7. SiFli GUI Builder外置表盘¶

SiFli GUI Builder 工具支持可视化开发外置表盘，提升开发效率。

SiFli GUI Builder 工具表盘通过APP_TOOL_SUPPORT使能，准确配置路径为：menuconfig (Top) → App_Tool Config → app tool support (APP_TOOL_SUPPORT)。App_Tool Config 是 Solution 框架直接加入根菜单的入口，仅在 HCPU 或 PC Simulator 工程中显示；APP_TOOL_SUPPORT 直接依赖 LV_USING_FREETYPE_ENGINE，两项默认均开启。
用户可通过SiFli GUI Builder 工具实现SiFli GUI Builder工具实现外置表盘了解详细操作步骤。

具体例程可以参见solution\examples\_dynamic_app\tool\tool_wf\pointer。