Get Ready to Unleash the Power of UCanCode .NET

GetRandomRgn

The GetRandomRgn function copies the system clipping region of a specified device context to a specific region. You may need to get the newer versions of the windows header files in order to have access to this function, it has just recently been documented in MSDN, but has been exported from GDI32.dll for quite some time. The only value that is documented for the iNum parameters is SYSRGN which is defined as the value 4 in wingdi.h. As you can see from the description below extracted from MSDN, the iNum must be set to SYSRGN. This is simply not true. There are three other undocumented values that are legal to send to this function.

int GetRandomRgn(
  HDC  hdc,    // handle to DC
  HRGN hrgn,   // handle to region
  INT  iNum    // must be SYSRGN
);

Here are the four valid values, and their effect when set into iNum in GetRandomRgn:

• VALUE = 1: This undocumented value will return the current Clip Region contained in the DC.
• VALUE = 2: This undocumented value will return the current Meta Region contained in the DC.
• VALUE = 3: This undocumented value will return the intersection of the Clip Region and Meta Region. Feng Yuan calls this region the Rao region, which is supposedly named after the Microsoft engineer that convinced the development team to cache this intersected region to increase performance. Take this for what it is worth.
• VALUE = 4, SYSRGN: The only value that is documented and defined for this function. This value returns the System Region that was described earlier.

One more thing to be aware of when a region is retrieved from GetRandomRgn is that on Windows 9x operating systems the region is returned in window coordinates, and on Windows NT machines the region is in screen coordinates. Therefore to use the region in a window on Windows NT machines the region will need to be offset. Here is a piece of code that can be used to translate the region on a Windows NT machine.

POINT pt = {0,0};
::MapWindowPoints(NULL, hWnd, &pt, 1);

::OffsetRgn(hRgn, pt.x, pt.y);

GetDCEx

The GetDCEx function retrieves a handle to a DC for a specified window or for the entire screen. This function allows the developer to specify an initial Clip Region for the newly created DC. However, this statement is a little misconceiving. The actaul region that gets set when a clipping region is specified is the System Region. This is the developer's backdoor into setting the System Region for a DC. However, one the region is set and the DC is created, there is no way for an application to directly manipulate the System Region.

HDC GetDCEx(
  HWND hWnd,      // handle to window
  HRGN hrgnClip,  // handle to clipping region
  DWORD flags     // creation options
);

In order to set the region, one of these two flags must be used to indicate how to use the region:

• DCX_EXCLUDERGN: The clipping region identified by hrgnClip is excluded from the visible region of the returned DC.
• DCX_INTERSECTRGN: The clipping region identified by hrgnClip is intersected with the visible region of the returned DC. This would have the effect of reallowing the regions that have already been clipped away for child window clipping and Z-Order clipping to be painted on.

One thing to be aware of when passing a valid region to this function, is that this function assumes ownership of the region. It is very important that this region is not deleted or even used after this function call.

The regions that are stored in a DC are stored in window coordinates on a Windows 9x machine and in screen coordinates on a Windows NT machine. This means that if the region is to be set in GetDCEx on a Windows NT machine, then the region will need to be translated to screen coordinates relative to the window before the call to GetDCEx. Here is a small code sample that demonstrates how to do this:

	POINT pt = {0,0};
	::MapWindowPoints(hWnd, NULL, &pt, 1);

	::OffsetRgn(hRgn, pt.x, pt.y);

GetClipBox The GetClipBox function retrieves the dimensions of the tightest bounding rectangle that can be drawn around the current visible area on the device. The visible area is defined by the current Clip Region or clip path, as well as any overlapping windows. Collapse Copy Code int GetClipBox( HDC hdc, // handle to DC LPRECT lprc // rectangle ); The dimensions that this function return are in logical coordinates for the current DC. The return value will indicate the current region type that is stored in the Clip Region. GetClipRgn The GetClipRgn function retrieves a handle identifying the current application-defined Clip Region for the specified device context. The region that is returned will be in device coordinates, rather than logical coordinates. This differs from the behaviour for GetClipBox. It is highly likely that this function could be implemented in terms of GetRandomRgn by simply passing in a 1 to the iNum parameter. Collapse Copy Code int GetClipRgn( HDC hdc, // handle to DC HRGN hrgn // handle to region ); SelectClipRgn The SelectClipRgn function selects a region as the current Clip Region for the specified device context. This is the simplest way to set the Clip Region of a device context. Collapse Copy Code int SelectClipRgn( HDC hdc, // handle to DC HRGN hrgn // handle to region ); The dimensions that this function return are in device coordinates for the current DC. The return value will indicate the current region type that is stored in the Clip Region.