CRgn

CRgn 类封装了一个 W indows 图形设备接口（ GD I）区域。这一区域是某一窗口中的一个椭圆或多边形区域。要使用这个区域，你可以使用类 CRgn 的成员函数以及被定义为类 CDC 的成员函数的剪贴函数。

#include <afxwin.h>

CRgn 类成员

Construction

CRgn 构造一个 CRgn 对象

Initialization

CreateRectRgn 用一个矩形区域来初始化一个 CRgn 对象

CreateRectRgnIndire ct

用由一个 RECT 结构定义的矩形区域来初始化一个

CRgn 对象

CreateEllipticRgn 用一个椭圆形区域来初始化一个 CRgn 对象

CreateEllipticRgnInd irect

用由一个 RECT 结构定义的椭圆形区域来初始化一个 CRgn 对象

CreatePolygonRgn 用一个多边形区域来初始化一个 CRgn 对象。如果

有必要，系统通过在第一个顶点和最后一个顶点之间绘制直线来自动关闭该多边形

CreatePolyPolygonR gn

用一系列封闭的多边形组成的区域来初始化一个

CRgn 对象。这些多边形可能互不相交或相互重叠

CreateRoundRectRgn 用一个圆角的矩形区域来初始化一个 CRgn 对象

CombineRgn 设置一个 CRgn 对象，使它等效于两个指定的 CRgn

对象的联合

CopyRgn 设置一个 CRgn 对象，使它为一个指定的 CRgn 对

象的拷贝

CreateFromPath 从被选入给定设备环境的路径创建一个区域

CreateFromData 根据给定的区域和变换数据创建一个区域

Operations

EqualRgn 检查两个 CRgn 对象，确定它们是否相等

FromHandle 当给定了一个 W indows 区域的句柄时返回指向一个

CRgn 对象的指针

GetRegionData 用描述给定区域的数据来填充指定的缓冲区

GetRgnBox 检取一个 CRgn 对象的限定矩形的坐标

O ffsetRgn 用指定的偏移量移动一个 CRgn 对象

PtInRegion 确定一个指定的点是否在矩形内

RectInRegion 确定一个指定矩形的任何部分是否都在区域的边界

内

SetRectRgn 将 CRgn 对象设置为指定的矩形区域

Operators

OperatorHRGN 返回包含在 CRgn 对象中的 W indows 句柄

成员函数

CRgn ::Comb ineRgn

int CombineRgn( CRgn* pRgn1 , CRgn* pRgn2 , int nCombineMode );

返回值

返回最后结果区域的类型。它可以是下列值之一：

COMPLEXREGION 新区域具有相互重叠的边界。
ERROR 未创建新区域。
NULLREGION 新区域为空。
SIMPLEREGION 新区域没有相互重叠的边界。

参数

pRgn1

表示一个已经存在的区域。

pRgn2

表示一个已经存在的区域。

nCombineMode

指定当组合两个源区域时要执行的操作。它可以是下列值之一：

RGN_AND 使用两个区域互相重叠的区域（相交区域）。
RGN_COPY 创建区域 1 （由 pRgn1 标识）的一个拷贝
RGN_DIEF 创建一个区域，该区域由区域 1 （由 pRgn1 标

识）的不是区域 2 （由 pRgn2 标识）的那一部分区域组成。
RGN_OR 组合两个区域的整个部分（两个区域的并）。
RGN_XOR 组合两个区域，但去掉相互重叠的区域。

说明

此成员函数通过组合两个已有的区域来创建一个新的 GDI 区域。所组合成的区域就像 nCombineMode 所指定的一样。

两个指定的区域被组合，所得到的结果区域的句柄被保存在 CRgn 对象中。因此，不管 CRgn 中原来保存的区域是什么，都将被合并后的区域所代替。

区域的大小被限制在 32767 × 32767 个逻辑单位和 64K 内存这两个值中较小的

那个值的范围内。

使用 CopyRgn 只是简单地将一个区域拷贝到另一个区域。

请参阅 CRgn::CopyRgn, ::CombineRgn

CRgn ::CopyRgn

int CopyRgn( CRgn* pRgnSrc );

返回值

返回最后结果区域的类型。它可以是下列值之一：

COMPLEXREGION 新区域具有相互重叠的边界。
ERROR 未创建新区域。
NULLREGION 新区域为空。
SI MPLEREGION 新区域没有相互重叠的边界。

参数

pRgnSrc

