root_view

root_view 模块提供窗口与根视图管理功能，包含窗口创建、事件分发、按键与手势监听等核心能力。

Class Summary

OHOS::Window

Window 前向声明类，用于窗口管理场景

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

OHOS::WindowImpl

WindowImpl 前向声明类，用于窗口实现场景

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

OHOS::RootView

视图树的根节点，管理子视图的添加、删除及事件分发

• 构造：无

• 成员函数：

  接口名称	功能简述
  AddHardwareLayer	添加硬件图层
  GetHardwareLayer	获取硬件图层
  ClearHardwareLayer	清除硬件图层
  GetInstance	获取 RootView 单例实例
  GetWindowRootView	获取绑定窗口的 RootView 实例
  DestroyWindowRootView	销毁绑定窗口的 RootView 实例
  GetViewType	获取视图类型
  OnKeyEvent	响应物理按键事件
  OnGestureEvent	响应手势事件
  SetOnKeyActListener	设置按键事件监听器
  ClearOnKeyActListener	清除按键事件监听器
  GetOnKeyActListener	获取按键事件监听器
  SetGestureListener	设置手势事件监听器
  ClearGestureListener	清除手势事件监听器
  GetGestureListener	获取手势事件监听器
  OnVirtualDeviceEvent	响应虚拟设备输入事件
  SetOnVirtualDeviceEventListener	设置虚拟设备事件监听器
  ClearOnVirtualDeviceEventListener	清除虚拟设备事件监听器
  FindSubView	检查目标视图是否为指定父视图的子视图
  GetBoundWindow	获取与 RootView 绑定的窗口
  DrawTop	绘制指定视图的顶层区域
  Measure	对所有子视图执行测量
  MeasureView	对指定视图执行测量
  UpdateBufferInfo	基于 FB 缓冲区信息更新绘图缓冲区
  SaveDrawContext	保存当前绘图上下文
  RestoreDrawContext	恢复之前保存的绘图上下文
  SetScreencapFlag	设置截屏标志
  SetBlurView	设置模糊视图
  ClearBlurView	清除模糊视图
  GetBlurView	获取当前模糊视图
  SetSnapshotFlag	设置快照标志
  GetSnapshotFlag	获取快照标志状态
  GetAppView	获取应用视图容器
  Add	向 RootView 添加子视图
  Insert	在指定视图后插入子视图
  Remove	从 RootView 移除子视图
  RemoveAll	移除 RootView 中所有子视图
  AddSystemView	添加系统视图
  RemoveSystemView	移除系统视图
  isSystemViewEmpty	检查系统视图是否为空

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

• 声明头文件：middleware/services/gui/uikit/ui/interfaces/kits/components/root_view.h
• 公有运算符：无
• 继承关系：UIViewGroup
• 嵌套类型：OnKeyActListener、OnGestureListener、OnVirtualDeviceEventListener、DrawContext
• 模板形参：无

OHOS::RootView::OnKeyActListener

按键事件监听器抽象基类，用于响应物理按键事件

• 构造：无

• 成员函数：

  接口名称	功能简述
  OnKeyAct	响应物理按键事件的回调接口

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

• 声明头文件：middleware/services/gui/uikit/ui/interfaces/kits/components/root_view.h
• 公有运算符：无
• 继承关系：HeapBase
• 嵌套类型：无
• 模板形参：无

OHOS::RootView::OnGestureListener

手势事件监听器抽象基类，用于响应手势事件

• 构造：无

• 成员函数：

  接口名称	功能简述
  OnGesture	响应手势事件的回调接口

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

• 声明头文件：middleware/services/gui/uikit/ui/interfaces/kits/components/root_view.h
• 公有运算符：无
• 继承关系：HeapBase
• 嵌套类型：无
• 模板形参：无

OHOS::RootView::OnVirtualDeviceEventListener

虚拟设备事件监听器抽象基类，用于响应虚拟设备输入事件

• 构造：无

• 成员函数：

  接口名称	功能简述
  OnVirtualDeviceEvent	响应虚拟设备输入事件的回调接口

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

