跳转至
项目
版本
全文检索

ui_view

ui_view 模块提供视图基类，定义所有UI视图的基础属性与操作，包括布局、绘制、事件、焦点与变换等。

Class Summary

OHOS::UIView

视图基类，提供基础视图属性与操作，所有视图均派生自该类

Functions

OHOS::UIView

UIView

explicit UIView(const char* id)

功能说明

  • 带参数构造函数，根据指定的视图ID创建UIView实例
  • 构造时先调用默认构造函数完成基础初始化，再将id_成员设置为传入的ID
  • 视图ID可用于后续通过GetChildById等方法在视图树中查找该视图

入参

名称 参数类型 详细说明 约束取值范围
id const char* 视图ID字符串指针 非空字符串指针

OnPreDraw

virtual bool OnPreDraw(Rect& invalidatedArea) const

功能说明

  • 在视图绘制前调用，用于判断失效区域是否被当前视图完全覆盖
  • 如果完全覆盖则返回true，绘制引擎可跳过被遮挡的下层视图绘制以优化性能
  • 如果部分覆盖，函数会将invalidatedArea修改为实际被覆盖的区域

入参

名称 参数类型 详细说明 约束取值范围
invalidatedArea Rect& 待判断的失效区域，部分覆盖时返回实际覆盖区域 有效的Rect引用

返回值

  • 返回类型：bool

返回失效区域覆盖判断结果

返回值 触发场景
true(1) 失效区域被当前视图完全覆盖
false(0) 失效区域未被完全覆盖

OnDraw

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

功能说明

  • 视图绘制回调，在视图需要重绘时由绘制引擎调用
  • 子类应重写此方法实现自定义绘制逻辑
  • 绘制范围限制在invalidatedArea指定的失效区域内

入参

名称 参数类型 详细说明 约束取值范围
gfxDstBuffer BufferInfo& 图形目标缓冲区，绘制内容将输出到此缓冲区 有效的BufferInfo引用
invalidatedArea const Rect& 需要绘制的失效区域 有效的Rect引用

OnPostDraw

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

功能说明

  • 视图绘制后回调，在OnDraw执行完毕后由绘制引擎调用
  • 可用于在视图内容绘制完成后叠加额外效果（如前景装饰）
  • 子类可重写此方法实现后绘制逻辑

入参

名称 参数类型 详细说明 约束取值范围
gfxDstBuffer BufferInfo& 图形目标缓冲区 有效的BufferInfo引用
invalidatedArea const Rect& 绘制失效区域 有效的Rect引用

ReMeasure

virtual void ReMeasure()

功能说明

  • 重新测量视图尺寸，在视图尺寸需要更新时调用
  • 子类可重写此方法实现自定义测量逻辑
  • 默认实现为空函数，基类不做额外处理

Invalidate

void Invalidate()

功能说明

  • 刷新视图的整个失效区域，标记视图需要重绘
  • 调用后绘制引擎会在下一帧重绘该视图
  • 适用于视图内容发生变化的场景

InvalidateRect

void InvalidateRect(const Rect& invalidatedArea, UIView* view = nullptr)

功能说明

  • 刷新指定失效区域，仅标记指定矩形区域需要重绘
  • 相比Invalidate()更精细，可减少不必要的重绘范围以提升性能
  • 可选参数view指定关联视图，默认为nullptr表示当前视图自身

入参

名称 参数类型 详细说明 约束取值范围
invalidatedArea const Rect& 需要刷新的失效区域 有效的Rect引用
view UIView* 关联的视图指针，默认nullptr UIView指针或nullptr

OnLongPressEvent

virtual bool OnLongPressEvent(const LongPressEvent& event)

功能说明

  • 长按事件回调，当视图被长按时触发
  • 若事件被消费则不再向父视图传递，否则在本地处理完成后传递给父视图
  • 子类可重写此方法实现自定义长按响应逻辑

入参

名称 参数类型 详细说明 约束取值范围
event const LongPressEvent& 长按事件对象 有效的LongPressEvent引用

返回值

返回值 触发场景
true 长按事件被消费
false 长按事件未被消费

OnDragStartEvent

virtual bool OnDragStartEvent(const DragEvent& event)

功能说明

  • 拖拽开始事件回调，当视图开始被拖拽时触发
  • 若事件被消费则不再向父视图传递
  • 子类可重写此方法实现拖拽开始的自定义处理

入参

名称 参数类型 详细说明 约束取值范围
event const DragEvent& 拖拽事件对象 有效的DragEvent引用

返回值

返回值 触发场景
true 拖拽开始事件被消费
false 拖拽开始事件未被消费

OnDragEvent

virtual bool OnDragEvent(const DragEvent& event)

功能说明

  • 拖拽中事件回调，当视图正在被拖拽时持续触发
  • 若事件被消费则不再向父视图传递
  • 子类可重写此方法实现拖拽过程中的自定义处理

入参

名称 参数类型 详细说明 约束取值范围
event const DragEvent& 拖拽事件对象 有效的DragEvent引用

返回值

返回值 触发场景
true 拖拽事件被消费
false 拖拽事件未被消费

OnDragEndEvent

virtual bool OnDragEndEvent(const DragEvent& event)

功能说明

  • 拖拽结束事件回调，当视图停止拖拽时触发
  • 若事件被消费则不再向父视图传递
  • 子类可重写此方法实现拖拽结束的自定义处理

入参

名称 参数类型 详细说明 约束取值范围
event const DragEvent& 拖拽事件对象 有效的DragEvent引用

返回值

返回值 触发场景
true 拖拽结束事件被消费
false 拖拽结束事件未被消费

OnClickEvent

virtual bool OnClickEvent(const ClickEvent& event)

功能说明

  • 点击事件回调，当视图被点击时触发
  • 若事件被消费则不再向父视图传递
  • 子类可重写此方法实现自定义点击响应逻辑

入参

名称 参数类型 详细说明 约束取值范围
event const ClickEvent& 点击事件对象 有效的ClickEvent引用

返回值

返回值 触发场景
true 点击事件被消费
false 点击事件未被消费

OnPressEvent

virtual bool OnPressEvent(const PressEvent& event)

功能说明

  • 按下事件回调，当视图被按下时触发
  • 若事件被消费则不再向父视图传递
  • 子类可重写此方法实现按下状态的自定义处理

入参

名称 参数类型 详细说明 约束取值范围
event const PressEvent& 按下事件对象 有效的PressEvent引用

返回值

返回值 触发场景
true 按下事件被消费
false 按下事件未被消费

OnReleaseEvent

virtual bool OnReleaseEvent(const ReleaseEvent& event)

功能说明

  • 释放事件回调，当视图被释放时触发
  • 若事件被消费则不再向父视图传递
  • 子类可重写此方法实现释放状态的自定义处理

入参

名称 参数类型 详细说明 约束取值范围
event const ReleaseEvent& 释放事件对象 有效的ReleaseEvent引用

返回值

返回值 触发场景
true 释放事件被消费
false 释放事件未被消费

OnCancelEvent

virtual bool OnCancelEvent(const CancelEvent& event)

功能说明

  • 取消事件回调，当视图上的点击事件被取消时触发
  • 若事件被消费则不再向父视图传递
  • 子类可重写此方法实现事件取消的自定义处理

入参

名称 参数类型 详细说明 约束取值范围
event const CancelEvent& 取消事件对象 有效的CancelEvent引用

返回值

返回值 触发场景
true 取消事件被消费
false 取消事件未被消费

SetOnDragListener

void SetOnDragListener(OnDragListener* onDragListener)

功能说明

  • 设置拖拽事件监听器，用于监听视图的拖拽相关事件
  • 设置后当拖拽事件发生时将回调监听器中的对应方法
  • 传入nullptr可取消已设置的监听器

入参

名称 参数类型 详细说明 约束取值范围
onDragListener OnDragListener* 拖拽事件监听器指针 OnDragListener指针或nullptr

GetOnDragListener

OnDragListener*& GetOnDragListener()

功能说明

  • 获取已设置的拖拽事件监听器
  • 返回引用可允许直接修改监听器指针
  • 未设置时返回值为nullptr

返回值

返回值 触发场景
OnDragListener*& 已设置的拖拽事件监听器引用，未设置时为nullptr

SetOnClickListener

void SetOnClickListener(OnClickListener* onClickListener)

功能说明

  • 设置点击事件监听器，用于监听视图的点击事件
  • 设置后当点击事件发生时将回调监听器中的OnClick方法
  • 传入nullptr可取消已设置的监听器

入参

名称 参数类型 详细说明 约束取值范围
onClickListener OnClickListener* 点击事件监听器指针 OnClickListener指针或nullptr