标识一个已有的区域。

说明

此成员函数用来将一个由 pRgnSrc 定义的区域拷贝到 CRgn 对象中。新的区域将代替 CRgn 对象中原来保存的区域。此函数是 CombineRgn 成员函数的一个特例。

请参阅 C Rgn::CombineRgn, ::CombineRgn

CRgn ::CreateEllipticRgn

BOOL CreateEllipticRgn( int x1 , int y1 , int x2 , int y2 );

返回值

如果操作成功则返回非零值；否则返回 0 。

参数

指定椭圆的边界矩形的左上角的逻辑 x 坐标。

指定椭圆的边界矩形的左上角的逻辑 y 坐标。

指定椭圆的边界矩形的右下角的逻辑 x 坐标。

指定椭圆的边界矩形的右下角的逻辑 y 坐标。

说明

此成员函数用来创建一个椭圆形区域。该区域由用 x1 ， y1 ， x2 ，和 y2 指定的边界矩形来定义。该区域保存在 CRgn 对象中。

区域的大小被限制在 32767 × 32767 个逻辑单位和 64K 内存这两个值中较小的那个值的范围内。

当使用完了由 CreateEllipticRgn 函数创建的区域时，应用程序应该将此区域选择出设备环境外，并用 DeleteObject 函数来删除它。

请参阅 CRgn::CreateEllipticRgnIndirect, ::CreateEllipticRgn

CRgn ::CreateEllipticRgnIndirect

BOOL CreateEllipticRgnIndirect( LPCRECT lpRect );

返回值

如果操作成功则返回非零值；否则返回 0 。

参数

lpRect

指向一个 RECT 结构或一个 CRect 对象，该结构或对象包含了椭圆的边界矩形的左上角和右下角的逻辑坐标。

说明

此成员函数用来创建一个椭圆形区域。该区域由用 lpRect 指向的结构或对象定

义，它保存在 CRgn 对象中。

区域的大小被限制在 32767 × 32767 个逻辑单位和 64K 内存这两个值中较小的那个值的范围内。

当使用完了由 CreateEllipticRgnIndirect 函数创建的区域时，应用程序应该将此区域选择出设备环境外，并用 DeleteObject 函数来删除它。

请参阅 C Rgn::CreateEllipticRgn, ::CreateEllipticRgnIndirect

CRgn ::CreateFromData

BOOL CreateFromData( const XFORM* lpXForm , int nCoun t, const RGNDATA*

pRgnData );

返回值

如果函数成功则返回非零值；否则返回 0 。

参数

lpXForm

指向一个 XFORM 数据结构，该数据结构定义了要在区域中实现的变换。如果这个指针是 NULL ，则将使用相同的变换。

nCount

指定由 pRgnData 指向的结构的字节数。

pRgnData

指向一个 RGNDATA 数据结构，该数据结构包含了区域数据。

说明

此成员函数从给定的区域和变换数据创建一个区域。应用程序可以通过调用函数 CRgn::GetRegionData 来获取一个区域的数据。

请参阅 C Rgn::GetRegionData, ::ExtCreateRegion

CRgn ::CreateF romPath

BOOL CreateFromPath( CDC* pDC );

返回值

如果函数成功则返回非零值；否则返回 0 。

参数

pDC

标识包含有一条闭合路径的设备环境。

说明

此成员函数从被选入给定设备环境的路径创建一个区域。由 pDC 标识的设备环境中必须包含有一条闭合的路径。在 CreateFromPath 把一条路径转换为一个区

域后， W indows 从该设备环境中丢弃此闭合路径。

请参阅 C DC::BeginPath, CDC::EndPath, CDC::SetPolyFillMode

CRgn ::CreatePolygonRgn

BOOL CreatePolygonRgn( LPPOINT lpPoints , int nCount, int nMode );

返回值

如果操作成功则返回非零值；否则返回 0 。

参数

lpPoints

指向一个 POINT 结构数组，或指向一个 CPoint 对象数组。每一个结构指定多边形的一个顶点的 x 坐标和 y 坐标。 POINT 结构具有下面这样的

形式：

typedef struct tagPOINT{ int x;

int y;

} POINT;

nCount

指定由 lpPoints 指向的数组中的 POINT 结构或 CPoint 对象的数目。

nMode

指定区域的填充模式。这个参数可以是 ALTERNATE 或 W IN D IN G 。

说明