• 声明头文件：middleware/services/gui/uikit/ui/interfaces/kits/components/root_view.h
• 公有运算符：无
• 继承关系：HeapBase
• 嵌套类型：无
• 模板形参：无

Functions

OHOS::Window

类 Window 仅有前向声明，无公有成员函数，不在 Functions 中输出类分组。

OHOS::WindowImpl

类 WindowImpl 仅有前向声明，无公有成员函数，不在 Functions 中输出类分组。

OHOS::RootView

AddHardwareLayer

void AddHardwareLayer(IHardwareView* view)

功能说明

• 将指定的硬件图层视图添加到 RootView
• 调用后硬件图层视图被记录，用于硬件加速渲染
• 重复调用会覆盖之前设置的硬件图层

入参

名称	参数类型	详细说明	约束取值范围
view	IHardwareView*	入参指针，指向待添加的硬件图层视图	非nullptr时指向有效的IHardwareView对象

Kconfig 配置

配置项	说明	默认值
VERSION_IOT	启用IoT版本硬件图层功能	n

GetHardwareLayer

IHardwareView* GetHardwareLayer()

功能说明

• 获取当前 RootView 中设置的硬件图层视图
• 用于查询当前绑定的硬件加速渲染目标
• 未设置硬件图层时返回 nullptr

返回值

• 返回类型：IHardwareView*

返回当前硬件图层视图指针

返回值	触发场景
非nullptr	已设置硬件图层视图
nullptr	未设置硬件图层视图

Kconfig 配置

配置项	说明	默认值
VERSION_IOT	启用IoT版本硬件图层功能	n

ClearHardwareLayer

void ClearHardwareLayer()

功能说明

• 清除当前 RootView 中设置的硬件图层视图
• 调用后硬件图层指针置空，不再进行硬件加速渲染
• 可与 AddHardwareLayer 配合使用以切换硬件图层

Kconfig 配置

配置项	说明	默认值
VERSION_IOT	启用IoT版本硬件图层功能	n

GetInstance

static RootView* GetInstance()

功能说明

• 获取 RootView 的全局单例实例
• 首次调用时自动构造单例对象，后续调用返回同一实例
• 单例生命周期贯穿整个应用运行期

返回值

• 返回类型：RootView*

返回 RootView 单例指针

返回值	触发场景
非nullptr	始终返回有效的单例指针

GetWindowRootView

static RootView* GetWindowRootView()

功能说明

• 创建并获取一个绑定到窗口的 RootView 实例
• 每次调用创建新的 RootView 对象，与 GetInstance 的单例实例独立
• 用于多窗口场景下各窗口拥有独立的 RootView

返回值

• 返回类型：RootView*

返回新创建的窗口绑定 RootView 实例

返回值	触发场景
非nullptr	新创建的 RootView 实例

Kconfig 配置

配置项	说明	默认值
ENABLE_WINDOW	启用窗口管理功能	n

DestroyWindowRootView

static bool DestroyWindowRootView(RootView* rootView)

功能说明

• 销毁通过 GetWindowRootView 创建的 RootView 实例
• 不允许销毁全局单例实例（GetInstance 返回的实例），此时返回 false
• 销毁成功后传入的指针不再有效，调用方不应再使用

入参

名称	参数类型	详细说明	约束取值范围
rootView	RootView*	入参指针，指向待销毁的窗口 RootView 实例	不得为 GetInstance() 返回的单例指针

返回值

• 返回类型：bool

返回销毁操作结果

返回值	触发场景
true(1)	销毁成功
false(0)	传入指针为单例实例，拒绝销毁

Kconfig 配置

配置项	说明	默认值
ENABLE_WINDOW	启用窗口管理功能	n

GetViewType

UIViewType GetViewType() const override

功能说明

• 获取当前视图的类型标识
• RootView 始终返回 UI_ROOT_VIEW
• 该函数为 const 成员函数，不修改对象状态

返回值

• 返回类型：UIViewType

返回视图类型标识

返回值	触发场景
UI_ROOT_VIEW	RootView 固有视图类型

OnKeyEvent