GetOnClickListener

OnClickListener*& GetOnClickListener()

功能说明

  • 获取已设置的点击事件监听器
  • 返回引用可允许直接修改监听器指针
  • 未设置时返回值为nullptr

返回值

返回值 触发场景
OnClickListener*& 已设置的点击事件监听器引用，未设置时为nullptr

SetOnLongPressListener

void SetOnLongPressListener(OnLongPressListener* onLongPressListener)

功能说明

  • 设置长按事件监听器，用于监听视图的长按事件
  • 设置后当长按事件发生时将回调监听器中的OnLongPress方法
  • 传入nullptr可取消已设置的监听器

入参

名称 参数类型 详细说明 约束取值范围
onLongPressListener OnLongPressListener* 长按事件监听器指针 OnLongPressListener指针或nullptr

GetOnLongPressListener

OnLongPressListener*& GetOnLongPressListener()

功能说明

  • 获取已设置的长按事件监听器
  • 返回引用可允许直接修改监听器指针
  • 未设置时返回值为nullptr

返回值

返回值 触发场景
OnLongPressListener*& 已设置的长按事件监听器引用，未设置时为nullptr

SetOnTouchListener

void SetOnTouchListener(OnTouchListener* onTouchListener)

功能说明

  • 设置触摸事件监听器，用于监听视图的触摸相关事件（按下、释放、取消）
  • 设置后当对应触摸事件发生时将回调监听器中的方法
  • 传入nullptr可取消已设置的监听器

入参

名称 参数类型 详细说明 约束取值范围
onTouchListener OnTouchListener* 触摸事件监听器指针 OnTouchListener指针或nullptr

GetTouchListener

OnTouchListener*& GetTouchListener()

功能说明

  • 获取已设置的触摸事件监听器
  • 返回引用可允许直接修改监听器指针
  • 未设置时返回值为nullptr

返回值

返回值 触发场景
OnTouchListener*& 已设置的触摸事件监听器引用，未设置时为nullptr

GetTargetView

virtual void GetTargetView(const Point& point, UIView** last)

功能说明

  • 根据指定坐标获取包含该坐标的最顶层目标视图
  • 通过双指针参数返回查找到的视图
  • 用于事件分发时确定触摸事件的目标视图

入参

名称 参数类型 详细说明 约束取值范围
point const Point& 指定坐标点 有效的Point引用
last UIView** 输出参数，返回包含指定坐标的视图双指针 非空UIView双指针

GetTargetView

virtual void GetTargetView(const Point& point, UIView** current, UIView** target)

功能说明

  • 根据指定坐标同时获取当前视图和目标视图
  • 当前视图为包含指定坐标且可见、可响应触摸事件的最顶层视图
  • 目标视图为包含指定坐标的最顶层视图

入参

名称 参数类型 详细说明 约束取值范围
point const Point& 指定坐标点 有效的Point引用
current UIView** 输出参数，返回当前视图双指针 非空UIView双指针
target UIView** 输出参数，返回目标视图双指针 非空UIView双指针

SetParent

void SetParent(UIView* parent)

功能说明

  • 设置当前视图的父视图
  • 建立视图树中的父子层级关系
  • 通常由容器视图在添加子视图时内部调用

入参

名称 参数类型 详细说明 约束取值范围
parent UIView* 父视图指针 UIView指针或nullptr

GetParent

UIView* GetParent() const

功能说明

  • 获取当前视图的父视图
  • 用于遍历视图树或获取父视图信息
  • 无父视图时返回nullptr

返回值

返回值 触发场景
UIView* 父视图指针，无父视图时为nullptr

SetNextSibling

void SetNextSibling(UIView* sibling)

功能说明

  • 设置当前视图的下一个兄弟视图
  • 建立同一层级视图的链表关系
  • 通常由容器视图内部调用

入参

名称 参数类型 详细说明 约束取值范围
sibling UIView* 下一个兄弟视图指针 UIView指针或nullptr

GetNextSibling

UIView* GetNextSibling() const

功能说明

  • 获取当前视图的下一个兄弟视图
  • 用于遍历同一父视图下的兄弟视图链表
  • 无下一个兄弟视图时返回nullptr

返回值

返回值 触发场景
UIView* 下一个兄弟视图指针，无兄弟视图时为nullptr

SetVisible

virtual void SetVisible(bool visible)

功能说明

  • 设置视图是否可见，不可见的视图不会被绘制
  • 视图不可见时仍存在于视图树中，只是不参与绘制和事件响应
  • 子类可重写此方法添加额外的可见性处理逻辑

入参

名称 参数类型 详细说明 约束取值范围
visible bool 是否可见，true为可见，false为不可见 true/false

IsVisible

bool IsVisible() const

功能说明

  • 查询视图是否可见
  • 仅反映当前视图自身的可见性，不包含父视图的可见性
  • 即使当前视图可见，若父视图不可见则该视图实际不会显示

返回值

返回值 触发场景
true 视图可见
false 视图不可见

SetTouchable

void SetTouchable(bool touch)

功能说明

  • 设置视图是否可触摸，不可触摸的视图不响应触摸事件
  • 触摸事件将穿透不可触摸的视图传递给下层
  • 默认情况下视图可触摸

入参

名称 参数类型 详细说明 约束取值范围
touch bool 是否可触摸，true为可触摸，false为不可触摸 true/false

IsTouchable

bool IsTouchable() const

功能说明

  • 查询视图是否可触摸
  • 仅反映当前视图自身的可触摸属性
  • 不可触摸的视图不参与触摸事件分发

返回值

返回值 触发场景
true 视图可触摸
false 视图不可触摸

SetDraggable

void SetDraggable(bool draggable)

功能说明

  • 设置视图是否可拖拽
  • 可拖拽的视图能响应拖拽开始、拖拽中、拖拽结束事件
  • 默认情况下视图不可拖拽

入参

名称 参数类型 详细说明 约束取值范围
draggable bool 是否可拖拽，true为可拖拽，false为不可拖拽 true/false

IsDraggable

bool IsDraggable() const

功能说明

  • 查询视图是否可拖拽
  • 仅反映当前视图自身的可拖拽属性
  • 不可拖拽的视图不会触发拖拽相关事件

返回值

返回值 触发场景
true 视图可拖拽
false 视图不可拖拽

SetDragParentInstead

void SetDragParentInstead(bool dragParentInstead)

功能说明

  • 设置当视图被拖拽时，是否将拖拽事件转交父视图处理
  • 为true时当前视图不处理拖拽事件，由父视图代为处理
  • 适用于子视图不需要独立拖拽逻辑的场景

入参

名称 参数类型 详细说明 约束取值范围
dragParentInstead bool 是否转交父视图，true为转交，false为不转交 true/false

IsDragParentInstead

bool IsDragParentInstead() const

功能说明

  • 查询拖拽事件是否转交父视图处理
  • 为true时拖拽事件由父视图代为处理
  • 默认情况下不转交父视图

返回值

返回值 触发场景
true 拖拽事件转交父视图处理
false 拖拽事件由当前视图自行处理

SetFullScreenBlur

void SetFullScreenBlur(bool isFull)

功能说明

  • 设置视图是否使用全屏模糊效果
  • 为true时模糊效果作用于全屏范围而非仅视图自身区域
  • 适用于需要全局模糊背景的弹窗或覆盖层场景

入参

名称 参数类型 详细说明 约束取值范围
isFull bool 是否全屏模糊，true为全屏模糊，false为仅视图区域 true/false

IsFullScreenBlur

bool IsFullScreenBlur() const

功能说明

  • 查询视图是否设置为全屏模糊
  • 为true时模糊范围覆盖全屏
  • 默认情况下不使用全屏模糊

返回值

返回值 触发场景
true 视图使用全屏模糊
false 视图不使用全屏模糊

GetRect

Rect GetRect() const

功能说明

  • 获取视图的绝对矩形区域
  • 当视图存在旋转变形时，返回绝对矩形区域与变形矩阵的交集
  • 绝对坐标是相对于屏幕原点的坐标

返回值

返回值 触发场景
Rect 视图的绝对矩形区域

GetVisibleRect

Rect GetVisibleRect() const

功能说明

  • 获取视图的可见绝对矩形区域
  • 可见区域为视图实际能显示在屏幕上的区域
  • 考虑了父视图裁剪等影响后的实际可见范围

返回值

返回值 触发场景
Rect 视图的可见绝对矩形区域

GetMaskedRect

Rect GetMaskedRect() const

功能说明

  • 获取视图的有效绝对矩形区域
  • 有效区域指视图能正常显示的区域，通常与可见区域相同
  • 在网格布局等场景中，有效区域可能与可见区域不同

