| title | ms.custom | ms.date | ms.reviewer | ms.suite | ms.technology | ms.tgt_pltfrm | ms.topic | f1_keywords | dev_langs | helpviewer_keywords | ms.assetid | caps.latest.revision | author | ms.author | manager | ||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
CRgn Class | Microsoft Docs |
11/04/2016 |
|
reference |
|
|
|
d904da84-76aa-481e-8780-b09485f49e64 |
23 |
mikeblome |
mblome |
ghogen |
Encapsulates a Windows graphics device interface (GDI) region.
class CRgn : public CGdiObject
| Name | Description |
|---|---|
| CRgn::CRgn | Constructs a CRgn object. |
| Name | Description |
|---|---|
| CRgn::CombineRgn | Sets a CRgn object so that it is equivalent to the union of two specified CRgn objects. |
| CRgn::CopyRgn | Sets a CRgn object so that it is a copy of a specified CRgn object. |
| CRgn::CreateEllipticRgn | Initializes a CRgn object with an elliptical region. |
| CRgn::CreateEllipticRgnIndirect | Initializes a CRgn object with an elliptical region defined by a RECT structure. |
| CRgn::CreateFromData | Creates a region from the given region and transformation data. |
| CRgn::CreateFromPath | Creates a region from the path that is selected into the given device context. |
| CRgn::CreatePolygonRgn | Initializes a CRgn object with a polygonal region. The system closes the polygon automatically, if necessary, by drawing a line from the last vertex to the first. |
| CRgn::CreatePolyPolygonRgn | Initializes a CRgn object with a region consisting of a series of closed polygons. The polygons may be disjoint, or they may overlap. |
| CRgn::CreateRectRgn | Initializes a CRgn object with a rectangular region. |
| CRgn::CreateRectRgnIndirect | Initializes a CRgn object with a rectangular region defined by a RECT structure. |
| CRgn::CreateRoundRectRgn | Initializes a CRgn object with a rectangular region with rounded corners. |
| CRgn::EqualRgn | Checks two CRgn objects to determine whether they are equivalent. |
| CRgn::FromHandle | Returns a pointer to a CRgn object when given a handle to a Windows region. |
| CRgn::GetRegionData | Fills the specified buffer with data describing the given region. |
| CRgn::GetRgnBox | Retrieves the coordinates of the bounding rectangle of a CRgn object. |
| CRgn::OffsetRgn | Moves a CRgn object by the specified offsets. |
| CRgn::PtInRegion | Determines whether a specified point is in the region. |
| CRgn::RectInRegion | Determines whether any part of a specified rectangle is within the boundaries of the region. |
| CRgn::SetRectRgn | Sets the CRgn object to the specified rectangular region. |
| Name | Description |
|---|---|
| CRgn::operator HRGN | Returns the Windows handle contained in the CRgn object. |
A region is an elliptical or polygonal area within a window. To use regions, you use the member functions of class CRgn with the clipping functions defined as members of class CDC.
The member functions of CRgn create, alter, and retrieve information about the region object for which they are called.
For more information on using CRgn, see Graphic Objects.
CRgn
Header: afxwin.h
Creates a new GDI region by combining two existing regions.
int CombineRgn(
CRgn* pRgn1,
CRgn* pRgn2,
int nCombineMode);
pRgn1
Identifies an existing region.
pRgn2
Identifies an existing region.
nCombineMode
Specifies the operation to be performed when combining the two source regions. It can be any one of the following values:
-
RGN_AND Uses overlapping areas of both regions (intersection).
-
RGN_COPY Creates a copy of region 1 (identified by
pRgn1). -
RGN_DIFF Creates a region consisting of the areas of region 1 (identified by
pRgn1) that are not part of region 2 (identified bypRgn2). -
RGN_OR Combines both regions in their entirety (union).
-
RGN_XOR Combines both regions but removes overlapping areas.
Specifies the type of the resulting region. It can be one of the following values:
-
COMPLEXREGION New region has overlapping borders.
-
ERROR No new region created.
-
NULLREGION New region is empty.
-
SIMPLEREGION New region has no overlapping borders.
The regions are combined as specified by nCombineMode.
The two specified regions are combined, and the resulting region handle is stored in the CRgn object. Thus, whatever region is stored in the CRgn object is replaced by the combined region.
The size of a region is limited to 32,767 by 32,767 logical units or 64K of memory, whichever is smaller.
Use CopyRgn to simply copy one region into another region.
[!code-cppNVC_MFCDocView#144]
Copies the region defined by pRgnSrc into the CRgn object.
int CopyRgn(CRgn* pRgnSrc);
pRgnSrc
Identifies an existing region.
Specifies the type of the resulting region. It can be one of the following values:
-
COMPLEXREGION New region has overlapping borders.
-
ERROR No new region created.
-
NULLREGION New region is empty.
-
SIMPLEREGION New region has no overlapping borders.
The new region replaces the region formerly stored in the CRgn object. This function is a special case of the CombineRgn member function.
See the example for CRgn::CreateEllipticRgn.
Creates an elliptical region.
BOOL CreateEllipticRgn(
int x1,
int y1,
int x2,
int y2);
x1
Specifies the logical x-coordinate of the upper-left corner of the bounding rectangle of the ellipse.
y1
Specifies the logical y-coordinate of the upper-left corner of the bounding rectangle of the ellipse.
x2
Specifies the logical x-coordinate of the lower-right corner of the bounding rectangle of the ellipse.
y2
Specifies the logical y-coordinate of the lower-right corner of the bounding rectangle of the ellipse.
Nonzero if the operation succeeded; otherwise 0.
The region is defined by the bounding rectangle specified by x1, y1, x2, and y2. The region is stored in the CRgn object.
The size of a region is limited to 32,767 by 32,767 logical units or 64K of memory, whichever is smaller.
When it has finished using a region created with the CreateEllipticRgn function, an application should select the region out of the device context and use the DeleteObject function to remove it.
[!code-cppNVC_MFCDocView#145]
Creates an elliptical region.
BOOL CreateEllipticRgnIndirect(LPCRECT lpRect);
lpRect
Points to a RECT structure or a CRect object that contains the logical coordinates of the upper-left and lower-right corners of the bounding rectangle of the ellipse.
Nonzero if the operation succeeded; otherwise 0.
The region is defined by the structure or object pointed to by lpRect and is stored in the CRgn object.
The size of a region is limited to 32,767 by 32,767 logical units or 64K of memory, whichever is smaller.
When it has finished using a region created with the CreateEllipticRgnIndirect function, an application should select the region out of the device context and use the DeleteObject function to remove it.
See the example for CRgn::CreateRectRgnIndirect.
Creates a region from the given region and transformation data.
BOOL CreateFromData(
const XFORM* lpXForm,
int nCount,
const RGNDATA* pRgnData);
lpXForm
Points to an XFORM data structure that defines the transformation to be performed on the region. If this pointer is NULL, the identity transformation is used.
nCount
Specifies the number of bytes pointed to by pRgnData.
pRgnData
Points to a RGNDATA data structure that contains the region data.
Nonzero if the function is successful; otherwise 0.
An application can retrieve data for a region by calling the CRgn::GetRegionData function.
Creates a region from the path that is selected into the given device context.
BOOL CreateFromPath(CDC* pDC);
pDC
Identifies a device context that contains a closed path.
Nonzero if the function is successful; otherwise 0.
The device context identified by the pDC parameter must contain a closed path. After CreateFromPath converts a path into a region, Windows discards the closed path from the device context.
Creates a polygonal region.
BOOL CreatePolygonRgn(
LPPOINT lpPoints,
int nCount,
int nMode);
lpPoints
Points to an array of POINT structures or an array of CPoint objects. Each structure specifies the x-coordinate and y-coordinate of one vertex of the polygon. The POINT structure has the following form:
typedef struct tagPOINT {
int x;
int y;
} POINT;
nCount
Specifies the number of POINT structures or CPoint objects in the array pointed to by lpPoints.
nMode
Specifies the filling mode for the region. This parameter may be either ALTERNATE or WINDING.
Nonzero if the operation succeeded; otherwise 0.
The system closes the polygon automatically, if necessary, by drawing a line from the last vertex to the first. The resulting region is stored in the CRgn object.
The size of a region is limited to 32,767 by 32,767 logical units or 64K of memory, whichever is smaller.
When the polygon-filling mode is ALTERNATE, the system fills the area between odd-numbered and even-numbered polygon sides on each scan line. That is, the system fills the area between the first and second side, between the third and fourth side, and so on.
When the polygon-filling mode is WINDING, the system uses the direction in which a figure was drawn to determine whether to fill an area. Each line segment in a polygon is drawn in either a clockwise or a counterclockwise direction. Whenever an imaginary line drawn from an enclosed area to the outside of a figure passes through a clockwise line segment, a count is incremented. When the line passes through a counterclockwise line segment, the count is decremented. The area is filled if the count is nonzero when the line reaches the outside of the figure.
When an application has finished using a region created with the CreatePolygonRgn function, it should select the region out of the device context and use the DeleteObject function to remove it.
[!code-cppNVC_MFCDocView#146]
Creates a region consisting of a series of closed polygons.
BOOL CreatePolyPolygonRgn(
LPPOINT lpPoints,
LPINT lpPolyCounts,
int nCount,
int nPolyFillMode);
lpPoints
Points to an array of POINT structures or an array of CPoint objects that defines the vertices of the polygons. Each polygon must be explicitly closed because the system does not close them automatically. The polygons are specified consecutively. The POINT structure has the following form:
typedef struct tagPOINT {
int x;
int y;
} POINT;
lpPolyCounts
Points to an array of integers. The first integer specifies the number of vertices in the first polygon in the lpPoints array, the second integer specifies the number of vertices in the second polygon, and so on.
nCount
Specifies the total number of integers in the lpPolyCounts array.
nPolyFillMode
Specifies the polygon-filling mode. This value may be either ALTERNATE or WINDING.
Nonzero if the operation succeeded; otherwise 0.
The resulting region is stored in the CRgn object.
The polygons may be disjoint, or they may overlap.
The size of a region is limited to 32,767 by 32,767 logical units or 64K of memory, whichever is smaller.
When the polygon-filling mode is ALTERNATE, the system fills the area between odd-numbered and even-numbered polygon sides on each scan line. That is, the system fills the area between the first and second side, between the third and fourth side, and so on.
When the polygon-filling mode is WINDING, the system uses the direction in which a figure was drawn to determine whether to fill an area. Each line segment in a polygon is drawn in either a clockwise or a counterclockwise direction. Whenever an imaginary line drawn from an enclosed area to the outside of a figure passes through a clockwise line segment, a count is incremented. When the line passes through a counterclockwise line segment, the count is decremented. The area is filled if the count is nonzero when the line reaches the outside of the figure.
When an application has finished using a region created with the CreatePolyPolygonRgn function, it should select the region out of the device context and use the CGDIObject::DeleteObject member function to remove it.
Creates a rectangular region that is stored in the CRgn object.
BOOL CreateRectRgn(
int x1,
int y1,
int x2,
int y2);
x1
Specifies the logical x-coordinate of the upper-left corner of the region.
y1
Specifies the logical y-coordinate of the upper-left corner of the region.
x2
Specifies the logical x-coordinate of the lower-right corner of the region.
y2
Specifies the logical y-coordinate of the lower-right corner of the region.
Nonzero if the operation succeeded; otherwise 0.
The size of a region is limited to 32,767 by 32,767 logical units or 64K of memory, whichever is smaller.
When it has finished using a region created by CreateRectRgn, an application should use the CGDIObject::DeleteObject member function to remove the region.
[!code-cppNVC_MFCDocView#147]
For an additional example, see CRgn::CombineRgn.
Creates a rectangular region that is stored in the CRgn object.
BOOL CreateRectRgnIndirect(LPCRECT lpRect);
lpRect
Points to a RECT structure or CRect object that contains the logical coordinates of the upper-left and lower-right corners of the region. The RECT structure has the following form:
typedef struct tagRECT {
int left;
int top;
int right;
int bottom;
} RECT;
Nonzero if the operation succeeded; otherwise 0.
The size of a region is limited to 32,767 by 32,767 logical units or 64K of memory, whichever is smaller.
When it has finished using a region created by CreateRectRgnIndirect, an application should use the CGDIObject::DeleteObject member function to remove the region.
[!code-cppNVC_MFCDocView#148]
Creates a rectangular region with rounded corners that is stored in the CRgn object.
BOOL CreateRoundRectRgn(
int x1,
int y1,
int x2,
int y2,
int x3,
int y3);
x1
Specifies the logical x-coordinate of the upper-left corner of the region.
y1
Specifies the logical y-coordinate of the upper-left corner of the region.
x2
Specifies the logical x-coordinate of the lower-right corner of the region.
y2
Specifies the logical y-coordinate of the lower-right corner of the region.
x3
Specifies the width of the ellipse used to create the rounded corners.
y3
Specifies the height of the ellipse used to create the rounded corners.
Nonzero if the operation succeeded; otherwise 0.
The size of a region is limited to 32,767 by 32,767 logical units or 64K of memory, whichever is smaller.
When an application has finished using a region created with the CreateRoundRectRgn function, it should select the region out of the device context and use the CGDIObject::DeleteObject member function to remove it.
[!code-cppNVC_MFCDocView#149]
Constructs a CRgn object.
CRgn();
The m_hObject data member does not contain a valid Windows GDI region until the object is initialized with one or more of the other CRgn member functions.
See the example for CRgn::CreateRoundRectRgn.
Determines whether the given region is equivalent to the region stored in the CRgn object.
BOOL EqualRgn(CRgn* pRgn) const;
pRgn
Identifies a region.
Nonzero if the two regions are equivalent; otherwise 0.
[!code-cppNVC_MFCDocView#150]
Returns a pointer to a CRgn object when given a handle to a Windows region.
static CRgn* PASCAL FromHandle(HRGN hRgn);
hRgn
Specifies a handle to a Windows region.
A pointer to a CRgn object. If the function was not successful, the return value is NULL.
If a CRgn object is not already attached to the handle, a temporary CRgn object is created and attached. This temporary CRgn object is valid only until the next time the application has idle time in its event loop, at which time all temporary graphic objects are deleted. Another way of saying this is that the temporary object is only valid during the processing of one window message.
Fills the specified buffer with data describing the region.
int GetRegionData(
LPRGNDATA lpRgnData,
int nCount) const;
lpRgnData
Points to a RGNDATA data structure that receives the information. If this parameter is NULL, the return value contains the number of bytes needed for the region data.
nCount
Specifies the size, in bytes, of the lpRgnData buffer.
If the function succeeds and nCount specifies an adequate number of bytes, the return value is always nCount. If the function fails, or if nCount specifies less than adequate number of bytes, the return value is 0 (error).
This data includes the dimensions of the rectangles that make up the region. This function is used in conjunction with the CRgn::CreateFromData function.
Retrieves the coordinates of the bounding rectangle of the CRgn object.
int GetRgnBox(LPRECT lpRect) const;
lpRect
Points to a RECT structure or CRect object to receive the coordinates of the bounding rectangle. The RECT structure has the following form:
typedef struct tagRECT {
int left;
int top;
int right;
int bottom;
} RECT;
Specifies the region's type. It can be any of the following values:
-
COMPLEXREGION Region has overlapping borders.
-
NULLREGION Region is empty.
-
ERROR
CRgnobject does not specify a valid region. -
SIMPLEREGION Region has no overlapping borders.
See the example for CRgn::CreatePolygonRgn.
Moves the region stored in the CRgn object by the specified offsets.
int OffsetRgn(
int x,
int y);
int OffsetRgn(POINT point);
x
Specifies the number of units to move left or right.
y
Specifies the number of units to move up or down.
point
The x-coordinate of point specifies the number of units to move left or right. The y-coordinate of point specifies the number of units to move up or down. The point parameter may be either a POINT structure or a CPoint object.
The new region's type. It can be any one of the following values:
-
COMPLEXREGION Region has overlapping borders.
-
ERROR Region handle is not valid.
-
NULLREGION Region is empty.
-
SIMPLEREGION Region has no overlapping borders.
The function moves the region x units along the x-axis and y units along the y-axis.
The coordinate values of a region must be less than or equal to 32,767 and greater than or equal to -32,768. The x and y parameters must be carefully chosen to prevent invalid region coordinates.
See the example for CRgn::CreateEllipticRgn.
Use this operator to get the attached Windows GDI handle of the CRgn object.
operator HRGN() const;
If successful, a handle to the Windows GDI object represented by the CRgn object; otherwise NULL.
This operator is a casting operator, which supports direct use of an HRGN object.
For more information about using graphic objects, see the article Graphic Objects in the Windows SDK.
Checks whether the point given by x and y is in the region stored in the CRgn object.
BOOL PtInRegion(
int x,
int y) const;
BOOL PtInRegion(POINT point) const;
x
Specifies the logical x-coordinate of the point to test.
y
Specifies the logical y-coordinate of the point to test.
point
The x- and y-coordinates of point specify the x- and y-coordinates of the point to test the value of. The point parameter can either be a POINT structure or a CPoint object.
Nonzero if the point is in the region; otherwise 0.
Determines whether any part of the rectangle specified by lpRect is within the boundaries of the region stored in the CRgn object.
BOOL RectInRegion(LPCRECT lpRect) const;
lpRect
Points to a RECT structure or CRect object. The RECT structure has the following form:
typedef struct tagRECT {
int left;
int top;
int right;
int bottom;
} RECT;
Nonzero if any part of the specified rectangle lies within the boundaries of the region; otherwise 0.
Creates a rectangular region.
void SetRectRgn(
int x1,
int y1,
int x2,
int y2);
void SetRectRgn(LPCRECT lpRect);
x1
Specifies the x-coordinate of the upper-left corner of the rectangular region.
y1
Specifies the y-coordinate of the upper-left corner of the rectangular region.
x2
Specifies the x-coordinate of the lower-right corner of the rectangular region.
y2
Specifies the y-coordinate of the lower-right corner of the rectangular region.
lpRect
Specifies the rectangular region. Can be either a pointer to a RECT structure or a CRect object.
Unlike CreateRectRgn, however, it does not allocate any additional memory from the local Windows application heap. Instead, it uses the space allocated for the region stored in the CRgn object. This means that the CRgn object must already have been initialized with a valid Windows region before calling SetRectRgn. The points given by x1, y1, x2, and y2 specify the minimum size of the allocated space.
Use this function instead of the CreateRectRgn member function to avoid calls to the local memory manager.