virtual void OnKeyEvent(const KeyEvent& event)

功能说明

• 响应物理按键事件，将其分发给已注册的按键事件监听器
• 若已设置 OnKeyActListener，则调用其 OnKeyAct 回调
• 若未设置监听器，该函数不执行任何操作

入参

名称	参数类型	详细说明	约束取值范围
event	const KeyEvent&	入参只读引用，待响应的物理按键事件	引用有效的 KeyEvent 对象

OnGestureEvent

virtual void OnGestureEvent(const GestureEvent& event)

功能说明

• 响应手势事件，将其分发给已注册的手势事件监听器
• 若已设置 OnGestureListener，则调用其 OnGesture 回调
• 若未设置监听器，该函数不执行任何操作

入参

名称	参数类型	详细说明	约束取值范围
event	const GestureEvent&	入参只读引用，待响应的手势事件	引用有效的 GestureEvent 对象

SetOnKeyActListener

void SetOnKeyActListener(OnKeyActListener* onKeyActListener)

功能说明

• 设置按键事件监听器，用于接收物理按键事件回调
• 调用后 OnKeyEvent 会将按键事件分发给该监听器
• 重复调用会覆盖之前设置的监听器

入参

名称	参数类型	详细说明	约束取值范围
onKeyActListener	OnKeyActListener*	入参指针，指向按键事件监听器对象	可为nullptr，传入nullptr等同于清除监听器

ClearOnKeyActListener

void ClearOnKeyActListener()

功能说明

• 清除已设置的按键事件监听器
• 调用后 OnKeyEvent 不再分发按键事件
• 等同于调用 SetOnKeyActListener(nullptr)

GetOnKeyActListener

OnKeyActListener* GetOnKeyActListener()

功能说明

• 获取当前设置的按键事件监听器
• 用于查询当前是否已注册按键事件监听器
• 未设置监听器时返回 nullptr

返回值

• 返回类型：OnKeyActListener*

返回当前按键事件监听器指针

返回值	触发场景
非nullptr	已设置按键事件监听器
nullptr	未设置按键事件监听器

SetGestureListener

void SetGestureListener(OnGestureListener* onGestureListener)

功能说明

• 设置手势事件监听器，用于接收手势事件回调
• 调用后 OnGestureEvent 会将手势事件分发给该监听器
• 重复调用会覆盖之前设置的监听器

入参

名称	参数类型	详细说明	约束取值范围
onGestureListener	OnGestureListener*	入参指针，指向手势事件监听器对象	可为nullptr，传入nullptr等同于清除监听器

ClearGestureListener

void ClearGestureListener()

功能说明

• 清除已设置的手势事件监听器
• 调用后 OnGestureEvent 不再分发手势事件
• 等同于调用 SetGestureListener(nullptr)

GetGestureListener

OnGestureListener* GetGestureListener()

功能说明

• 获取当前设置的手势事件监听器
• 用于查询当前是否已注册手势事件监听器
• 未设置监听器时返回 nullptr

返回值

• 返回类型：OnGestureListener*

返回当前手势事件监听器指针

返回值	触发场景
非nullptr	已设置手势事件监听器
nullptr	未设置手势事件监听器

OnVirtualDeviceEvent

virtual void OnVirtualDeviceEvent(const VirtualDeviceEvent& event)

功能说明

• 响应虚拟设备输入事件，将其分发给已注册的虚拟设备事件监听器
• 虚拟设备事件指非触控、非物理按键的输入事件
• 若未设置监听器，该函数不执行任何操作

入参

名称	参数类型	详细说明	约束取值范围
event	const VirtualDeviceEvent&	入参只读引用，待响应的虚拟设备输入事件	引用有效的 VirtualDeviceEvent 对象

SetOnVirtualDeviceEventListener

void SetOnVirtualDeviceEventListener(OnVirtualDeviceEventListener* onVirtualDeviceEventListener)

功能说明

• 设置虚拟设备事件监听器，用于接收虚拟设备输入事件回调
• 调用后 OnVirtualDeviceEvent 会将事件分发给该监听器
• 重复调用会覆盖之前设置的监听器