返回值

返回值 触发场景
Rect 视图的有效绝对矩形区域

GetOrigRect

Rect GetOrigRect() const

功能说明

  • 获取视图的原始绝对矩形区域
  • 不考虑变形变换，返回视图原始的矩形区域
  • 用于需要获取未变换区域信息的场景

返回值

返回值 触发场景
Rect 视图的原始绝对矩形区域

GetContentRect

virtual Rect GetContentRect()

功能说明

  • 获取视图内容的绝对矩形区域，该区域不包含padding
  • 内容区域是视图实际绘制内容的区域
  • 子类可重写此方法返回自定义内容区域

返回值

返回值 触发场景
Rect 视图内容绝对矩形区域

GetOrigContentRect

virtual Rect GetOrigContentRect()

功能说明

  • 获取视图原始内容绝对矩形区域，不包含padding
  • 不考虑变形变换，返回原始内容矩形区域
  • 用于需要获取未变换内容区域信息的场景

返回值

返回值 触发场景
Rect 视图原始内容绝对矩形区域

GetRelativeRect

Rect GetRelativeRect() const

功能说明

  • 获取视图相对于父视图的矩形区域
  • 坐标原点为父视图的左上角
  • 用于布局计算中获取视图在父视图内的相对位置

返回值

返回值 触发场景
Rect 视图相对于父视图的矩形区域

ResizeVisibleArea

void ResizeVisibleArea(int16_t x, int16_t y, int16_t width, int16_t height)

功能说明

  • 调整视图可见区域的大小
  • 可能影响视图的最终显示尺寸
  • 用于自定义可见区域的场景

入参

名称 参数类型 详细说明 约束取值范围
x int16_t 新的x坐标 整数值
y int16_t 新的y坐标 整数值
width int16_t 新的宽度 正整数
height int16_t 新的高度 正整数

SetWidth

virtual void SetWidth(int16_t width)

功能说明

  • 设置视图的宽度
  • 设置后视图的实际绘制宽度将更新
  • 子类可重写此方法添加宽度变更的额外处理

入参

名称 参数类型 详细说明 约束取值范围
width int16_t 视图宽度值 正整数

SetWidthPercent

virtual void SetWidthPercent(float widthPercent)

功能说明

  • 设置视图宽度占父视图宽度的百分比
  • 视图实际宽度根据父视图宽度和百分比动态计算
  • 适用于需要响应式布局的场景

入参

名称 参数类型 详细说明 约束取值范围
widthPercent float 宽度百分比的小数形式 0.0~1.0

GetWidth

virtual int16_t GetWidth()

功能说明

  • 获取视图的宽度
  • 返回视图的像素宽度值
  • 子类可重写此方法返回自定义宽度

返回值

返回值 触发场景
int16_t 视图宽度值

SetHeight

virtual void SetHeight(int16_t height)

功能说明

  • 设置视图的高度
  • 设置后视图的实际绘制高度将更新
  • 子类可重写此方法添加高度变更的额外处理

入参

名称 参数类型 详细说明 约束取值范围
height int16_t 视图高度值 正整数

SetHeightPercent

virtual void SetHeightPercent(float heightPercent)

功能说明

  • 设置视图高度占父视图高度的百分比
  • 视图实际高度根据父视图高度和百分比动态计算
  • 适用于需要响应式布局的场景

入参

名称 参数类型 详细说明 约束取值范围
heightPercent float 高度百分比的小数形式 0.0~1.0

GetHeight

virtual int16_t GetHeight()

功能说明

  • 获取视图的高度
  • 返回视图的像素高度值
  • 子类可重写此方法返回自定义高度

返回值

返回值 触发场景
int16_t 视图高度值

Resize

virtual void Resize(int16_t width, int16_t height)

功能说明

  • 同时调整视图的宽度和高度
  • 等效于分别调用SetWidth和SetHeight，但仅触发一次重绘
  • 子类可重写此方法添加尺寸变更的额外处理

入参

名称 参数类型 详细说明 约束取值范围
width int16_t 新的宽度 正整数
height int16_t 新的高度 正整数

ResizePercent

virtual void ResizePercent(float widthPercent, float heightPercent)

功能说明

  • 按百分比同时调整视图的宽度和高度
  • 宽度百分比为视图宽度占父视图宽度的比例
  • 高度百分比为视图高度占父视图高度的比例

入参

名称 参数类型 详细说明 约束取值范围
widthPercent float 宽度百分比的小数形式 0.0~1.0
heightPercent float 高度百分比的小数形式 0.0~1.0

SetX

virtual void SetX(int16_t x)

功能说明

  • 设置视图的x坐标
  • 坐标为相对于父视图的偏移量
  • 子类可重写此方法添加坐标变更的额外处理

入参

名称 参数类型 详细说明 约束取值范围
x int16_t 视图x坐标值 整数值

SetXPercent

virtual void SetXPercent(float xPercent)

功能说明

  • 设置视图x坐标占父视图宽度的百分比
  • 视图实际x坐标根据父视图宽度和百分比动态计算
  • 适用于需要响应式布局的场景

入参

名称 参数类型 详细说明 约束取值范围
xPercent float x坐标百分比的小数形式 0.0~1.0

GetX

int16_t GetX() const

功能说明

  • 获取视图的x坐标
  • 返回相对于父视图的x偏移量
  • 不含margin的坐标值

返回值

返回值 触发场景
int16_t 视图x坐标值

SetY

virtual void SetY(int16_t y)

功能说明

  • 设置视图的y坐标
  • 坐标为相对于父视图的偏移量
  • 子类可重写此方法添加坐标变更的额外处理

入参

名称 参数类型 详细说明 约束取值范围
y int16_t 视图y坐标值 整数值

SetYPercent

virtual void SetYPercent(float yPercent)

功能说明

  • 设置视图y坐标占父视图高度的百分比
  • 视图实际y坐标根据父视图高度和百分比动态计算
  • 适用于需要响应式布局的场景

入参

名称 参数类型 详细说明 约束取值范围
yPercent float y坐标百分比的小数形式 0.0~1.0

GetY

int16_t GetY() const

功能说明

  • 获取视图的y坐标
  • 返回相对于父视图的y偏移量
  • 不含margin的坐标值

返回值

返回值 触发场景
int16_t 视图y坐标值

GetWidthWithMargin

int16_t GetWidthWithMargin()

功能说明

  • 获取包含margin的视图宽度
  • 宽度 = 视图宽度 + marginLeft + marginRight
  • 用于布局计算中需要考虑margin的场景

返回值

返回值 触发场景
int16_t 包含margin的宽度值

GetHeightWithMargin

int16_t GetHeightWithMargin()

功能说明

  • 获取包含margin的视图高度
  • 高度 = 视图高度 + marginTop + marginBottom
  • 用于布局计算中需要考虑margin的场景

返回值

返回值 触发场景
int16_t 包含margin的高度值

SetPosition

virtual void SetPosition(int16_t x, int16_t y)

功能说明

  • 设置视图的位置，同时设置x和y坐标
  • 等效于分别调用SetX和SetY，但仅触发一次重绘
  • 子类可重写此方法添加位置变更的额外处理

入参

名称 参数类型 详细说明 约束取值范围
x int16_t 视图x坐标值 整数值
y int16_t 视图y坐标值 整数值

SetPositionPercent

virtual void SetPositionPercent(float xPercent, float yPercent)

功能说明

  • 按百分比设置视图的位置
  • xPercent为视图x坐标占父视图宽度的百分比
  • yPercent为视图y坐标占父视图高度的百分比

入参

名称 参数类型 详细说明 约束取值范围
xPercent float x坐标百分比的小数形式 0.0~1.0
yPercent float y坐标百分比的小数形式 0.0~1.0

SetPosition

virtual void SetPosition(int16_t x, int16_t y, int16_t width, int16_t height)

功能说明

  • 同时设置视图的位置和大小
  • 等效于同时调用SetX、SetY、SetWidth、SetHeight，但仅触发一次重绘
  • 子类可重写此方法添加位置和尺寸变更的额外处理

入参

名称 参数类型 详细说明 约束取值范围
x int16_t 视图x坐标值 整数值
y int16_t 视图y坐标值 整数值
width int16_t 视图宽度 正整数
height int16_t 视图高度 正整数

SetPositionPercent

virtual void SetPositionPercent(float xPercent, float yPercent, float widthPercent, float heightPercent)

功能说明

  • 按百分比同时设置视图的位置和大小
  • 所有参数均为相对于父视图的百分比小数形式
  • 适用于需要响应式布局的场景

入参