此成员函数创建一个多边形区域。如果必要，系统通过从多边形的最后一个顶点到第一个顶点绘制一条直线来关闭此多边形。创建出的多边形区域被保存在CR gn 对象中。

区域的大小被限制在 32767 × 32767 个逻辑单位和 64K 内存这两个值中较小的那个值的范围内。

当多边形的填充模式是 ALTERNATE 时，系统在每条扫描线上填充第奇数条边与第偶数条边之间的区域。也就是说，系统将填充第 1 条边和第 2 条边之间的区域；第 3 条边和第 4 条边之间的区域，等等。

当多边形的填充模式时 W INDING 时，系统使用绘图的方向来决定是否填充一个区域。多边形中的线段不是以顺时针方向就是以逆时针方向绘制的。一旦从一个封闭区域内向一个图形之外画的假想线穿过了一条顺时针线段时，便将某一计数值加 1 ；若这条线穿过了一条逆时针线段，则将计数值减 1 。当假想线到达图形之外时，若计数值为非零，则区域被填充。

当使用完了由 CreatePolygonRgn 函数创建的区域时，应用程序应该将此区域选择出设备环境外，并用 DeleteObject 函数来删除它。

请参阅 C Rgn::CreatePolyPolygonRgn, ::CreatePolygonRgn

CRgn ::CreatePolyPolygonRgn

BOOL CreatePolyPolygonRgn( LPPOINT lpPoints , LPINT lpPolyCounts , int

nCount ,

int nPolyFillMode );

返回值

如果操作成功则返回非零值；否则返回 0 。

参数

lpPoints

指向一个 POINT 结构数组，或指向一个 CPoint 对象数组，该结构或对象定义了多边形的顶点。每一个多边形都必须被显式地关闭，因为系统不会自动地关闭它们。多边形被连续指定。 POINT 结构具有下面这样的

形式：

typedef struct tagPOINT{ int x;

int y;

} POINT;

lpPolyCounts

指向一个整数数组。第一个整数指定 lpPoints 数组中的第一个多边形的顶点数，第二个整数指定 lpPoints 数组中的第二个多边形的顶点数，如此等等。

nCount

指定 lpPolyCounts 数组中的整数的总数。

nPolyFillMode

指定多边形填充模式。这个值可以是 ALTERNATE 或 W IN D IN G 。

说明

此成员函数用来创建一个包含一系列封闭多边形的区域。获得的结果矩形被保存在 CRgn 对象中。

这些多边形可能是互相分开的，或可能时相互重叠的。

区域的大小被限制在 32767 × 32767 个逻辑单位和 64K 内存这两个值中较小的那个值的范围内。

当多边形的填充模式是 W INDING 时，系统使用绘图的方向来决定是否填充一个区域。多边形中的线段不是以顺时针方向就是以逆时针方向绘制的。一旦从

一个封闭区域内向一个图形之外画的假想线穿过了一条顺时针线段时，便将某一计数值加 1 ；若这条线穿过了一条逆时针线段，则将计数值减 1 。当假想线到达图形之外时，若计数值为非零，则区域被填充。

当使用完了由 CreatePolyPolygonRgn 函数创建的区域时，应用程序应该将此区域选择为设备环境外，并用 CGDIObject::DeleteObject 函数来删除它。

请参阅 CRgn::CreatePolygonRgn, CDC ::SetPolyFill Mode, ::CreatePolyPolygonRgn

CRgn ::CreateRectRgn

BOOL CreateRectRgn( int x1 , int y1 , int x2 , int y2 );

返回值

如果操作成功则返回非零值；否则返回 0 。

参数

指定区域的左上角的逻辑 x 坐标。

指定区域左上角的逻辑 y 坐标。

指定区域右下角的逻辑 x 坐标。

指定区域的右下角的逻辑 y 坐标。

说明

此成员函数用来创建一个矩形区域，该区域被保存在 CRgn 对象中。

区域的大小被限制在 32767 × 32767 个逻辑单位和 64K 内存这两个值中较小的

那个值的范围内。

当使用完了由 CreateRectRgn 函数创建的区域时，应用程序应该将此区域选择出设备环境外，并用 CGDIObject::DeleteObject 函数来删除它。

请参阅 CRgn::CreateRectRgnIndirect, CRgn::CreateRoundRectRgn, ::CreateRectRgn

CRgn ::CreateRectRgnIndirect

BOOL CreateRectRgnIndirect( LPCRECT lpRect );

返回值