入参

名称	参数类型	详细说明	约束取值范围
onVirtualDeviceEventListener	OnVirtualDeviceEventListener*	入参指针，指向虚拟设备事件监听器对象	可为nullptr，传入nullptr等同于清除监听器

ClearOnVirtualDeviceEventListener

void ClearOnVirtualDeviceEventListener()

功能说明

• 清除已设置的虚拟设备事件监听器
• 调用后 OnVirtualDeviceEvent 不再分发事件
• 等同于调用 SetOnVirtualDeviceEventListener(nullptr)

FindSubView

static bool FindSubView(const UIView& parentView, const UIView* subView)

功能说明

• 检查目标视图是否为指定父视图的子视图
• 递归遍历父视图的子视图树进行查找
• 用于确认视图层级关系

入参

名称	参数类型	详细说明	约束取值范围
parentView	const UIView&	入参只读引用，指定的父视图	引用有效的 UIView 对象
subView	const UIView*	入参只读指针，待查找的目标子视图	可为nullptr，nullptr时返回false

返回值

• 返回类型：bool

返回查找结果

返回值	触发场景
true(1)	目标视图是指定父视图的子视图
false(0)	目标视图不是指定父视图的子视图；subView 为 nullptr

GetBoundWindow

Window* GetBoundWindow() const

功能说明

• 获取与当前 RootView 绑定的窗口对象
• 用于多窗口场景下查询 RootView 所属窗口
• 未绑定窗口时返回 nullptr

返回值

• 返回类型：Window*

返回绑定的窗口指针

返回值	触发场景
非nullptr	已绑定窗口
nullptr	未绑定窗口

Kconfig 配置

配置项	说明	默认值
ENABLE_WINDOW	启用窗口管理功能	n

DrawTop

void DrawTop(UIView* view, const Rect& rect)

功能说明

• 在指定矩形区域内绘制指定视图的顶层内容
• 用于局部刷新场景，仅重绘指定区域
• 当存在模糊视图时，绘制逻辑与常规渲染不同

入参

名称	参数类型	详细说明	约束取值范围
view	UIView*	入参指针，待绘制的视图	应指向有效的 UIView 对象
rect	const Rect&	入参只读引用，指定绘制区域矩形	应为有效的 Rect 区域

Measure

void Measure()

功能说明

• 对 RootView 下所有子视图执行测量操作
• 当存在无效区域时才执行测量
• 测量是渲染流程的前置步骤

MeasureView

void MeasureView(UIView* view)

功能说明

• 对指定视图及其子视图执行测量操作
• 递归遍历视图树，对每个可见视图调用 ReMeasure 和 UpdatePos
• 测量过程中会更新模糊视图状态

入参

名称	参数类型	详细说明	约束取值范围
view	UIView*	入参指针，待测量的视图	应指向有效的 UIView 对象

UpdateBufferInfo

void UpdateBufferInfo(BufferInfo* fbBufferInfo)

功能说明

• 基于 FB 缓冲区信息更新绘图缓冲区
• 用于帧缓冲区切换或更新场景
• 调用后绘图上下文中的缓冲区信息被更新

入参

名称	参数类型	详细说明	约束取值范围
fbBufferInfo	BufferInfo*	入参指针，指向帧缓冲区信息	应指向有效的 BufferInfo 对象

SaveDrawContext

void SaveDrawContext()

功能说明

• 保存当前绘图上下文信息
• 用于绘图上下文切换前保存现场
• 可与 RestoreDrawContext 配合使用实现上下文恢复

RestoreDrawContext

void RestoreDrawContext()

功能说明

• 恢复之前保存的绘图上下文信息
• 调用后绘图上下文恢复到保存时的状态

前置条件

• 调用时序约束：必须在 SaveDrawContext() 之后调用

SetScreencapFlag

void SetScreencapFlag()

功能说明

• 设置截屏标志，标记需要在下次渲染时执行截屏
• 截屏完成后标志自动重置为 false
• 用于 DFX 调试诊断场景

Kconfig 配置

