CRgn Class

 

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at CRgn Class.

Encapsulates a Windows graphics device interface (GDI) region.

Syntax

class CRgn : public CGdiObject  

Members

Public Constructors

Name Description
CRgn::CRgn Constructs a CRgn object.

Public Methods

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.

Public Operators

Name Description
CRgn::operator HRGN Returns the Windows handle contained in the CRgn object.

Remarks

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.

Inheritance Hierarchy

CObject

CGdiObject

CRgn

Requirements

Header: afxwin.h

CRgn::CombineRgn

Creates a new GDI region by combining two existing regions.

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

Parameters

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 by pRgn2).

  • RGN_OR Combines both regions in their entirety (union).

  • RGN_XOR Combines both regions but removes overlapping areas.

Return Value

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.

Remarks

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.

Example

   CRgn   rgnA, rgnB, rgnC;

   VERIFY(rgnA.CreateRectRgn( 50, 50, 150, 150 ));
   VERIFY(rgnB.CreateRectRgn( 100, 100, 200, 200 ));
   VERIFY(rgnC.CreateRectRgn( 0, 0, 50, 50 ));

   int nCombineResult = rgnC.CombineRgn( &rgnA, &rgnB, RGN_OR );
   ASSERT( nCombineResult != ERROR && nCombineResult != NULLREGION );

   CBrush br1, br2, br3;
   VERIFY(br1.CreateSolidBrush( RGB(255, 0, 0) ));  // rgnA Red
   VERIFY(pDC->FrameRgn( &rgnA, &br1, 2, 2 ));
   VERIFY(br2.CreateSolidBrush( RGB(0, 255, 0) ));  // rgnB Green
   VERIFY(pDC->FrameRgn( &rgnB, &br2, 2, 2 ));
   VERIFY(br3.CreateSolidBrush( RGB(0, 0, 255) ));  // rgnC Blue
   VERIFY(pDC->FrameRgn( &rgnC, &br3, 2, 2 ));

CRgn::CopyRgn

Copies the region defined by pRgnSrc into the CRgn object.

int CopyRgn(CRgn* pRgnSrc);

Parameters

pRgnSrc
Identifies an existing region.

Return Value

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.

Remarks

The new region replaces the region formerly stored in the CRgn object. This function is a special case of the CombineRgn member function.

Example

See the example for CRgn::CreateEllipticRgn.

CRgn::CreateEllipticRgn

Creates an elliptical region.

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

Parameters

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.

Return Value

Nonzero if the operation succeeded; otherwise 0.

Remarks

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.

Example

   CRgn   rgnA, rgnB, rgnC;

   VERIFY(rgnA.CreateEllipticRgn(200, 100, 350, 250));
   VERIFY(rgnB.CreateRectRgn( 0, 0, 50, 50 ));
   VERIFY(rgnB.CopyRgn( &rgnA ));
   int nOffsetResult = rgnB.OffsetRgn( -75, 75 );
   ASSERT( nOffsetResult != ERROR && nOffsetResult != NULLREGION );

   VERIFY(rgnC.CreateRectRgn( 0, 0, 1, 1));
   int nCombineResult = rgnC.CombineRgn( &rgnA, &rgnB, RGN_AND );
   ASSERT( nCombineResult != ERROR && nOffsetResult != NULLREGION );

   CBrush brA, brB, brC;
   VERIFY(brC.CreateHatchBrush( HS_FDIAGONAL, RGB(0, 0, 255) )); // Blue
   VERIFY(pDC->FillRgn( &rgnC, &brC ));
   VERIFY(brA.CreateSolidBrush( RGB(255, 0, 0) ));  // rgnA Red
   VERIFY(pDC->FrameRgn( &rgnA, &brA, 2, 2 ));
   VERIFY(brB.CreateSolidBrush( RGB(0, 255, 0) ));  // rgnB Green
   VERIFY(pDC->FrameRgn( &rgnB, &brB, 2, 2 ));   

CRgn::CreateEllipticRgnIndirect

Creates an elliptical region.

BOOL CreateEllipticRgnIndirect(LPCRECT lpRect);

Parameters

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.

Return Value

Nonzero if the operation succeeded; otherwise 0.

Remarks

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.

Example

See the example for CRgn::CreateRectRgnIndirect.

CRgn::CreateFromData

Creates a region from the given region and transformation data.