如果操作成功则返回非零值；否则返回 0 。

参数

lpRect

指向一个 RECT 结构或 CRect 对象，该结构或对象包含了区域的左上角和右下角的逻辑坐标。 RECT 结构具有下面的格式：

typedef struct tagRECT { int left;

int top; int right;

int bottom;

} RECT;

说明

此成员函数用来创建一个矩形区域，该区域被保存在 CRgn 对象中。

区域的大小被限制在 32767 × 32767 个逻辑单位和 64K 内存这两个值中较小的那个值的范围内。

当使用完了由 CreateRectRgn Indirect 函数创建的区域时，应用程序应该将此区域选择出设备环境外，并用 CGDIObject::DeleteObject 成员函数来删除它。

请参阅 CRgn::CreateRectRgn, CRgn::CreateRoundRectRgn, ::CreateRectRgnIndirect

CRgn ::CreateRoundRectRgn

BOOL CreateRoundRectRgn( int x1 , int y1 , int x2 , int y2 , int x3 , int y3 );

返回值

如果操作成功则返回非零值；否则返回 0 。

参数

指定区域的左上角的逻辑 x 坐标。

指定区域左上角的逻辑 y 坐标。

指定区域右下角的逻辑 x 坐标。

指定区域的右下角的逻辑 y 坐标。

指定用来创建圆角的椭圆的宽度。

指定用来创建圆角的椭圆的高度。。

说明

此成员函数用来创建一个具有圆角的矩形区域。

区域的大小被限制在 32767 × 32767 个逻辑单位和 64K 内存这两个值中较小的

那个值的范围内。

当使用完了由 CreateRoundRectRgn 函数创建的区域时，应用程序应该将此区域选择出设备环境外，并用 CGDIObject::DeleteObject 函数来删除它。

请参阅 CRgn::CreateRectRgn, CRgn::CreateRectRgnIndirect, ::CreateRoundRectRgn

CRgn ::CRgn

CRgn();

说明

此成员函数用来构造一个 CRgn 对象。在未使用 CRgn 中的某一个或几个成员函数来初始化该 CRgn 对象之前， m_hObject 数据成员中不含由一个有效的W indows GDI 区域。

BOOL EqualRgn( CRgn* pRgn ) const;

返回值

如果两个区域相等则返回非零值；否则返回 0 。

参数

pRgn

标识一个区域。

说明

此成员函数用来确定给定的矩形与 CRgn 对象中保存的矩形是否相等。

请参阅 ::EqualRgn

static CRgn* PASCAL FromHandle( HRGN hRgn );

返回值

如果函数成功则返回一个指向 CRgn 对象的指针。如果函数不成功，则返回值为 NULL 。

参数

hRgn

指定一个 W indows 区域的句柄。

说明

当给出了一个 Windows 区域句柄时，此成员函数返回一个指向 CRgn 对象的指

。如果还没有一个 CRgn 对象连接到这个句柄上，则创
建一个临时 CRgn 对象并将它连接到句柄上。这一临时的 CRgn 对象将一直有效，直到应用程序在其事件循环中再次有空闲时间为止。此时，所有的临时图形对象都将被删除。也就是说，该临时对象仅在处理一条窗口消息的过程中有效。

CRgn ::GetRegionData

Int GetRegionData( LPRGNDATA lpRgnData , int nCount ) const;

返回值

指定结果区域的类型。它可以是下列值之一：

COMPLEXREGION 新区域具有相互重叠的边界。
ERROR 未创建新区域。
NULLREGION 新区域为空。
SI MPLEREGION 新区域没有相互重叠的边界。

参数

lpRgnData

指向一个 RGNDATA 数据结构，该结构用来接收信息。如果这个参数是

NULL ，则返回值包含了此区域数据的字节数。

nCount

指定 lpRgnData 缓冲的用字节表示的大小。

说明

此成员函数用描述区域的数据来填充指定的缓存。这些数据包括组成该区域的矩形的尺寸。此函数常与 CRgn::CreateFromData 函数连用。

请参阅 CRgn::CreateFromData

CRgn ::GetRgnBox

int GetRgnBox( LPRECT lpRect ) const;

返回值

指定结果区域的类型。它可以是下列值之一：

COMPLEXREGION 新区域具有相互重叠的边界。
ERROR 未创建新区域。
NULLREGION 新区域为空。
SI MPLEREGION 新区域没有相互重叠的边界。

参数

lpRect