配置项	说明	默认值
ENABLE_DFX_CMD	启用DFX调试命令功能	n

SetBlurView

bool SetBlurView(UIView* view)

功能说明

• 设置模糊视图，用于全屏模糊渲染场景
• 传入 nullptr 时直接返回 true 且不修改模糊视图栈
• 当模糊视图栈为空时直接入栈，非空时处理去重逻辑后入栈

入参

名称	参数类型	详细说明	约束取值范围
view	UIView*	入参指针，指向待设置的模糊视图	可为nullptr；非nullptr时应指向有效的 UIView 对象

返回值

• 返回类型：bool

返回设置结果

返回值	触发场景
true(1)	设置成功（传入nullptr时直接返回true；视图已在栈顶时返回true；正常入栈后返回true）

ClearBlurView

void ClearBlurView(UIView* view)

功能说明

• 从模糊视图栈中移除指定的模糊视图
• 若栈中存在该视图则移除，否则不执行操作
• 移除后模糊渲染不再应用于该视图

入参

名称	参数类型	详细说明	约束取值范围
view	UIView*	入参指针，指向待清除的模糊视图	应指向有效的 UIView 对象

GetBlurView

UIView* GetBlurView()

功能说明

• 获取当前生效的全屏模糊视图
• 用于查询当前是否有模糊视图正在生效
• 未设置模糊视图时返回 nullptr

返回值

• 返回类型：UIView*

返回当前模糊视图指针

返回值	触发场景
非nullptr	存在生效的模糊视图
nullptr	无模糊视图生效

SetSnapshotFlag

void SetSnapshotFlag(bool flag)

功能说明

• 设置快照标志，标记当前渲染帧是否为快照模式
• 快照模式下渲染行为可能有所不同
• 可与 GetSnapshotFlag 配合使用查询当前标志状态

入参

名称	参数类型	详细说明	约束取值范围
flag	bool	入参，快照标志值	true：启用快照模式；false：关闭快照模式

GetSnapshotFlag

bool GetSnapshotFlag()

功能说明

• 获取当前快照标志状态
• 用于查询当前渲染帧是否处于快照模式
• 与 SetSnapshotFlag 配合使用

返回值

• 返回类型：bool

返回快照标志状态

返回值	触发场景
true(1)	快照模式已启用
false(0)	快照模式未启用

GetAppView

UIViewGroup* GetAppView()

功能说明

• 获取应用视图容器，即 RootView 中用于承载应用层子视图的 ViewGroup
• 应用层子视图通过 Add/Insert/Remove 等接口操作的对象即为该容器
• 该容器的位置和大小与屏幕尺寸一致

返回值

• 返回类型：UIViewGroup*

返回应用视图容器指针

返回值	触发场景
非nullptr	始终返回有效的应用视图容器指针

Add

void Add(UIView* view) override

功能说明

• 向 RootView 的应用视图容器中添加子视图
• 重写 UIViewGroup::Add，实际操作目标为内部 appView_ 容器
• 添加后子视图将参与后续的测量与渲染流程

入参

名称	参数类型	详细说明	约束取值范围
view	UIView*	入参指针，指向待添加的子视图	应指向有效的 UIView 对象

Insert

void Insert(UIView* prevView, UIView* insertView) override

功能说明

• 在指定视图之后插入子视图到应用视图容器
• 重写 UIViewGroup::Insert，实际操作目标为内部 appView_ 容器
• 插入后新视图位于 prevView 之后

入参

名称	参数类型	详细说明	约束取值范围
prevView	UIView*	入参指针，前驱视图	可为nullptr
insertView	UIView*	入参指针，待插入的子视图	应指向有效的 UIView 对象

Remove

void Remove(UIView* view) override

功能说明

• 从应用视图容器中移除指定的子视图
• 重写 UIViewGroup::Remove，实际操作目标为内部 appView_ 容器
• 移除后该视图不再参与测量与渲染

入参

名称	参数类型	详细说明	约束取值范围
view	UIView*	入参指针，指向待移除的子视图	应指向有效的 UIView 对象

RemoveAll

void RemoveAll() override

功能说明

