| int SelectClipRgn(hdc, hrgn) | |||||
| HDC hdc; | /* handle of device context | */ | |||
| HRGN hrgn; | /* handle of region, */ | ||||
The SelectClipRgn function selects the given region as the current clipping region for the given device context.
hdc
Identifies the device context.
hrgn
Identifies the region to be selected. If this value is NULL, the entire client area is selected and output is still clipped to the window.
The return value is SIMPLEREGION (region has no overlapping borders), COMPLEXREGION (region has overlapping borders), or NULLREGION (region is empty), if the function is successful. Otherwise, the return value is ERROR.
The SelectClipRgn function selects only a copy of the specified region. Because SelectClipRgn uses only a copy, the region can be selected for any number of other device contexts or it can be deleted.
The coordinates for the specified region should be specified in device units.
Some printer devices support text output at a higher resolution than graphics output in order to retain the precision needed to express text metrics. These devices report device units at the higher resolution—that is, text units. These devices then scale coordinates for graphics so that several reported device units map to only one graphics unit. Applications should always call the SelectClipRgn function using the text unit. Applications that must take the scaling of graphics objects in the graphics device interface (GDI) can use the GETSCALINGFACTOR printer escape to determine the scaling factor. This scaling factor affects clipping. If a region is used to clip graphics, GDI divides the coordinates by the scaling factor. (If the region is used to clip text, however, GDI makes no scaling adjustment.) A scaling factor of 1 causes the coordinates to be divided by 2; a scaling factor of 2 causes the coordinates to be divided by 4; and so on.
The following example uses the GetClipBox function to determine the size of the current clipping region and the GetTextExtent function to determine the width of a line of text. If the text will not fit in the clipping region, the SelectClipRgn is used to make the region wide enough for the text. The output is clipped to the window regardless of the size of the region specified in the second parameter of SelectClipRegion.
HRGN hrgnClip;
RECT rcClip;
LPSTR lpszTest = "Test of clipping region.";
DWORD dwStringLen;
WORD wExtent;
GetClipBox(hdc, &rcClip);
dwStringLen = GetTextExtent(hdc, lpszTest, lstrlen(lpszTest));
wExtent = LOWORD(dwStringLen);
if (rcClip.right < 50 + wExtent) {
hrgnClip = CreateRectRgn(50, 50, 50 + wExtent, 80);
SelectClipRgn(hdc, hrgnClip);
}
TextOut(hdc, 50, 60, lpszTest, lstrlen(lpszTest));
DeleteObject(hrgnClip);