跳转至
项目
版本
全文检索

ui_analog_clock

ui_analog_clock 模块提供模拟时钟组件，支持表盘绘制与时针/分针/秒针动画显示。

Class Summary

OHOS::UIAnalogClock

提供模拟时钟相关功能，支持设置指针图像/线条、获取指针属性、设置初始时间及工作模式

  • 构造：无

  • 成员函数：

    接口名称 功能简述
    GetViewType 获取视图类型
    SetHandImage 设置指针绘制使用的图像
    SetHandLine 设置指针绘制使用的线条参数
    GetHandRotateCenter 获取指定指针的旋转中心
    GetHandPosition 获取指定指针的位置
    GetHandInitAngle 获取指定指针的初始旋转角度
    GetHandCurrentAngle 获取指定指针的当前旋转角度
    SetInitTime24Hour 以24小时制设置初始时间
    SetInitTime12Hour 以12小时制设置初始时间
    OnDraw 绘制模拟时钟
    OnPostDraw 执行绘制后操作
    SetWorkMode 设置工作模式
    GetWorkMode 获取当前工作模式
    UpdateClock 更新时钟时间

  • 使用包含头文件：#include "components/ui_analog_clock.h"

  • 声明头文件：middleware/services/gui/uikit/ui/interfaces/kits/components/ui_analog_clock.h
  • 公有运算符：无
  • 继承关系：UIAbstractClock
  • 嵌套类型：Hand、enum class HandType、enum class DrawType
  • 模板形参：无

OHOS::UIAnalogClock::Hand

定义模拟时钟指针的基本属性

  • 构造：无
  • 成员函数：无
  • 使用包含头文件：#include "components/ui_analog_clock.h"
  • 声明头文件：middleware/services/gui/uikit/ui/interfaces/kits/components/ui_analog_clock.h
  • 公有运算符：无
  • 继承关系：HeapBase
  • 嵌套类型：无
  • 模板形参：无

Functions

OHOS::UIAnalogClock

GetViewType

UIViewType GetViewType() const override

功能说明

  • 核心用途：获取当前视图的类型标识
  • 返回值为 UI_ANALOG_CLOCK，用于区分其他视图类型
  • 该函数为 const 成员函数，不修改对象状态

返回值

  • 返回类型：UIViewType

返回当前视图类型

返回值 触发场景
UI_ANALOG_CLOCK(11) 当前对象为模拟时钟视图

SetHandImage

void SetHandImage(HandType type, const UIImageView& img, Point position, Point center)

功能说明

  • 核心用途：设置指定类型指针的绘制图像
  • 通过图像方式绘制时钟指针，需同时指定图像起始位置和旋转中心
  • 设置后指针将使用图像进行绘制

入参

名称 参数类型 详细说明 约束取值范围
type HandType 指针类型 HOUR_HAND / MINUTE_HAND / SECOND_HAND
img const UIImageView& 入参只读引用，指针使用的图像 已完成图像资源加载的 UIImageView 对象
position Point 图像起始位置坐标 x: int16_t, y: int16_t
center Point 指针旋转中心坐标 x: int16_t, y: int16_t

SetHandLine

void SetHandLine(HandType type, Point position, Point center, ColorType color, uint16_t width, uint16_t height, OpacityType opacity)

功能说明

  • 核心用途：设置指定类型指针的线条绘制参数
  • 通过线条方式绘制时钟指针，可指定颜色、宽度、高度和透明度
  • 宽度和高度表示指针在12点方向时的尺寸

入参

名称 参数类型 详细说明 约束取值范围
type HandType 指针类型 HOUR_HAND / MINUTE_HAND / SECOND_HAND
position Point 线条靠近旋转中心端点的位置 x: int16_t, y: int16_t
center Point 旋转中心坐标 x: int16_t, y: int16_t
color ColorType 线条颜色 Color16 或 Color32，由 COLOR_DEPTH 宏决定
width uint16_t 12点方向时线条宽度 0 ~ 65535
height uint16_t 12点方向时线条高度 0 ~ 65535
opacity OpacityType 线条透明度 0(透明) ~ 255(不透明)

GetHandRotateCenter