名称 参数类型 详细说明 约束取值范围
xPercent float x坐标百分比 0.0~1.0
yPercent float y坐标百分比 0.0~1.0
widthPercent float 宽度百分比 0.0~1.0
heightPercent float 高度百分比 0.0~1.0

IsViewGroup

bool IsViewGroup() const

功能说明

  • 查询视图是否为容器视图（ViewGroup）
  • 容器视图可以包含子视图，非容器视图不能包含子视图
  • 该属性在容器视图构造时被设置

返回值

返回值 触发场景
true 视图为容器视图
false 视图不是容器视图

SetIntercept

void SetIntercept(bool isIntercept)

功能说明

  • 设置是否拦截输入事件
  • 拦截后视图不在本地处理完成后将输入事件传递给父视图
  • 适用于需要阻止事件冒泡的场景

入参

名称 参数类型 详细说明 约束取值范围
isIntercept bool 是否拦截，true为拦截，false为不拦截 true/false

IsIntercept

bool IsIntercept()

功能说明

  • 查询是否拦截输入事件
  • 拦截时视图不将输入事件传递给父视图
  • 默认不拦截

返回值

返回值 触发场景
true 拦截输入事件
false 不拦截输入事件

SetTransformMap

void SetTransformMap(const TransformMap& transMap)

功能说明

  • 设置视图的仿射变换矩阵
  • 变换矩阵用于实现旋转、缩放、平移等变换效果
  • 设置新的变换矩阵后视图将按新矩阵进行变换

入参

名称 参数类型 详细说明 约束取值范围
transMap const TransformMap& 仿射变换矩阵 有效的TransformMap引用

GetTransformMap

TransformMap& GetTransformMap()

功能说明

  • 获取视图的仿射变换矩阵
  • 返回引用可允许直接修改变换矩阵
  • 未设置变换时返回默认的恒等变换矩阵

返回值

返回值 触发场景
TransformMap& 仿射变换矩阵引用

GetChildById

virtual UIView* GetChildById(const char* id) const

功能说明

  • 根据视图ID获取子视图
  • 在当前视图的子视图中查找指定ID的视图
  • 非容器视图默认返回nullptr

入参

名称 参数类型 详细说明 约束取值范围
id const char* 子视图ID 非空字符串指针

返回值

返回值 触发场景
UIView* 子视图指针，未找到时为nullptr

SetViewId

void SetViewId(const char* id)

功能说明

  • 设置视图ID
  • 视图ID用于在视图树中唯一标识和查找视图
  • ID为字符串指针，外部需保证ID字符串的生命周期

入参

名称 参数类型 详细说明 约束取值范围
id const char* 视图ID字符串指针 字符串指针

GetViewId

const char* GetViewId() const

功能说明

  • 获取视图ID
  • 返回视图ID的字符串指针
  • 未设置ID时返回nullptr

返回值

返回值 触发场景
const char* 视图ID字符串指针，未设置时为nullptr

SetViewIndex

void SetViewIndex(int16_t index)

功能说明

  • 设置视图索引
  • 索引用于标识视图在父容器中的顺序
  • 通常由容器视图在添加子视图时内部设置

入参

名称 参数类型 详细说明 约束取值范围
index int16_t 视图索引值 int16_t范围

GetViewIndex

int16_t GetViewIndex() const

功能说明

  • 获取视图索引
  • 返回视图在父容器中的顺序索引
  • 未设置时为默认值

返回值

返回值 触发场景
int16_t 视图索引值

GetViewType

virtual UIViewType GetViewType() const

功能说明

  • 获取视图类型
  • 返回UIViewType枚举值，标识视图的具体类型
  • 子类必须重写此方法返回正确的视图类型

返回值

返回值 触发场景
UIViewType 视图类型枚举值

LayoutChildren

virtual void LayoutChildren(bool neeInvalidate = false)

功能说明

  • 按预设排列模式布局所有子视图
  • 仅容器视图需要重写此方法
  • neeInvalidate为true时布局完成后刷新失效区域

入参

名称 参数类型 详细说明 约束取值范围
neeInvalidate bool 布局完成后是否刷新失效区域，默认false true/false

LayoutCenterOfParent

void LayoutCenterOfParent(int16_t xOffSet = 0, int16_t yOffset = 0)

功能说明

  • 将视图布局在父视图的中心位置
  • 可通过偏移参数在中心位置基础上进行微调
  • 正xOffset向右偏移，正yOffset向下偏移

入参

名称 参数类型 详细说明 约束取值范围
xOffSet int16_t x轴偏移量，默认0，正值向右，负值向左 整数值
yOffset int16_t y轴偏移量，默认0，正值向下，负值向上 整数值

LayoutLeftOfParent

void LayoutLeftOfParent(int16_t offset = 0)

功能说明

  • 将视图布局在父视图的左侧
  • 正offset向右偏移，负offset向左偏移
  • 视图左边缘与父视图左边缘对齐（加上偏移量）

入参

名称 参数类型 详细说明 约束取值范围
offset int16_t x轴偏移量，默认0，正值向右，负值向左 整数值

LayoutRightOfParent

void LayoutRightOfParent(int16_t offset = 0)

功能说明

  • 将视图布局在父视图的右侧
  • 正offset向左偏移，负offset向右偏移
  • 视图右边缘与父视图右边缘对齐（加上偏移量）

入参

名称 参数类型 详细说明 约束取值范围
offset int16_t x轴偏移量，默认0，正值向左，负值向右 整数值

LayoutTopOfParent

void LayoutTopOfParent(int16_t offset = 0)

功能说明

  • 将视图布局在父视图的上方
  • 正offset向下偏移，负offset向上偏移
  • 视图上边缘与父视图上边缘对齐（加上偏移量）

入参

名称 参数类型 详细说明 约束取值范围
offset int16_t y轴偏移量，默认0，正值向下，负值向上 整数值

LayoutBottomOfParent

void LayoutBottomOfParent(int16_t offset = 0)

功能说明

  • 将视图布局在父视图的下方
  • 正offset向上偏移，负offset向下偏移
  • 视图下边缘与父视图下边缘对齐（加上偏移量）

入参

名称 参数类型 详细说明 约束取值范围
offset int16_t y轴偏移量，默认0，正值向上，负值向下 整数值

AlignLeftToSibling

void AlignLeftToSibling(const char* id, int16_t offset = 0)

功能说明

  • 将视图与指定ID的兄弟视图左对齐
  • 正offset向右偏移，负offset向左偏移
  • 视图左边缘与兄弟视图左边缘对齐（加上偏移量）

入参

名称 参数类型 详细说明 约束取值范围
id const char* 兄弟视图ID 非空字符串指针
offset int16_t x轴偏移量，默认0 整数值

AlignRightToSibling

void AlignRightToSibling(const char* id, int16_t offset = 0)

功能说明

  • 将视图与指定ID的兄弟视图右对齐
  • 正offset向左偏移，负offset向右偏移
  • 视图右边缘与兄弟视图右边缘对齐（加上偏移量）

入参

名称 参数类型 详细说明 约束取值范围
id const char* 兄弟视图ID 非空字符串指针
offset int16_t x轴偏移量，默认0 整数值

AlignTopToSibling

void AlignTopToSibling(const char* id, int16_t offset = 0)

功能说明

  • 将视图与指定ID的兄弟视图顶部对齐
  • 正offset向下偏移，负offset向上偏移
  • 视图上边缘与兄弟视图上边缘对齐（加上偏移量）

入参

名称 参数类型 详细说明 约束取值范围
id const char* 兄弟视图ID 非空字符串指针
offset int16_t y轴偏移量，默认0 整数值

AlignBottomToSibling

void AlignBottomToSibling(const char* id, int16_t offset = 0)

功能说明

  • 将视图与指定ID的兄弟视图底部对齐
  • 正offset向上偏移，负offset向下偏移
  • 视图下边缘与兄弟视图下边缘对齐（加上偏移量）

入参

名称 参数类型 详细说明 约束取值范围
id const char* 兄弟视图ID 非空字符串指针
offset int16_t y轴偏移量，默认0 整数值

AlignHorCenterToSibling

void AlignHorCenterToSibling(const char* id, int16_t offset = 0)

功能说明

  • 将视图与指定ID的兄弟视图水平居中对齐
  • 正offset向右偏移，负offset向左偏移
  • 视图水平中心与兄弟视图水平中心对齐（加上偏移量）

入参

名称 参数类型 详细说明 约束取值范围
id const char* 兄弟视图ID 非空字符串指针
offset int16_t x轴偏移量，默认0 整数值

AlignVerCenterToSibling

void AlignVerCenterToSibling(const char* id, int16_t offset = 0)

