表盘¶

1. 简介¶

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

表盘功能通过 APP_WF_USED 使能，配置路径为：menuconfig (Top) → Development Config → Dynamic_app config。
支持多种开发方式：可选择 C 语言、QJS（Quick JavaScript）以及 SiFli GUI Builder 来实现表盘。
使能表盘相关的宏之后，Solution 框架将提供自动注册以及调度机制：
- 内置表盘在编译阶段自动关联至专属代码段，系统启动后框架可直接识别并加载
- 外置表盘则通过框架的动态管理能力实现自动适配。
- 外置表盘支持完整的装入和卸载流程，从资源分配到状态同步均由框架封装处理，用户无需关心底层的注册逻辑、生命周期调度及资源清理细节，能够很容易地进行表盘的开发、扩展与更新。

2. C注册内置表盘¶

2.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

2.2 帧率相关的注意事项¶

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

2.3 状态机相关¶

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

2.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_cool。

3. C注册外置表盘¶

C外置表盘通过 APP_DLMODULE_WF_USED使能（menuconfig (Top) → Development Config → Dynamic_app config）。

3.1 注册流程¶

代码第一行定义DYN_WF宏，申明此表盘是外置表盘，资源通过外置方式获取：

    #define DYN_WF

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

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

3.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。

3. QJS外置表盘¶

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

QJS 外置表盘通过 QUICKJS_LVGL 使能，配置路径为：menuconfig (Top) → SiFli SDK configuration → Third party packages → Enable Quick JS → QuickJS: Enable LVGL v7/v8 support。
客户可通过Quick JavaScript 编写Quick Java Script来编写外置表盘了解详细开发流程。

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

4. SiFli GUI Builder外置表盘¶

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

SiFli GUI Builder 工具表盘通过 APP_TOOL_SUPPORT 使能，配置路径为：menuconfig (Top) → App_Tool Config。
用户可通过SiFli GUI Builder 工具实现SiFli GUI Builder工具实现外置表盘了解详细操作步骤。

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