• 移除应用视图容器中的所有子视图
• 重写 UIViewGroup::RemoveAll，实际操作目标为内部 appView_ 容器
• 调用后应用视图容器不包含任何子视图

AddSystemView

void AddSystemView(UIView* view)

功能说明

• 向系统视图容器中添加系统级视图
• 系统视图与应用视图隔离，渲染层级独立
• 系统视图通常用于状态栏、导航栏等系统级 UI 元素

入参

名称	参数类型	详细说明	约束取值范围
view	UIView*	入参指针，指向待添加的系统视图	应指向有效的 UIView 对象

RemoveSystemView

void RemoveSystemView(UIView* view)

功能说明

• 从系统视图容器中移除指定的系统视图
• 移除后该系统视图不再参与渲染
• 与 AddSystemView 配合使用

入参

名称	参数类型	详细说明	约束取值范围
view	UIView*	入参指针，指向待移除的系统视图	应指向有效的 UIView 对象

isSystemViewEmpty

bool isSystemViewEmpty()

功能说明

• 检查系统视图容器是否为空
• 空表示当前无任何系统视图
• 用于查询系统视图的添加/移除状态

返回值

• 返回类型：bool

返回系统视图容器是否为空

返回值	触发场景
true(1)	系统视图容器中无任何子视图
false(0)	系统视图容器中存在子视图

OHOS::RootView::OnKeyActListener

OnKeyAct

virtual bool OnKeyAct(UIView& view, const KeyEvent& event) = 0

功能说明

• 响应物理按键事件的纯虚回调接口
• 由子类实现具体的按键响应逻辑
• 返回 true 表示事件已消费，不再向父视图传递

入参

名称	参数类型	详细说明	约束取值范围
view	UIView&	入参引用，触发按键事件的视图	引用有效的 UIView 对象
event	const KeyEvent&	入参只读引用，物理按键事件	引用有效的 KeyEvent 对象

返回值

• 返回类型：bool

返回事件是否被消费

返回值	触发场景
true(1)	按键事件已消费，不再传递
false(0)	按键事件未消费，继续传递

OHOS::RootView::OnGestureListener

OnGesture

virtual bool OnGesture(UIView& view, const GestureEvent& event) = 0

功能说明

• 响应手势事件的纯虚回调接口
• 由子类实现具体的手势响应逻辑
• 返回 true 表示事件已消费

入参

名称	参数类型	详细说明	约束取值范围
view	UIView&	入参引用，触发手势事件的视图	引用有效的 UIView 对象
event	const GestureEvent&	入参只读引用，手势事件	引用有效的 GestureEvent 对象

返回值

• 返回类型：bool

返回事件是否被消费

返回值	触发场景
true(1)	手势事件已消费，不再传递
false(0)	手势事件未消费，继续传递

OHOS::RootView::OnVirtualDeviceEventListener

OnVirtualDeviceEvent

virtual bool OnVirtualDeviceEvent(UIView& view, VirtualDeviceEvent event) = 0

功能说明

• 响应虚拟设备输入事件的纯虚回调接口
• 由子类实现具体的虚拟设备事件响应逻辑
• 虚拟设备事件指非触控、非物理按键的输入事件

入参

名称	参数类型	详细说明	约束取值范围
view	UIView&	入参引用，触发虚拟设备事件的视图	引用有效的 UIView 对象
event	VirtualDeviceEvent	入参，虚拟设备输入事件	有效的 VirtualDeviceEvent 枚举值

返回值

• 返回类型：bool

返回事件是否被消费

返回值	触发场景
true(1)	虚拟设备事件已消费
false(0)	虚拟设备事件未消费

Structures

DrawContext

struct DrawContext {
    BufferInfo* bufferInfo;
#if ENABLE_MAP_BUFFER
    BufferInfo* mapBufferInfo;
#endif
};

成员说明

成员名称	数据类型	描述
bufferInfo	BufferInfo*	目标绘图缓冲区信息
mapBufferInfo	BufferInfo*	目标动画绘图缓冲区信息（需 ENABLE_MAP_BUFFER 宏开启）