BOOL CreateFromData(
    const XFORM* lpXForm,  
    int nCount,  
    const RGNDATA* pRgnData);

Parameters

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.

Return Value

Nonzero if the function is successful; otherwise 0.

Remarks

An application can retrieve data for a region by calling the CRgn::GetRegionData function.

CRgn::CreateFromPath

Creates a region from the path that is selected into the given device context.

BOOL CreateFromPath(CDC* pDC);

Parameters

pDC
Identifies a device context that contains a closed path.

Return Value

Nonzero if the function is successful; otherwise 0.

Remarks

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.

CRgn::CreatePolygonRgn

Creates a polygonal region.

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

Parameters

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.

Return Value

Nonzero if the operation succeeded; otherwise 0.

Remarks

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.

Example

   CRgn   rgnA, rgnB;

   CPoint ptVertex[5];

   ptVertex[0].x = 180;
   ptVertex[0].y = 80;
   ptVertex[1].x = 100;
   ptVertex[1].y = 160;
   ptVertex[2].x = 120;
   ptVertex[2].y = 260;
   ptVertex[3].x = 240;
   ptVertex[3].y = 260;
   ptVertex[4].x = 260;
   ptVertex[4].y = 160;

   VERIFY(rgnA.CreatePolygonRgn( ptVertex, 5, ALTERNATE));

   CRect rectRgnBox;
   int nRgnBoxResult = rgnA.GetRgnBox( &rectRgnBox );
   ASSERT( nRgnBoxResult != ERROR && nRgnBoxResult != NULLREGION );

   CBrush brA, brB;
   VERIFY(brA.CreateSolidBrush( RGB(255, 0, 0) ));  // rgnA Red
   VERIFY(pDC->FrameRgn( &rgnA, &brA, 2, 2 ));
   VERIFY(brB.CreateSolidBrush( RGB(0, 0, 255) ));  // Blue
   rectRgnBox.InflateRect(3,3);
   pDC->FrameRect( &rectRgnBox, &brB );

CRgn::CreatePolyPolygonRgn

Creates a region consisting of a series of closed polygons.

BOOL CreatePolyPolygonRgn(
    LPPOINT lpPoints,  
    LPINT lpPolyCounts,  
    int nCount,  
    int nPolyFillMode);

Parameters

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.

Return Value

Nonzero if the operation succeeded; otherwise 0.

Remarks

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.

CRgn::CreateRectRgn

Creates a rectangular region that is stored in the CRgn object.

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

Parameters

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.

Return Value

Nonzero if the operation succeeded; otherwise 0.

Remarks

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.

Example

   CRgn   rgn;

   BOOL bSucceeded = rgn.CreateRectRgn( 50, 20, 150, 120 );
   ASSERT( bSucceeded == TRUE );

For an additional example, see CRgn::CombineRgn.

CRgn::CreateRectRgnIndirect

Creates a rectangular region that is stored in the CRgn object.

BOOL CreateRectRgnIndirect(LPCRECT lpRect);

Parameters

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;

Return Value

Nonzero if the operation succeeded; otherwise 0.

Remarks

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.

Example

   CRgn   rgnA, rgnB, rgnC;

   CRect rectA(50, 50, 150, 150);
   CRect rectB(100, 50, 200, 150);

   VERIFY(rgnA.CreateRectRgnIndirect(&rectA));
   VERIFY(rgnB.CreateEllipticRgnIndirect(&rectB));
   VERIFY(rgnC.CreateRectRgn( 0, 0, 50, 50 ));

   int nCombineResult = rgnC.CombineRgn( &rgnA, &rgnB, RGN_AND );
   ASSERT( nCombineResult != ERROR && nCombineResult != NULLREGION );

   CBrush brA, brB, brC;
   VERIFY(brA.CreateSolidBrush( RGB(255, 0, 0) ));  
   VERIFY(pDC->FrameRgn( &rgnA, &brA, 2, 2 ));      // rgnA Red

   VERIFY(brB.CreateSolidBrush( RGB(0, 255, 0) ));  
   VERIFY(pDC->FrameRgn( &rgnB, &brB, 2, 2 ));      // rgnB Green
   VERIFY(brC.CreateSolidBrush( RGB(0, 0, 255) ));  // rgnC Blue
   VERIFY(pDC->FrameRgn( &rgnC, &brC, 2, 2 ));

CRgn::CreateRoundRectRgn

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);