Point GetHandRotateCenter(HandType type) const

功能说明

  • 核心用途：获取指定类型指针的旋转中心坐标
  • 该函数为 const 成员函数，不修改对象状态
  • 返回的坐标点为指针旋转的中心位置

入参

名称 参数类型 详细说明 约束取值范围
type HandType 指针类型 HOUR_HAND / MINUTE_HAND / SECOND_HAND

返回值

  • 返回类型：Point

返回指定指针的旋转中心

返回值 触发场景
Point{x, y} 正常返回旋转中心坐标

GetHandPosition

Point GetHandPosition(HandType type) const

功能说明

  • 核心用途：获取指定类型指针的位置坐标
  • 该函数为 const 成员函数，不修改对象状态
  • 返回的坐标点为指针在时钟上的位置

入参

名称 参数类型 详细说明 约束取值范围
type HandType 指针类型 HOUR_HAND / MINUTE_HAND / SECOND_HAND

返回值

  • 返回类型：Point

返回指定指针的位置

返回值 触发场景
Point{x, y} 正常返回指针位置坐标

GetHandInitAngle

uint16_t GetHandInitAngle(HandType type) const

功能说明

  • 核心用途：获取指定类型指针的初始旋转角度
  • 默认值为0，表示指针方向垂直向上
  • 该函数为 const 成员函数，不修改对象状态

入参

名称 参数类型 详细说明 约束取值范围
type HandType 指针类型 HOUR_HAND / MINUTE_HAND / SECOND_HAND

返回值

  • 返回类型：uint16_t

返回指定指针的初始旋转角度

返回值 触发场景
0 指针方向垂直向上（默认值）
其他值 指针初始旋转角度

GetHandCurrentAngle

uint16_t GetHandCurrentAngle(HandType type) const

功能说明

  • 核心用途：获取指定类型指针的当前旋转角度
  • 该角度随时间更新而变化
  • 该函数为 const 成员函数，不修改对象状态

入参

名称 参数类型 详细说明 约束取值范围
type HandType 指针类型 HOUR_HAND / MINUTE_HAND / SECOND_HAND

返回值

  • 返回类型：uint16_t

返回指定指针的当前旋转角度

返回值 触发场景
0 ~ 360 当前旋转角度值

SetInitTime24Hour

void SetInitTime24Hour(uint8_t hour, uint8_t minute, uint8_t second)

功能说明

  • 核心用途：以24小时制设置模拟时钟的初始时间
  • 设置后时钟指针将根据设置的时间定位到对应角度
  • 时间参数经取模运算后生效

入参

名称 参数类型 详细说明 约束取值范围
hour uint8_t 小时 0 ~ 23（取模后）
minute uint8_t 分钟 0 ~ 59（取模后）
second uint8_t 秒 0 ~ 59（取模后）

SetInitTime12Hour

void SetInitTime12Hour(uint8_t hour, uint8_t minute, uint8_t second, bool am)

功能说明

  • 核心用途：以12小时制设置模拟时钟的初始时间
  • 需额外指定上午/下午标识
  • 设置后时钟指针将根据设置的时间定位到对应角度

入参

名称 参数类型 详细说明 约束取值范围
hour uint8_t 小时 0 ~ 11（取模后）
minute uint8_t 分钟 0 ~ 59（取模后）
second uint8_t 秒 0 ~ 59（取模后）
am bool 上午/下午标识 true: 上午; false: 下午

OnDraw

void OnDraw(BufferInfo& gfxDstBuffer, const Rect& invalidatedArea) override

功能说明

  • 核心用途：绘制模拟时钟到指定图形缓冲区
  • 入参引用 gfxDstBuffer 由调用方提供图形缓冲区，函数将绘制内容写入该缓冲区
  • 仅在无效区域内进行绘制

入参

名称 参数类型 详细说明 约束取值范围
gfxDstBuffer BufferInfo& 入参引用，目标图形缓冲区 已完成初始化的 BufferInfo 对象
invalidatedArea const Rect& 入参只读引用，需要绘制的无效区域 有效的矩形区域

OnPostDraw

void OnPostDraw(BufferInfo& gfxDstBuffer, const Rect& invalidatedArea) override

