跳转至
项目
版本
全文检索

rect

rect 模块提供矩形区域功能，包含矩形坐标运算、交集/并集计算与包含判断等几何操作。

Class Summary

OHOS::CommonRect

定义矩形，包含矩形四条边界的位置数据，提供矩形的包含、相交、聚合等操作能力。

  • 构造：CommonRect(T left, T top, T right, T bottom)、CommonRect(const CommonRect<T>& other) = default、CommonRect(CommonRect<T>&& other) = default

  • 成员函数：

    接口名称 功能简述
    CommonRect 基于四条边界坐标构造矩形实例
    CommonRect 拷贝构造矩形实例
    CommonRect 移动构造矩形实例
    SetRect 设置矩形四条边界的坐标
    GetWidth 获取矩形宽度
    GetHeight 获取矩形高度
    GetX 获取矩形左边界坐标
    GetY 获取矩形上边界坐标
    GetLeft 获取矩形左边界坐标
    GetTop 获取矩形上边界坐标
    GetRight 获取矩形右边界坐标
    GetBottom 获取矩形下边界坐标
    SetX 改变左边界坐标且不改变矩形宽度
    SetY 改变上边界坐标且不改变矩形高度
    SetPosition 改变左边界和上边界坐标且不改变矩形宽高
    SetWidth 改变矩形宽度且不改变左边界坐标
    SetHeight 改变矩形高度且不改变上边界坐标
    SetLeft 设置矩形左边界坐标
    SetTop 设置矩形上边界坐标
    SetRight 设置矩形右边界坐标
    SetBottom 设置矩形下边界坐标
    Resize 设置矩形宽度和高度
    GetSize 获取矩形面积
    Intersect 计算两个矩形的交集并判断是否相交
    Join 计算包含两个矩形的最小矩形
    IsContains 判断矩形是否包含指定坐标点（Vector2）
    IsContains 判断矩形是否包含指定坐标点（Point）
    IsContains 判断矩形是否包含另一个矩形
    IsExtends 判断矩形是否与另一个矩形水平或垂直相邻
    IsIntersect 判断矩形是否与另一个矩形相交
    Inflate 按指定增量扩展矩形四条边界
    operator= 拷贝赋值运算符
    operator= 移动赋值运算符
    operator== 判断两个矩形是否相等
    Normalize 规范化矩形确保左不大于右、上不大于下
    IsValid 判断矩形是否有效
    JoinRect 计算两个有效矩形的并集矩形

  • 使用包含头文件：#include "gfx_utils/rect.h"

  • 声明头文件：middleware/services/gui/uikit/utils/interfaces/kits/gfx_utils/rect.h
  • 公有运算符：void operator=(const CommonRect<T>& other)、void operator=(const CommonRect<T>&& other)、bool operator==(const CommonRect<T>& other) const
  • 继承关系：HeapBase
  • 嵌套类型：无
  • 模板形参：typename T

Functions

OHOS::CommonRect

CommonRect(args...)

CommonRect(T left, T top, T right, T bottom)

功能说明

  • 基于四条边界的坐标值构造矩形实例
  • 调用者需确保传入的坐标值符合业务逻辑约束
  • 构造完成后即可直接调用其他成员函数进行矩形操作

入参

名称 参数类型 详细说明 约束取值范围
left T 左边界坐标 与模板参数 T 的取值范围一致
top T 上边界坐标 与模板参数 T 的取值范围一致
right T 右边界坐标 与模板参数 T 的取值范围一致
bottom T 下边界坐标 与模板参数 T 的取值范围一致

CommonRect(args...)

CommonRect(const CommonRect<T>& other) = default

功能说明

  • 拷贝构造矩形实例，基于另一个矩形的所有边界坐标创建新矩形
  • 拷贝后新矩形与原矩形各边界坐标完全一致
  • 默认拷贝构造，行为与编译器生成的逐成员拷贝一致

入参

名称 参数类型 详细说明 约束取值范围
other const CommonRect& 入参只读引用，待拷贝的源矩形 有效的 CommonRect 对象

CommonRect(args...)

CommonRect(CommonRect<T>&& other) = default

功能说明

  • 移动构造矩形实例，从另一个矩形接管边界坐标
  • 移动后源对象处于有效但未指定的状态
  • 默认移动构造，行为与编译器生成的逐成员移动一致

入参

名称 参数类型 详细说明 约束取值范围
other CommonRect&& 入参右值引用，用于移动语义的源矩形 有效的 CommonRect 右值对象

SetRect

void SetRect(T left, T top, T right, T bottom)

功能说明

  • 设置矩形四条边界的坐标值
  • 调用后矩形原有坐标被完全替换
  • 常用于重置矩形的位置和尺寸

入参