功能说明

  • 将视图与指定ID的兄弟视图垂直居中对齐
  • 正offset向下偏移，负offset向上偏移
  • 视图垂直中心与兄弟视图垂直中心对齐（加上偏移量）

入参

名称 参数类型 详细说明 约束取值范围
id const char* 兄弟视图ID 非空字符串指针
offset int16_t y轴偏移量，默认0 整数值

AlignToReference

void AlignToReference(AlignmentType alignType, UIView* referView, int16_t ofsX = 0, int16_t ofsY = 0)

功能说明

  • 将视图与参考视图按指定的对齐类型进行对齐
  • 支持多种对齐方式，由alignType参数指定
  • 可通过偏移参数在对齐位置基础上进行微调

入参

名称 参数类型 详细说明 约束取值范围
alignType AlignmentType 对齐类型 AlignmentType枚举值
referView UIView* 参考视图指针 非空UIView指针
ofsX int16_t x轴偏移量，默认0 整数值
ofsY int16_t y轴偏移量，默认0 整数值

UpdatePos

void UpdatePos()

功能说明

  • 更新子视图位置，在父视图尺寸发生变化时调用
  • 根据当前对齐类型重新计算子视图位置
  • 确保子视图在父视图尺寸变化后仍保持正确的对齐关系

LayoutLeftToSibling

void LayoutLeftToSibling(const char* id, int16_t offset = 0)

功能说明

  • 将视图布局在指定ID的兄弟视图左侧
  • 正offset向左偏移，负offset向右偏移
  • 视图右边缘与兄弟视图左边缘对齐（加上偏移量）

入参

名称 参数类型 详细说明 约束取值范围
id const char* 兄弟视图ID 非空字符串指针
offset int16_t x轴偏移量，默认0，正值向左，负值向右 整数值

LayoutRightToSibling

void LayoutRightToSibling(const char* id, int16_t offset = 0)

功能说明

  • 将视图布局在指定ID的兄弟视图右侧
  • 正offset向右偏移，负offset向左偏移
  • 视图左边缘与兄弟视图右边缘对齐（加上偏移量）

入参

名称 参数类型 详细说明 约束取值范围
id const char* 兄弟视图ID 非空字符串指针
offset int16_t x轴偏移量，默认0，正值向右，负值向左 整数值

LayoutTopToSibling

void LayoutTopToSibling(const char* id, int16_t offset = 0)

功能说明

  • 将视图布局在指定ID的兄弟视图上方
  • 正offset向上偏移，负offset向下偏移
  • 视图下边缘与兄弟视图上边缘对齐（加上偏移量）

入参

名称 参数类型 详细说明 约束取值范围
id const char* 兄弟视图ID 非空字符串指针
offset int16_t y轴偏移量，默认0，正值向上，负值向下 整数值

LayoutBottomToSibling

void LayoutBottomToSibling(const char* id, int16_t offset = 0)

功能说明

  • 将视图布局在指定ID的兄弟视图下方
  • 正offset向下偏移，负offset向上偏移
  • 视图上边缘与兄弟视图下边缘对齐（加上偏移量）

入参

名称 参数类型 详细说明 约束取值范围
id const char* 兄弟视图ID 非空字符串指针
offset int16_t y轴偏移量，默认0，正值向下，负值向上 整数值

SetStyle

virtual void SetStyle(Style& style)

功能说明

  • 设置视图的完整样式对象
  • 替换当前视图的所有样式属性
  • 子类可重写此方法添加样式变更的额外处理

入参

名称 参数类型 详细说明 约束取值范围
style Style& 视图样式对象引用 有效的Style引用

SetStyle

virtual void SetStyle(uint8_t key, int64_t value)

功能说明

  • 设置单个样式属性值
  • 通过key指定样式属性类型，value设置对应值
  • 子类可重写此方法添加特定样式属性的处理

入参

名称 参数类型 详细说明 约束取值范围
key uint8_t 样式属性键值 有效的StyleKey枚举值
value int64_t 样式属性值 与key对应的取值范围

GetStyle

virtual int64_t GetStyle(uint8_t key) const

功能说明

  • 获取指定样式属性的值
  • 通过key指定要查询的样式属性类型
  • 子类可重写此方法添加特定样式属性的获取逻辑

入参

名称 参数类型 详细说明 约束取值范围
key uint8_t 样式属性键值 有效的StyleKey枚举值

返回值

返回值 触发场景
int64_t 样式属性值

GetStyleConst

const Style& GetStyleConst() const

功能说明

  • 获取视图样式的常量引用
  • 适用于不需要修改样式的场景，可节省内存
  • 返回的引用不允许修改样式内容

返回值

返回值 触发场景
const Style& 视图样式的常量引用

SetOpaScale

void SetOpaScale(uint8_t opaScale)

功能说明

  • 设置视图的透明度
  • 透明度值影响视图的整体绘制透明效果
  • 值为0时完全透明，值为255时完全不透明

入参

名称 参数类型 详细说明 约束取值范围
opaScale uint8_t 透明度值 0~255

GetOpaScale

uint8_t GetOpaScale() const

功能说明

  • 获取视图的透明度
  • 返回当前设置的透明度值
  • 默认值为255（完全不透明）

返回值

返回值 触发场景
uint8_t 视图透明度值，0~255

GetExtraMsg

ViewExtraMsg* GetExtraMsg()

功能说明

  • 获取视图的附加信息
  • 附加信息由图形框架之外的逻辑设置和使用
  • 未设置时返回nullptr

返回值

返回值 触发场景
ViewExtraMsg* 附加信息指针，未设置时为nullptr

SetExtraMsg

void SetExtraMsg(ViewExtraMsg* extraMsg)

功能说明

  • 设置视图的附加信息
  • 附加信息由图形框架之外的逻辑设置，框架本身不使用此字段
  • 可存储任意与视图关联的自定义数据

入参

名称 参数类型 详细说明 约束取值范围
extraMsg ViewExtraMsg* 附加信息指针 ViewExtraMsg指针或nullptr

Rotate

void Rotate(int16_t angle, const Vector2<float>& pivot)

功能说明

  • 2D旋转视图
  • 围绕指定枢轴点旋转指定角度
  • 旋转后视图的矩形区域将发生变化

入参

名称 参数类型 详细说明 约束取值范围
angle int16_t 旋转角度 整数值
pivot const Vector2& 旋转枢轴点坐标 有效的Vector2引用

Rotate

void Rotate(int16_t angle, const Vector3<float>& pivotStart, const Vector3<float>& pivotEnd)

功能说明

  • 3D旋转视图
  • 通过起始和结束枢轴点定义旋转轴
  • 适用于3D变换效果

入参

名称 参数类型 详细说明 约束取值范围
angle int16_t 旋转角度 整数值
pivotStart const Vector3& 旋转起始枢轴点 有效的Vector3引用
pivotEnd const Vector3& 旋转结束枢轴点 有效的Vector3引用

Scale

virtual void Scale(const Vector2<float>& scale, const Vector2<float>& pivot)

功能说明

  • 2D缩放视图
  • 通过x和y方向的缩放因子进行缩放
  • 围绕指定枢轴点进行缩放

入参

名称 参数类型 详细说明 约束取值范围
scale const Vector2& x和y方向的缩放因子 浮点数
pivot const Vector2& 缩放枢轴点坐标 有效的Vector2引用

Scale

virtual void Scale(const Vector3<float>& scale, const Vector3<float>& pivot)

功能说明

  • 3D缩放视图
  • 通过x、y和z方向的缩放因子进行缩放
  • 围绕指定3D枢轴点进行缩放

入参

名称 参数类型 详细说明 约束取值范围
scale const Vector3& x、y、z方向的缩放因子 浮点数
pivot const Vector3& 缩放枢轴点坐标 有效的Vector3引用

Shear

void Shear(const Vector2<float>& shearX, const Vector2<float>& shearY, const Vector2<float>& shearZ)

功能说明

  • 对视图进行3D剪切变换
  • shearX控制y和z方向的剪切（z方向当前无效）
  • shearY控制x和z方向的剪切（z方向当前无效），shearZ控制x和y方向的剪切

入参

名称 参数类型 详细说明 约束取值范围
shearX const Vector2& x轴剪切参数 浮点数
shearY const Vector2& y轴剪切参数 浮点数
shearZ const Vector2& z轴剪切参数 浮点数

Translate

void Translate(const Vector2<int16_t>& trans)

功能说明

  • 2D平移视图
  • 通过x和y方向的偏移量进行平移
  • 平移改变视图的绘制位置但不改变其逻辑位置

入参