功能说明

  • 核心用途：执行模拟时钟绘制后的操作
  • 入参引用 gfxDstBuffer 由调用方提供图形缓冲区
  • 在 OnDraw 之后调用，用于绘制后处理

入参

名称 参数类型 详细说明 约束取值范围
gfxDstBuffer BufferInfo& 入参引用，目标图形缓冲区 已完成初始化的 BufferInfo 对象
invalidatedArea const Rect& 入参只读引用，需要绘制的区域 有效的矩形区域

SetWorkMode

virtual void SetWorkMode(WorkMode newMode) override

功能说明

  • 核心用途：设置模拟时钟的工作模式
  • 工作模式决定时钟是否随时间变化更新绘制
  • 该函数为虚函数，支持子类重写

入参

名称 参数类型 详细说明 约束取值范围
newMode WorkMode 工作模式 ALWAYS_ON / NORMAL

GetWorkMode

virtual WorkMode GetWorkMode() const override

功能说明

  • 核心用途：获取模拟时钟的当前工作模式
  • 该函数为 const 虚函数，不修改对象状态，支持子类重写
  • 返回值反映时钟当前的绘制更新策略

返回值

  • 返回类型：WorkMode

返回当前工作模式

返回值 触发场景
ALWAYS_ON(0) 常亮模式，不随时间变化更新绘制
NORMAL(1) 正常模式，随时间变化更新绘制

UpdateClock

virtual void UpdateClock(bool clockInit) override

功能说明

  • 核心用途：更新模拟时钟的时间显示
  • 参数 clockInit 标识是否为首次初始化更新
  • 该函数为虚函数，支持子类重写

入参

名称 参数类型 详细说明 约束取值范围
clockInit bool 是否为首次初始化 true: 首次初始化; false: 非首次更新

Enumerations

UIAnalogClock::HandType 

enum class HandType {
    HOUR_HAND,
    MINUTE_HAND,
    SECOND_HAND,
};
枚举成员 取值 描述
HOUR_HAND 0 时针
MINUTE_HAND 1 分针
SECOND_HAND 2 秒针

UIAnalogClock::DrawType 

enum class DrawType {
    DRAW_LINE,
    DRAW_IMAGE,
};
枚举成员 取值 描述
DRAW_LINE 0 使用线条绘制指针
DRAW_IMAGE 1 使用图像绘制指针

Structures

OHOS::UIAnalogClock::Hand 

class Hand : public HeapBase {
public:
    Hand()
        : center_{0, 0},
          initAngle_(0),
          preAngle_(0),
          nextAngle_(0),
          position_{0, 0},
          imageInfo_{{0, 0, 0}},
          color_{{0, 0, 0}},
          width_(0),
          height_(0),
          opacity_(0),
          drawtype_(DrawType::DRAW_IMAGE)
    {
    }
    virtual ~Hand() {}
    Point center_;
    uint16_t initAngle_;
    uint16_t preAngle_;
    uint16_t nextAngle_;
    Point position_;
    ImageInfo imageInfo_;
    TransformMap trans_;
    Rect target_;
    ColorType color_;
    uint16_t width_;
    uint16_t height_;
    OpacityType opacity_;
    DrawType drawtype_;
    Image image_;
};

成员说明

成员名称 数据类型 描述
center_ Point 指针旋转中心，x/y 为 int16_t
initAngle_ uint16_t 指针初始顺时针旋转角度，默认 0 表示垂直向上
preAngle_ uint16_t 指针最近一次旋转角度
nextAngle_ uint16_t 指针下一次旋转角度
position_ Point 指针在时钟上的位置
imageInfo_ ImageInfo 指针图像信息
trans_ TransformMap 指针旋转与平移变换信息
target_ Rect 旋转平移后的新矩形区域
color_ ColorType 指针颜色
width_ uint16_t 指针宽度
height_ uint16_t 指针高度
opacity_ OpacityType 指针透明度，0(透明) ~ 255(不透明)
drawtype_ DrawType 指针绘制类型，DRAW_LINE 或 DRAW_IMAGE
image_ Image 指针对应的图像对象