名称 参数类型 详细说明 约束取值范围
left T 左边界坐标 与模板参数 T 的取值范围一致
top T 上边界坐标 与模板参数 T 的取值范围一致
right T 右边界坐标 与模板参数 T 的取值范围一致
bottom T 下边界坐标 与模板参数 T 的取值范围一致

GetWidth

T GetWidth() const

功能说明

  • 获取矩形的宽度值
  • 宽度计算方式为右边界坐标减去左边界坐标加 1
  • const 成员函数，不修改对象状态

返回值

  • 返回类型：T

返回矩形宽度

返回值 触发场景
宽度值 矩形右边界大于等于左边界时返回正值；右边界小于左边界时可能返回负值或零

GetHeight

T GetHeight() const

功能说明

  • 获取矩形的高度值
  • 高度计算方式为下边界坐标减去上边界坐标加 1
  • const 成员函数，不修改对象状态

返回值

  • 返回类型：T

返回矩形高度

返回值 触发场景
高度值 矩形下边界大于等于上边界时返回正值；下边界小于上边界时可能返回负值或零

GetX

T GetX() const

功能说明

  • 获取矩形左边界的坐标值
  • 等价于 GetLeft，返回左边界坐标
  • const 成员函数，不修改对象状态

返回值

  • 返回类型：T

返回左边界坐标

返回值 触发场景
左边界坐标 始终返回 left_ 的当前值

GetY

T GetY() const

功能说明

  • 获取矩形上边界的坐标值
  • 等价于 GetTop，返回上边界坐标
  • const 成员函数，不修改对象状态

返回值

  • 返回类型：T

返回上边界坐标

返回值 触发场景
上边界坐标 始终返回 top_ 的当前值

GetLeft

T GetLeft() const

功能说明

  • 获取矩形左边界的坐标值
  • 与 GetX 功能相同，返回左边界坐标
  • const 成员函数，不修改对象状态

返回值

  • 返回类型：T

返回左边界坐标

返回值 触发场景
左边界坐标 始终返回 left_ 的当前值

GetTop

T GetTop() const

功能说明

  • 获取矩形上边界的坐标值
  • 与 GetY 功能相同，返回上边界坐标
  • const 成员函数，不修改对象状态

返回值

  • 返回类型：T

返回上边界坐标

返回值 触发场景
上边界坐标 始终返回 top_ 的当前值

GetRight

T GetRight() const

功能说明

  • 获取矩形右边界的坐标值
  • const 成员函数，不修改对象状态

返回值

  • 返回类型：T

返回右边界坐标

返回值 触发场景
右边界坐标 始终返回 right_ 的当前值

GetBottom

T GetBottom() const

功能说明

  • 获取矩形下边界的坐标值
  • const 成员函数，不修改对象状态

返回值

  • 返回类型：T

返回下边界坐标

返回值 触发场景
下边界坐标 始终返回 bottom_ 的当前值

SetX

void SetX(T x)

功能说明

  • 改变矩形左边界坐标，同时调整右边界以保持矩形宽度不变
  • 右边界坐标随左边界偏移量同步调整
  • 调用后矩形整体水平平移

入参

名称 参数类型 详细说明 约束取值范围
x T 新的左边界坐标 与模板参数 T 的取值范围一致

SetY

void SetY(T y)

功能说明

  • 改变矩形上边界坐标，同时调整下边界以保持矩形高度不变
  • 下边界坐标随上边界偏移量同步调整
  • 调用后矩形整体垂直平移

入参

名称 参数类型 详细说明 约束取值范围
y T 新的上边界坐标 与模板参数 T 的取值范围一致

SetPosition

void SetPosition(T x, T y)

功能说明

  • 同时改变矩形左边界和上边界坐标，保持矩形宽度和高度不变
  • 等价于依次调用 SetX 和 SetY
  • 调用后矩形整体平移到新位置

入参

名称 参数类型 详细说明 约束取值范围
x T 新的左边界坐标 与模板参数 T 的取值范围一致
y T 新的上边界坐标 与模板参数 T 的取值范围一致

SetWidth

void SetWidth(T width)

功能说明

  • 改变矩形宽度，左边界坐标不变，根据宽度重新计算右边界坐标
  • 右边界计算方式为左边界坐标加宽度减 1
  • 传入的宽度值应大于 0

入参

名称 参数类型 详细说明 约束取值范围
width T 新的矩形宽度 大于 0

SetHeight

void SetHeight(T height)

功能说明

  • 改变矩形高度，上边界坐标不变，根据高度重新计算下边界坐标
  • 下边界计算方式为上边界坐标加高度减 1
  • 传入的高度值应大于 0

入参

名称 参数类型 详细说明 约束取值范围
height T 新的矩形高度 大于 0

SetLeft

void SetLeft(T left)

功能说明

  • 设置矩形左边界的坐标值
  • 仅修改左边界，不影响其他边界
  • 调用后矩形宽度可能改变