名称 参数类型 详细说明 约束取值范围
trans const Vector2& x和y方向的平移量 整数值

Translate

void Translate(const Vector3<int16_t>& trans)

功能说明

  • 3D平移视图
  • 通过x、y和z方向的偏移量进行平移
  • 适用于3D变换场景

入参

名称 参数类型 详细说明 约束取值范围
trans const Vector3& x、y、z方向的平移量 整数值

IsTransInvalid

bool IsTransInvalid()

功能说明

  • 查询视图的变换参数是否无效
  • 变换参数无效时需要重新计算变换矩阵
  • 用于判断是否需要更新变换

返回值

返回值 触发场景
true 变换参数无效，需要重新计算
false 变换参数有效

SetCameraDistance

void SetCameraDistance(int16_t distance)

功能说明

  • 设置3D变换中相机的距离
  • 相机距离影响3D透视效果的强度
  • 距离越大透视效果越弱，距离越小透视效果越强

入参

名称 参数类型 详细说明 约束取值范围
distance int16_t 相机距离值 正整数

SetCameraPosition

void SetCameraPosition(const Vector2<float>& position)

功能说明

  • 设置3D变换中相机的位置
  • 相机位置影响3D变换的视角
  • 用于自定义3D变换的观察角度

入参

名称 参数类型 详细说明 约束取值范围
position const Vector2& 相机位置坐标 浮点数

ResetTransParameter

void ResetTransParameter()

功能说明

  • 重置所有变换参数
  • 清除旋转、缩放、平移、剪切等变换设置
  • 重置后视图恢复到未变换状态

SetBackgroundBlur

void SetBackgroundBlur(float radius, uint32_t quality = 0)

功能说明

  • 设置背景模糊效果
  • radius控制模糊半径，值越大模糊效果越强
  • quality控制模糊质量，默认为0

入参

名称 参数类型 详细说明 约束取值范围
radius float 模糊半径 正浮点数
quality uint32_t 模糊质量，默认0 非负整数

ClearBackgroundBlur

void ClearBackgroundBlur()

功能说明

  • 清除背景模糊效果
  • 调用后视图不再应用背景模糊
  • 同时清除相关的模糊参数设置

SetBlurPath

void SetBlurPath(uint32_t cmdNum, const uint8_t* cmd, uint32_t dataNum, const float* data)

功能说明

  • 按指定路径设置模糊效果
  • 通过路径命令和数据定义模糊区域形状
  • 仅在ENABLE_VGU_ENGINE和CAPABILITY_HW_GAUSSIAN_BLUR_BY_MASK宏开启时可用

Kconfig配置

ENABLE_VGU_ENGINE && CAPABILITY_HW_GAUSSIAN_BLUR_BY_MASK

入参

名称 参数类型 详细说明 约束取值范围
cmdNum uint32_t 路径命令数量 正整数
cmd const uint8_t* 路径命令数组指针 非空指针
dataNum uint32_t 路径数据数量 正整数
data const float* 路径数据数组指针 非空指针

ClearBlurPath

void ClearBlurPath()

功能说明

  • 清除模糊路径设置
  • 调用后模糊效果不再按路径形状应用
  • 仅在ENABLE_VGU_ENGINE和CAPABILITY_HW_GAUSSIAN_BLUR_BY_MASK宏开启时可用

Kconfig配置

ENABLE_VGU_ENGINE && CAPABILITY_HW_GAUSSIAN_BLUR_BY_MASK

RequestFocus

virtual void RequestFocus()

功能说明

  • 请求视图获得焦点
  • 调用后视图将成为焦点视图
  • 仅在ENABLE_ROTATE_INPUT宏开启时可用

Kconfig配置

ENABLE_ROTATE_INPUT

ClearFocus

virtual void ClearFocus()

功能说明

  • 清除视图的焦点状态
  • 调用后视图失去焦点
  • 仅在ENABLE_ROTATE_INPUT宏开启时可用

Kconfig配置

ENABLE_ROTATE_INPUT

SetFocusable

virtual void SetFocusable(bool focusable)

功能说明

  • 设置视图是否可获焦
  • 可获焦的视图能够响应焦点相关的操作
  • 仅在ENABLE_FOCUS_MANAGER宏开启时可用

Kconfig配置

ENABLE_FOCUS_MANAGER

入参

名称 参数类型 详细说明 约束取值范围
focusable bool 是否可获焦，true为可获焦，false为不可获焦 true/false

IsFocusable

virtual bool IsFocusable() const

功能说明

  • 查询视图是否可获焦
  • 可获焦的视图能参与焦点管理
  • 仅在ENABLE_FOCUS_MANAGER宏开启时可用

Kconfig配置

ENABLE_FOCUS_MANAGER

返回值

返回值 触发场景
true 视图可获焦
false 视图不可获焦

Focus

virtual void Focus()

功能说明

  • 视图获焦时的响应回调
  • 当视图获得焦点时由焦点管理器调用
  • 仅在ENABLE_FOCUS_MANAGER宏开启时可用

Kconfig配置

ENABLE_FOCUS_MANAGER

Blur

virtual void Blur()

功能说明

  • 视图失焦时的响应回调
  • 当视图失去焦点时由焦点管理器调用
  • 仅在ENABLE_FOCUS_MANAGER宏开启时可用

Kconfig配置

ENABLE_FOCUS_MANAGER

SetOnFocusListener

virtual void SetOnFocusListener(OnFocusListener* onFocusListener)

功能说明

  • 设置焦点改变事件监听器
  • 当视图获焦或失焦时将回调监听器中的对应方法
  • 仅在ENABLE_FOCUS_MANAGER宏开启时可用

Kconfig配置

ENABLE_FOCUS_MANAGER

入参

名称 参数类型 详细说明 约束取值范围
onFocusListener OnFocusListener* 焦点改变事件监听器指针 OnFocusListener指针或nullptr

GetOnFocusListener

virtual OnFocusListener* GetOnFocusListener() const

功能说明

  • 获取焦点改变事件监听器
  • 返回当前设置的焦点改变事件监听器
  • 仅在ENABLE_FOCUS_MANAGER宏开启时可用

Kconfig配置

ENABLE_FOCUS_MANAGER

返回值

返回值 触发场景
OnFocusListener* 焦点改变事件监听器指针，未设置时为nullptr

OnRotateStartEvent

virtual bool OnRotateStartEvent(const RotateEvent& event)

功能说明

  • 旋转开始事件回调，当视图开始旋转时触发
  • 若事件被消费则不再向父视图传递
  • 仅在ENABLE_ROTATE_INPUT宏开启时可用

Kconfig配置

ENABLE_ROTATE_INPUT

入参

名称 参数类型 详细说明 约束取值范围
event const RotateEvent& 旋转事件对象 有效的RotateEvent引用

返回值

返回值 触发场景
true 旋转开始事件被消费
false 旋转开始事件未被消费

OnRotateEvent

virtual bool OnRotateEvent(const RotateEvent& event)

功能说明

  • 旋转事件回调，当视图正在旋转时持续触发
  • 若事件被消费则不再向父视图传递
  • 仅在ENABLE_ROTATE_INPUT宏开启时可用

Kconfig配置

ENABLE_ROTATE_INPUT

入参

名称 参数类型 详细说明 约束取值范围
event const RotateEvent& 旋转事件对象 有效的RotateEvent引用

返回值

返回值 触发场景
true 旋转事件被消费
false 旋转事件未被消费

OnRotateEndEvent

virtual bool OnRotateEndEvent(const RotateEvent& event)

功能说明

  • 旋转结束事件回调，当视图停止旋转时触发
  • 若事件被消费则不再向父视图传递
  • 仅在ENABLE_ROTATE_INPUT宏开启时可用

Kconfig配置

ENABLE_ROTATE_INPUT

入参

名称 参数类型 详细说明 约束取值范围
event const RotateEvent& 旋转事件对象 有效的RotateEvent引用

返回值

返回值 触发场景
true 旋转结束事件被消费
false 旋转结束事件未被消费

SetOnRotateListener

virtual void SetOnRotateListener(OnRotateListener* onRotateListener)

功能说明

  • 设置旋转事件监听器，用于监听视图的旋转相关事件
  • 设置后当旋转事件发生时将回调监听器中的对应方法
  • 仅在ENABLE_ROTATE_INPUT宏开启时可用

Kconfig配置

ENABLE_ROTATE_INPUT

入参

名称 参数类型 详细说明 约束取值范围
onRotateListener OnRotateListener* 旋转事件监听器指针 OnRotateListener指针或nullptr

GetOnRotateListener

virtual OnRotateListener*& GetOnRotateListener()

