CombineRgn Function

Declare Function CombineRgn Lib "gdi32.dll" (ByVal hDestRgn As Long, ByVal hSrcRgn1 As Long, ByVal hSrcRgn2 As Long, ByVal nCombineMode As Long) As Long

Platforms

Windows 95: Supported.
Windows 98: Supported.
Windows NT: Requires Windows NT 3.1 or later.
Windows 2000: Supported.
Windows CE: Requires Windows CE 1.0 or later.

Description & Usage

CombineRgn combines two regions to form a third region. The two regions can be combined using a variety of logical operators. Note that the region that receives the combined regions must already be a region -- the function cannot create a new one but can change an existing one.

Return Value

The function returns one of the following flags specifying the result of the region combination operation:

ERROR: An error occured while trying to combine the regions.
NULLREGION: The combined region is empty, i.e., null.
SIMPLEREGION: The combined region forms a rectangle.
COMPLEXREGION: The combined region is not empty but is also not a rectangle.

Visual Basic-Specific Issues

None.

Parameters

hDestRgn

A handle to the region to be set to the combination of the two source regions. This region must already have been created, although its contents when passed to the function is irrelevant.

hSrcRgn1

The first of the two source regions.

hSrcRgn2

The second of the two source regions.

nCombineMode

One of the following flags specifying the logical operation to use to combine the two regions:

RGN_AND: The combined region is the overlapping area of the two source regions.
RGN_OR: The combined region is all the area contained in either of the two source regions, including any overlap.
RGN_XOR: The combined region is all of the area contained in either of the two source regions, excluding any overlap.
RGN_DIFF: The combined region is all the area of the first source region except for the portion also included in the second source region.
RGN_COPY: The combined region is identical to the first source region. The second source region is ignored.

Constant Definitions

Const ERROR = 0
Const NULLREGION = 1
Const SIMPLEREGION = 2
Const COMPLEXREGION = 3
Const RGN_AND = 1
Const RGN_OR = 2
Const RGN_XOR = 3
Const RGN_DIFF = 4
Const RGN_COPY = 5

Example

' This code is licensed according to the terms and conditions listed here.

' On window Form1, create overlapping elliptical and rectangular regions.
' Fill the overlapped area with a dark gray brush; fill the nonoverlapping areas with
' a light gray brush.
Dim hRgn1 As Long, hRgn2 As Long  ' elliptical and rectangular source regions.
Dim hXorRgn As Long, hAndRgn As Long  ' regions set to the non-intersection and intersection
Dim hLightBrush As Long, hDarkBrush As Long  ' handles to light gray and dark gray brushes
Dim retval As Long  ' return value

' Create the four regions.  The initial settings of hXorRgn and hAndRgn are irrelevant.
hRgn1 = CreateEllipticRgn(100, 50, 200, 100)  ' bounding rect (100,50)-(200,100)
hRgn2 = CreateRectRgn(150, 75, 300, 200)  ' rectangle (150,75)-(300,200)
hXorRgn = CreateRectRgn(0, 0, 0, 0)  ' meaningless initialization
hAndRgn = CreateRectRgn(0, 0, 0, 0)  ' meaningless initialization

' Now set hAndRgn to the intersection of the two source regions and hXorRgn to
' the non-intersection of the two source regions.
retval = CombineRgn(hXorRgn, hRgn1, hRgn2, RGN_XOR)  ' non-intersection
retval = CombineRgn(hAndRgn, hRgn1, hRgn2, RGN_AND)  ' intersection

' Now get the necessary stock brushes and fill in the two combined regions.
hLightBrush = GetStockObject(LTGRAY_BRUSH)  ' light gray solid brush
hDarkBrush = GetStockObject(DKGRAY_BRUSH)  ' dark gray solid brush
retval = FillRgn(Form1.hDC, hXorRgn, hLightBrush)  ' fill non-intersection
retval = FillRgn(Form1.hDC, hAndRgn, hDarkBrush)  ' fill intersection

' Delete the four regions to free up resources.
retval = DeleteObject(hRgn1)
retval = DeleteObject(hRgn2)
retval = DeleteObject(hXorRgn)
retval = DeleteObject(hAndRgn)