入参

名称 参数类型 详细说明 约束取值范围
left T 左边界坐标 与模板参数 T 的取值范围一致

SetTop

void SetTop(T top)

功能说明

  • 设置矩形上边界的坐标值
  • 仅修改上边界，不影响其他边界
  • 调用后矩形高度可能改变

入参

名称 参数类型 详细说明 约束取值范围
top T 上边界坐标 与模板参数 T 的取值范围一致

SetRight

void SetRight(T right)

功能说明

  • 设置矩形右边界的坐标值
  • 仅修改右边界，不影响其他边界
  • 调用后矩形宽度可能改变

入参

名称 参数类型 详细说明 约束取值范围
right T 右边界坐标 与模板参数 T 的取值范围一致

SetBottom

void SetBottom(T bottom)

功能说明

  • 设置矩形下边界的坐标值
  • 仅修改下边界，不影响其他边界
  • 调用后矩形高度可能改变

入参

名称 参数类型 详细说明 约束取值范围
bottom T 下边界坐标 与模板参数 T 的取值范围一致

Resize

void Resize(T width, T height)

功能说明

  • 同时设置矩形的宽度和高度，左边界和上边界坐标不变
  • 右边界根据左边界和宽度重新计算，下边界根据上边界和高度重新计算
  • 传入的宽度和高度值均应大于 0

入参

名称 参数类型 详细说明 约束取值范围
width T 新的矩形宽度 大于 0
height T 新的矩形高度 大于 0

GetSize

uint32_t GetSize() const

功能说明

  • 获取矩形的面积值
  • 面积计算方式为宽度乘以高度
  • const 成员函数，不修改对象状态

返回值

  • 返回类型：uint32_t

返回矩形面积

返回值 触发场景
面积值 矩形有效时返回正值；无效矩形可能返回 0

Intersect

bool Intersect(const CommonRect<T>& rect1, const CommonRect<T>& rect2)

功能说明

  • 计算两个矩形的交集，将结果存入当前矩形
  • 若任一输入矩形无效或两矩形不相交，当前矩形被重置为零值矩形
  • 修改当前对象状态，将交集结果写入当前矩形的四条边界

入参

名称 参数类型 详细说明 约束取值范围
rect1 const CommonRect& 入参只读引用，第一个待计算交集的矩形 有效的 CommonRect 对象
rect2 const CommonRect& 入参只读引用，第二个待计算交集的矩形 有效的 CommonRect 对象

返回值

  • 返回类型：bool

返回两矩形是否相交

返回值 触发场景
true 两矩形存在交集区域
false 两矩形不相交或任一输入矩形无效

Join

void Join(const CommonRect<T>& rect1, const CommonRect<T>& rect2)

功能说明

  • 计算包含两个矩形的最小矩形，将结果存入当前矩形
  • 取两个矩形各边界坐标的最小值和最大值进行合并
  • 不检查输入矩形的有效性

入参

名称 参数类型 详细说明 约束取值范围
rect1 const CommonRect& 入参只读引用，第一个待合并的矩形 CommonRect 对象
rect2 const CommonRect& 入参只读引用，第二个待合并的矩形 CommonRect 对象

IsContains

bool IsContains(const Vector2<T>& point) const

功能说明

  • 判断当前矩形是否包含指定的二维向量坐标点
  • 判断条件为点的 x 和 y 坐标均在矩形边界范围内
  • const 成员函数，不修改对象状态

入参

名称 参数类型 详细说明 约束取值范围
point const Vector2& 入参只读引用，待判断的坐标点 有效的 Vector2 对象

返回值

  • 返回类型：bool

返回矩形是否包含该坐标点

返回值 触发场景
true 坐标点在矩形边界范围内（含边界）
false 坐标点不在矩形边界范围内

IsContains

bool IsContains(const Point& point) const

功能说明

  • 判断当前矩形是否包含指定的 Point 坐标点
  • 判断条件为点的 x 和 y 坐标均在矩形边界范围内
  • const 成员函数，不修改对象状态

入参

名称 参数类型 详细说明 约束取值范围
point const Point& 入参只读引用，待判断的坐标点 有效的 Point 对象

返回值

  • 返回类型：bool

返回矩形是否包含该坐标点

返回值 触发场景
true 坐标点在矩形边界范围内（含边界）
false 坐标点不在矩形边界范围内

IsContains

bool IsContains(const CommonRect<T>& other) const

功能说明

  • 判断当前矩形是否完全包含另一个矩形
  • 判断条件为另一矩形的四条边界均在当前矩形边界范围内
  • const 成员函数，不修改对象状态

入参

名称 参数类型 详细说明 约束取值范围
other const CommonRect& 入参只读引用，待判断的矩形 有效的 CommonRect 对象