功能说明

  • 获取旋转事件监听器
  • 返回引用可允许直接修改监听器指针
  • 仅在ENABLE_ROTATE_INPUT宏开启时可用

Kconfig配置

ENABLE_ROTATE_INPUT

返回值

返回值 触发场景
OnRotateListener*& 旋转事件监听器引用，未设置时为nullptr

GetBitmap

virtual bool GetBitmap(ImageInfo& bitmap, ColorMode colorMode = RGB888)

功能说明

  • 获取视图的位图截图
  • 截图将存储到bitmap参数中，该接口会申请内存
  • 使用完毕后需调用ImageCacheFree()接口释放内存

入参

名称 参数类型 详细说明 约束取值范围
bitmap ImageInfo& 位图存储对象引用 有效的ImageInfo引用
colorMode ColorMode 截图格式，默认为RGB888 ColorMode枚举值

返回值

返回值 触发场景
true 位图获取成功
false 位图获取失败

IsOnViewTree

bool IsOnViewTree()

功能说明

  • 查询视图是否在视图树上
  • 在视图树上表示视图已被添加到RootView的视图层级中
  • 不在视图树上的视图不会被绘制和响应事件

返回值

返回值 触发场景
true 视图在视图树上
false 视图不在视图树上

SetZIndex

void SetZIndex(int16_t zIndex)

功能说明

  • 设置视图的z轴层级
  • zIndex值越大，视图在渲染时越靠前（显示在上层）
  • 默认zIndex为0

入参

名称 参数类型 详细说明 约束取值范围
zIndex int16_t z轴层级值 int16_t范围

GetZIndex

int16_t GetZIndex()

功能说明

  • 获取视图的z轴层级
  • 返回当前设置的zIndex值
  • 默认值为0

返回值

返回值 触发场景
int16_t z轴层级值

SetNextRenderSibling

void SetNextRenderSibling(UIView* renderSibling)

功能说明

  • 设置下一个渲染兄弟视图
  • 渲染兄弟视图用于控制视图的渲染顺序
  • 通常由框架内部调用

入参

名称 参数类型 详细说明 约束取值范围
renderSibling UIView* 下一个渲染兄弟视图指针 UIView指针或nullptr

GetNextRenderSibling

UIView* GetNextRenderSibling() const

功能说明

  • 获取下一个渲染兄弟视图
  • 返回当前视图在渲染链中的下一个视图
  • 无下一个渲染兄弟视图时返回nullptr

返回值

返回值 触发场景
UIView* 下一个渲染兄弟视图指针，无时为nullptr

HandleGaussianBlur

void HandleGaussianBlur(BufferInfo& gfxDstBuffer)

功能说明

  • 对背景执行高斯模糊处理
  • 当视图设置了模糊半径时调用此方法应用模糊效果
  • 模糊效果作用于gfxDstBuffer指定的缓冲区

入参

名称 参数类型 详细说明 约束取值范围
gfxDstBuffer BufferInfo& 需要执行模糊的图形缓冲区 有效的BufferInfo引用

HandleLighting

void HandleLighting(BufferInfo& gfxDstBuffer, const Rect& invalidatedArea)

功能说明

  • 对视图执行光照效果处理
  • 仅内部使用，由绘制引擎在渲染时调用
  • 仅在ENABLE_VGU_ENGINE和CAPABILITY_HW_LIGHT宏开启时可用

Kconfig配置

ENABLE_VGU_ENGINE && CAPABILITY_HW_LIGHT

入参

名称 参数类型 详细说明 约束取值范围
gfxDstBuffer BufferInfo& 需要进行光照处理的缓冲区 有效的BufferInfo引用
invalidatedArea const Rect& 失效区域 有效的Rect引用

SetSpeLightStyle

void SetSpeLightStyle(const LightSpeStyle& speLightStyle)

功能说明

  • 设置反射光照参数
  • 目前反射光效果仅支持圆形或扇形区域
  • 仅在ENABLE_VGU_ENGINE和CAPABILITY_HW_LIGHT宏开启时可用

Kconfig配置

ENABLE_VGU_ENGINE && CAPABILITY_HW_LIGHT

入参

名称 参数类型 详细说明 约束取值范围
speLightStyle const LightSpeStyle& 反射光配置参数 有效的LightSpeStyle引用

GetSpeLightStyle

LightSpeStyle GetSpeLightStyle()

功能说明

  • 获取反射光照参数
  • 返回当前设置的反射光配置参数
  • 仅在ENABLE_VGU_ENGINE和CAPABILITY_HW_LIGHT宏开启时可用

Kconfig配置

ENABLE_VGU_ENGINE && CAPABILITY_HW_LIGHT

返回值

返回值 触发场景
LightSpeStyle 反射光照参数

SetAmbLightStyle

void SetAmbLightStyle(float ambAmp)

功能说明

  • 设置环境基础光照值
  • 可调节控件所在矩形区域的亮度
  • 仅在ENABLE_VGU_ENGINE和CAPABILITY_HW_LIGHT宏开启时可用

Kconfig配置

ENABLE_VGU_ENGINE && CAPABILITY_HW_LIGHT

入参

名称 参数类型 详细说明 约束取值范围
ambAmp float 环境基础光照值 浮点数

GetAmbLightStyle

float GetAmbLightStyle()

功能说明

  • 获取环境基础光照值
  • 返回当前设置的环境基础光照值
  • 仅在ENABLE_VGU_ENGINE和CAPABILITY_HW_LIGHT宏开启时可用

Kconfig配置

ENABLE_VGU_ENGINE && CAPABILITY_HW_LIGHT

返回值

返回值 触发场景
float 环境基础光照值

EnableLight

void EnableLight(bool enable)

功能说明

  • 使能或禁用控件的光照设置
  • 使能后光照效果将应用于视图
  • 仅在ENABLE_VGU_ENGINE和CAPABILITY_HW_LIGHT宏开启时可用

Kconfig配置

ENABLE_VGU_ENGINE && CAPABILITY_HW_LIGHT

入参

名称 参数类型 详细说明 约束取值范围
enable bool 是否使能光照，true为使能，false为禁用 true/false

IsEnableLight

bool IsEnableLight()

功能说明

  • 查询光照设置是否使能
  • 使能后光照效果将应用于视图
  • 仅在ENABLE_VGU_ENGINE和CAPABILITY_HW_LIGHT宏开启时可用

Kconfig配置

ENABLE_VGU_ENGINE && CAPABILITY_HW_LIGHT

返回值

返回值 触发场景
true 光照设置已使能
false 光照设置未使能

IsVideoContained

bool IsVideoContained()

功能说明

  • 查询视图是否为视频视图或包含视频视图
  • 用于判断视图层级中是否存在需要特殊处理的视频视图
  • 视频视图通常需要特殊的渲染和刷新策略

返回值

返回值 触发场景
true 视图为视频视图或包含视频视图
false 视图不是视频视图且不包含视频视图

DumpImgInfoRecursive

void DumpImgInfoRecursive()

功能说明

  • 递归输出当前视图及其所有子视图的图片信息
  • 用于调试和诊断图片资源使用情况
  • 遍历整个视图树输出所有图片相关信息

DumpImgInfo

virtual void DumpImgInfo()

功能说明

  • 输出当前视图的图片信息
  • 用于调试和诊断图片资源使用情况
  • 子类可重写此方法输出特定图片信息，默认实现为空

GetGuiInfo

virtual std::string GetGuiInfo() const

功能说明

  • 获取视图的GUI调试信息
  • 返回包含视图基本属性的字符串
  • 用于调试和诊断视图状态

返回值

返回值 触发场景
std::string GUI调试信息字符串

SetPositionInner

void SetPositionInner(int16_t x, int16_t y)

功能说明

  • 内部设置视图位置，含margin偏移
  • 仅在x或y坐标实际变化时才更新
  • 设置的坐标会加上对应的margin值后作为实际位置

入参

名称 参数类型 详细说明 约束取值范围
x int16_t 视图x坐标值 整数值
y int16_t 视图y坐标值 整数值

DisableAlignType

void DisableAlignType()

功能说明

  • 禁用对齐类型
  • 禁用后视图不再根据对齐类型自动调整位置
  • 适用于需要手动控制视图位置的场景

EnableAlignType

void EnableAlignType()

功能说明

  • 启用对齐类型
  • 启用后视图将根据对齐类型自动调整位置
  • 与DisableAlignType配合使用

Enumerations

UIViewType

视图类型枚举，用于标识各类视图组件的类型。