Parameters

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.

Return Value

Nonzero if the operation succeeded; otherwise 0.

Remarks

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.

Example

   CRgn   rgnA, rgnB, rgnC;

   VERIFY(rgnA.CreateRoundRectRgn( 50, 50, 150, 150, 30, 30 ));
   VERIFY(rgnB.CreateRoundRectRgn( 200, 75, 250, 125, 50, 50 ));
   VERIFY(rgnC.CreateRectRgn( 0, 0, 50, 50 ));

   int nCombineResult = rgnC.CombineRgn( &rgnA, &rgnB, RGN_OR );
   ASSERT( nCombineResult != ERROR && nCombineResult != NULLREGION );

   CBrush brA, brB, brC;
   VERIFY(brA.CreateSolidBrush( RGB(255, 0, 0) ));  
   VERIFY(pDC->FillRgn( &rgnA, &brA));      // rgnA Red Filled

   VERIFY(brB.CreateSolidBrush( RGB(0, 255, 0) ));  
   VERIFY(pDC->FillRgn( &rgnB, &brB));      // rgnB Green Filled
   VERIFY(brC.CreateSolidBrush( RGB(0, 0, 255) ));  // rgnC Blue
   VERIFY(pDC->FrameRgn( &rgnC, &brC, 2, 2 ));

CRgn::CRgn

Constructs a CRgn object.

CRgn();

Remarks

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.

Example

See the example for CRgn::CreateRoundRectRgn.

CRgn::EqualRgn

Determines whether the given region is equivalent to the region stored in the CRgn object.

BOOL EqualRgn(CRgn* pRgn) const;  

Parameters

pRgn
Identifies a region.

Return Value

Nonzero if the two regions are equivalent; otherwise 0.

Example

   CRgn   rgnA, rgnB;

   VERIFY(rgnA.CreateEllipticRgn(200, 100, 350, 250));
   VERIFY(rgnB.CreateRectRgn( 0, 0, 50, 50 ));
   VERIFY(rgnB.CopyRgn( &rgnA ));
   int nOffsetResult = rgnB.OffsetRgn( -75, 75 );
   ASSERT( nOffsetResult != ERROR && nOffsetResult != NULLREGION );
   ASSERT( FALSE == rgnB.EqualRgn( &rgnA ) );

CRgn::FromHandle

Returns a pointer to a CRgn object when given a handle to a Windows region.

static CRgn* PASCAL FromHandle(HRGN hRgn);

Parameters

hRgn
Specifies a handle to a Windows region.

Return Value

A pointer to a CRgn object. If the function was not successful, the return value is NULL.

Remarks

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.

CRgn::GetRegionData

Fills the specified buffer with data describing the region.

int GetRegionData(
    LPRGNDATA lpRgnData,  
    int nCount) const;  

Parameters

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.

Return Value

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).

Remarks

This data includes the dimensions of the rectangles that make up the region. This function is used in conjunction with the CRgn::CreateFromData function.

CRgn::GetRgnBox

Retrieves the coordinates of the bounding rectangle of the CRgn object.

int GetRgnBox(LPRECT lpRect) const;  

Parameters

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;

Return Value

Specifies the region's type. It can be any of the following values:

  • COMPLEXREGION Region has overlapping borders.

  • NULLREGION Region is empty.

  • ERROR CRgn object does not specify a valid region.

  • SIMPLEREGION Region has no overlapping borders.

Example

See the example for CRgn::CreatePolygonRgn.

CRgn::OffsetRgn

Moves the region stored in the CRgn object by the specified offsets.

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

Parameters

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.

Return Value

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.

Remarks

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.

Example

See the example for CRgn::CreateEllipticRgn.

CRgn::operator HRGN

Use this operator to get the attached Windows GDI handle of the CRgn object.

operator HRGN() const;  

Return Value

If successful, a handle to the Windows GDI object represented by the CRgn object; otherwise NULL.

Remarks

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.

CRgn::PtInRegion

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;  

Parameters

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.

Return Value

Nonzero if the point is in the region; otherwise 0.

CRgn::RectInRegion

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;  

Parameters

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;

Return Value

Nonzero if any part of the specified rectangle lies within the boundaries of the region; otherwise 0.

CRgn::SetRectRgn

Creates a rectangular region.

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

Parameters

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.

Remarks

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.

See Also

CWnd Class
Hierarchy Chart