指向一个 RECT 结构或 CRect 对象，该结构或对象包含了区域的左上角

和右下角的逻辑坐标。 RECT 结构具有下面的格式：

typedef struct tagRECT { int left;

int top; int right;

int bottom;

} RECT;

说明

此成员函数用来获取 CRgn 对象的边界矩形的坐标。

请参阅 ::GetRgnBox

CRgn ::O ffsetRgn

int OffsetRgn( int x , int y ); int OffsetRgn( POINT point );

返回值

指定结果区域的类型。它可以是下列值之一：

COMPLEXREGION 新区域具有相互重叠的边界。

ERROR 未创建新区域。
NULLREGION 新区域为空。
SIMPLEREGION 新区域没有相互重叠的边界。

参数

指定向左或向右移动的单位数。

指定向上或向下移动的单位数。

此参数的 x 坐标指定向左或向右移动的单位数。其 y 坐标指定向上或向下移动的单位数。此参数可以是一个 POINT 结构或一个 CPoint 对象。

说明

此成员函数用来将保存在 CRgn 对象中的区域移动指定的偏移。此函数将区域沿 x 轴移动 x 个单位，沿 y 轴移动 y 个单位。

区域的坐标值必须小于或等于 32,767 ，但大于或等于 -32,768 。要谨慎地选择 x

和 y 参数，以避免无效的区域坐标。

请参阅 ::OffsetRgn

CRgn ::PtInRegion

BOOL PtInRegion( int x , int y ) const;

返回值

如果点在区域内则返回非零值；否则返回 0 。

参数

指定要测试的点的 x 坐标。

指定要测试的点的 y 坐标。

point

此参数的 x 坐标和 y 坐标指定了要测试的点的 x 坐标和 y 坐标。此 point

参数或者是一个 point 结构或是一个 C P oint 对象。

说明

此成员函数用来检查由 x 和 y 给定的点是否在保存在 CRgn 对象中的区域的内部。

请参阅 ::PtInRegion

CRgn ::RectInRegion

BOOL RectInRegion( LPCRECT lpRect ) const;

返回值

如果指定矩形的任何一部分在区域的边界内，则返回非零值；否则返回 0 。

参数

lpRect

指向一个 RECT 结构或 CRect 对象，该结构或对象包含了区域的左上角和右下角的逻辑坐标。 RECT 结构具有下面的格式：

typedef struct tagRECT { int left;

int top;

int right; int bottom;

} RECT;

说明

此成员函数用来确定由 lpRect 指定的矩形的任何一部分是否在保存在 CRgn 对象中的区域的边界之内。

请参阅 ::RectInRegion

CRgn :: SetRectRgn

void SetRectRgn( int x1 , int y1 , int x2 , int y2 ); void SetRectRgn( LPCRECT lpRect );

参数

指定矩形区域的左上角的逻辑 x 坐标。

指定矩形区域左上角的逻辑 y 坐标。

指定矩形区域右下角的逻辑 x 坐标。

指定矩形区域的右下角的逻辑 y 坐标。

lpRect

指定一个矩形区域。该参数可以是一个指向 RECT 结构或一个 CRect 对象

的指针。

说明

此成员函数用来创建一个矩形区域。但是它与 CreateRectRgn 不一样，此函数不从局部 W indows 应用程序堆中分配任何附加的内存。此函数使用为存放在CRgn 对象中的区域分配的空间。这就意味着在调用 SetRectRgn 函数之前必须使用一个有效的 W indows 区域将该 CRgn 对象初始化。由参数 x1 ， x2 ， y1 ，和y2 指定的两个点指定已分配的空间的最小尺寸。

用这个函数代替 CreateRectRgn 成员函数可以避免调用局部内存管理程序。

请参阅 CRgn::CreateRectRgn, ::SetRectRgn

操作符

CRgn ::operator HRGN operator HRGN( ) const; 返回值

如果成功则返回一个 W indowsGDI 对象句柄，该对象由 CRgn 对象代表；否则返回 NULL 。

说明

此操作符用来获取 CRgn 对象的与 W indows GDI 连接的句柄。此操作符是一个强制转换操作符，它支持对一个 HRGN 对象的直接使用。

要获取更多有关使用图形对象的信息，请参见 “ Win32 SDK 程序员参考 ” 中的文章 “ 图形化对象 ” 。

CRgn

CRgn

CRgn 类 成 员

成 员 函 数

操 作 符

CRgn 类成员

成员函数

操作符