enum UIViewType : uint8_t {
    UI_ROOT_VIEW = 0,
    UI_VIEW_GROUP = 1,
    UI_LABEL = 2,
    UI_ARC_LABEL = 3,
    UI_LABEL_BUTTON = 4,
    UI_CHECK_BOX = 5,
    UI_TOGGLE_BUTTON = 6,
    UI_RADIO_BUTTON = 7,
    UI_IMAGE_VIEW = 8,
    UI_BOX_PROGRESS = 9,
    UI_SLIDER = 10,
    UI_CIRCLE_PROGRESS = 11,
    UI_SCROLL_VIEW = 12,
    UI_LIST = 13,
    UI_DIGITAL_CLOCK = 14,
    UI_ANALOG_CLOCK = 15,
#if ENABLE_SWEEP_CLOCK
    UI_SWEEP_CLOCK,
#endif
    UI_PICKER = 16,
    UI_SWIPE_VIEW = 17,
    UI_TIME_PICKER = 18,
    UI_ABSTRACT_CLOCK = 19,
    UI_ABSTRACT_PROGRESS = 20,
    UI_ABSTRACT_SCROLL = 21,
    UI_AXIS = 22,
    UI_BUTTON = 23,
    UI_CANVAS = 24,
    UI_CHART = 25,
    UI_IMAGE_ANIMATOR_VIEW = 26,
    UI_REPEAT_BUTTON = 27,
    UI_TEXTURE_MAPPER = 28,
    UI_DIALOG = 29,
    UI_QRCODE = 30,
    UI_LABEL_EXT = 31,
    UI_LABEL_BUTTON_EXT = 32,
    UI_CANVAS_EXT = 33,
    UI_CHART_PILLAR = 34,
    UI_CHART_POLYLINE = 35,
    UI_X_AXIS = 36,
    UI_Y_AXIS = 37,
    UI_LITE_SURFACE_VIEW = 38,
    LAYOUT = 39,
    LIST_LAYOUT = 40,
    FLEX_LAYOUT = 41,
    GRID_LAYOUT = 42,
    UI_EDIT_TEXT = 43,
#if ENABLE_SOFT_KEYBOARD
    UI_TEXT_PREVIEW_BOX = 44,
    UI_KEYBOARD_BUTTON = 45,
#endif
    UI_MENU_ITEM = 46,
    UI_CARD_PAGE = 47,
    UI_COVER_FLOW = 48,
    UI_SLIP_FLOW = 49,
    UI_FOLDABLE_VIEW = 50,
    UI_CROSS_VIEW = 51,
    UI_BARCODE = 52,
    UI_MAP_VIEW = 53,
    UI_KALEIDOSCOPE_VIEW = 54,
    UI_ROLLER_VIEW = 55,
    UI_HEXAGONS_LIST = 56,
    UI_IMAGE_PICKER = 57,
    UI_ICOSAHEDRON_VIEW = 58,
    UI_TRANSFORM_GROUP = 59,
    UI_TRANSFORM_LIST = 60,
    UI_COVER_FLOW_2 = 61,
    UI_WATERFALL_LIST = 62,
    UI_SPHERE_VIEW = 63,
    UI_PARTICLE_VIEW = 64,
    UI_PLANET_LIST = 65,
    UI_OPTION_BOX = 66,
    UI_CARD_CONTAINER = 67,
    UI_VIDEO = 68,
    UI_LOTT_VIEW = 69,
    UI_FLOAT_BOX_VIEW = 70,
    UI_CHART_PILLAR_EXT = 71,
    UI_CUSTOM_PLANET_LIST = 72,
    UI_LIST_EXT = 73,
    UI_LIST_NESTED = 74,
    UI_SCROLL_VIEW_NESTED = 75,
    UI_SWIPE_VIEW_NESTED = 76,
    UI_POST_EFFECT_IMAGE_VIEW = 77,
    UI_RAIN_VIEW = 78,
    UI_3D_VIEW = 79,
    UI_3D_MESH = 80,
    UI_3D_CYLINDER = 81,
    UI_3D_SPHERE = 82,
    UI_TRANSFORM_BUTTON = 83,
    UI_NUMBER_MAX = 84
};
枚举成员 取值 描述
UI_ROOT_VIEW 0 根视图
UI_VIEW_GROUP 1 视图组
UI_LABEL 2 标签
UI_ARC_LABEL 3 弧形标签
UI_LABEL_BUTTON 4 标签按钮
UI_CHECK_BOX 5 复选框
UI_TOGGLE_BUTTON 6 开关按钮
UI_RADIO_BUTTON 7 单选按钮
UI_IMAGE_VIEW 8 图片视图
UI_BOX_PROGRESS 9 条形进度条
UI_SLIDER 10 滑动条
UI_CIRCLE_PROGRESS 11 圆形进度条
UI_SCROLL_VIEW 12 滚动视图
UI_LIST 13 列表
UI_DIGITAL_CLOCK 14 数字时钟
UI_ANALOG_CLOCK 15 模拟时钟
UI_PICKER 16 选择器
UI_SWIPE_VIEW 17 滑动视图
UI_TIME_PICKER 18 时间选择器
UI_ABSTRACT_CLOCK 19 抽象时钟
UI_ABSTRACT_PROGRESS 20 抽象进度条
UI_ABSTRACT_SCROLL 21 抽象滚动
UI_AXIS 22 坐标轴
UI_BUTTON 23 按钮
UI_CANVAS 24 画布
UI_CHART 25 图表
UI_IMAGE_ANIMATOR_VIEW 26 图片动画视图
UI_REPEAT_BUTTON 27 重复按钮
UI_TEXTURE_MAPPER 28 纹理映射
UI_DIALOG 29 对话框
UI_QRCODE 30 二维码
UI_LABEL_EXT 31 扩展标签
UI_LABEL_BUTTON_EXT 32 扩展标签按钮
UI_CANVAS_EXT 33 扩展画布
UI_CHART_PILLAR 34 柱状图
UI_CHART_POLYLINE 35 折线图
UI_X_AXIS 36 X轴
UI_Y_AXIS 37 Y轴
UI_LITE_SURFACE_VIEW 38 轻量表面视图
LAYOUT 39 布局
LIST_LAYOUT 40 列表布局
FLEX_LAYOUT 41 弹性布局
GRID_LAYOUT 42 网格布局
UI_EDIT_TEXT 43 文本编辑框
UI_MENU_ITEM 46 菜单项
UI_CARD_PAGE 47 卡片页
UI_COVER_FLOW 48 封面流
UI_SLIP_FLOW 49 滑动流
UI_FOLDABLE_VIEW 50 可折叠视图
UI_CROSS_VIEW 51 交叉视图
UI_BARCODE 52 条形码
UI_MAP_VIEW 53 地图视图
UI_KALEIDOSCOPE_VIEW 54 万花筒视图
UI_ROLLER_VIEW 55 滚轮视图
UI_HEXAGONS_LIST 56 六边形列表
UI_IMAGE_PICKER 57 图片选择器
UI_ICOSAHEDRON_VIEW 58 二十面体视图
UI_TRANSFORM_GROUP 59 变换组
UI_TRANSFORM_LIST 60 变换列表
UI_COVER_FLOW_2 61 封面流2
UI_WATERFALL_LIST 62 瀑布流列表
UI_SPHERE_VIEW 63 球体视图
UI_PARTICLE_VIEW 64 粒子视图
UI_PLANET_LIST 65 行星列表
UI_OPTION_BOX 66 选项框
UI_CARD_CONTAINER 67 卡片容器
UI_VIDEO 68 视频
UI_LOTT_VIEW 69 Lottie动画视图
UI_FLOAT_BOX_VIEW 70 浮动框视图
UI_CHART_PILLAR_EXT 71 扩展柱状图
UI_CUSTOM_PLANET_LIST 72 自定义行星列表
UI_LIST_EXT 73 扩展列表
UI_LIST_NESTED 74 嵌套列表
UI_SCROLL_VIEW_NESTED 75 嵌套滚动视图
UI_SWIPE_VIEW_NESTED 76 嵌套滑动视图
UI_POST_EFFECT_IMAGE_VIEW 77 后效图片视图
UI_RAIN_VIEW 78 雨滴视图
UI_3D_VIEW 79 3D视图
UI_3D_MESH 80 3D网格
UI_3D_CYLINDER 81 3D圆柱
UI_3D_SPHERE 82 3D球体
UI_TRANSFORM_BUTTON 83 变换按钮
UI_NUMBER_MAX 84 视图类型最大值

Structures

ViewExtraMsg

视图附加信息结构体，用于存储视图的额外自定义数据，图形框架本身不使用此字段。

struct ViewExtraMsg {
    void* elementPtr;
};

成员说明

成员名称 数据类型 描述
elementPtr void* 附加信息指针，可指向任意自定义数据