返回值

  • 返回类型：bool

返回当前矩形是否包含另一矩形

返回值 触发场景
true 另一矩形的四条边界均在当前矩形范围内
false 另一矩形未被当前矩形完全包含

IsExtends

bool IsExtends(const CommonRect<T>& other) const

功能说明

  • 判断当前矩形是否与另一个矩形在水平或垂直方向上相邻
  • 相邻条件为两矩形一边对齐且另一方向上恰好相接（间距为 1）
  • const 成员函数，不修改对象状态

入参

名称 参数类型 详细说明 约束取值范围
other const CommonRect& 入参只读引用，待判断的矩形 有效的 CommonRect 对象

返回值

  • 返回类型：bool

返回两矩形是否相邻

返回值 触发场景
true 两矩形水平或垂直方向相邻
false 两矩形不相邻

IsIntersect

bool IsIntersect(const CommonRect<T>& other) const

功能说明

  • 判断当前矩形是否与另一个矩形相交
  • 相交判断基于两矩形的边界重叠关系
  • const 成员函数，不修改对象状态

入参

名称 参数类型 详细说明 约束取值范围
other const CommonRect& 入参只读引用，待判断的矩形 有效的 CommonRect 对象

返回值

  • 返回类型：bool

返回两矩形是否相交

返回值 触发场景
true 两矩形存在重叠区域
false 两矩形不存在重叠区域

Inflate

void Inflate(T delta)

功能说明

  • 按指定增量扩展矩形的四条边界
  • 左边界和上边界减去增量，右边界和下边界加上增量
  • 调用后矩形各方向均向外扩展

入参

名称 参数类型 详细说明 约束取值范围
delta T 扩展增量值 与模板参数 T 的取值范围一致

operator=

void operator=(const CommonRect<T>& other)

功能说明

  • 拷贝赋值运算符，将另一个矩形的四条边界坐标赋值给当前矩形
  • 赋值后当前矩形与源矩形各边界坐标完全一致
  • 修改当前对象状态

入参

名称 参数类型 详细说明 约束取值范围
other const CommonRect& 入参只读引用，待赋值的源矩形 有效的 CommonRect 对象

operator=

void operator=(const CommonRect<T>&& other)

功能说明

  • 移动赋值运算符，从另一个矩形接管边界坐标
  • 移动后源对象处于有效但未指定的状态
  • 修改当前对象状态

入参

名称 参数类型 详细说明 约束取值范围
other const CommonRect&& 入参右值引用，用于移动语义的源矩形 有效的 CommonRect 右值对象

operator==

bool operator==(const CommonRect<T>& other) const

功能说明

  • 判断当前矩形是否与另一个矩形相等
  • 相等条件为四条边界坐标完全相同
  • const 成员函数，不修改对象状态

入参

名称 参数类型 详细说明 约束取值范围
other const CommonRect& 入参只读引用，待比较的矩形 有效的 CommonRect 对象

返回值

  • 返回类型：bool

返回两矩形是否相等

返回值 触发场景
true 四条边界坐标完全相同
false 至少一条边界坐标不同

Normalize

void Normalize()

功能说明

  • 规范化矩形，确保左边界不大于右边界、上边界不大于下边界
  • 若左边界大于右边界，交换两者；若上边界大于下边界，交换两者
  • 调用后矩形各边界满足 left_ <= right_ 且 top_ <= bottom_

IsValid

bool IsValid() const

功能说明

  • 判断矩形是否有效
  • 有效条件为右边界不小于左边界、下边界不小于上边界、且矩形面积不为零
  • const 成员函数，不修改对象状态

返回值

  • 返回类型：bool

返回矩形是否有效

返回值 触发场景
true 矩形有效（右边界 >= 左边界，下边界 >= 上边界，面积 > 0）
false 矩形无效

JoinRect

void JoinRect(const CommonRect<T>& rect1, const CommonRect<T>& rect2)

功能说明

  • 计算两个有效矩形的并集矩形，将结果存入当前矩形
  • 若两个矩形均无效，当前矩形被重置为零值矩形；若仅一个有效，当前矩形取该有效矩形
  • 两个矩形均有效时等价于 Join 操作

入参

名称 参数类型 详细说明 约束取值范围
rect1 const CommonRect& 入参只读引用，第一个待合并的矩形 CommonRect 对象
rect2 const CommonRect& 入参只读引用，第二个待合并的矩形 CommonRect 对象

Type definitions

Rect 

using Rect = CommonRect<int16_t>;

使用说明：int16_t 模板实例化的 CommonRect，为 GUI 布局和绘制中最常用的矩形类型

Rect32 

using Rect32 = CommonRect<int32_t>;

使用说明：int32_t 模板实例化的 CommonRect，用于需要更大坐标范围的矩形操作场景