GpiSetClipRegion
This function defines the region to be used for clipping, when any drawing takes place through the specified presentation space.
Syntax
GpiSetClipRegion(hps, hrgn, phrgnOld)
Parameters
- hps (HPS) - input
- Presentation-space handle.
- The presentation space must be currently associated with a device context of the correct device class (defined when the region is first created).
- hrgn (HRGN) - input
- Region handle.
- If hrgn is null, the clipping region is set to no clipping (its initial state).
- phrgnOld (PHRGN) - output
- Old region handle (if any).
- HRGN_ERROR
- Error
- NULLHANDLE
- Null handle (no region selected).
- Otherwise
- Old region handle.
Return Value
- lComplexity (LONG) - returns
- Complexity of clipping and error indicators.
- The clipping complexity information includes the combined effects of:
- * Clip path
- * Viewing limits
- * Graphics field
- * Clip region
- * Visible region (windowing considerations).
- The possible values for the return value are:
- RGN_NULL
- Null region
- RGN_RECT
- Rectangular region
- RGN_COMPLEX
- Complex region
- RGN_ERROR
- Error.
Remarks
While a region is in use as a clip region, the calls GpiOffsetClipRegion, GpiExcludeClipRectangle and GpiIntersectClipRectangle cause it to be changed. These changes persist after the region has been deselected. The clip region cannot, however, be used for any other region operations, nor can it be selected into any other presentation space as a clipping region, until it is deselected. The coordinates of the region are taken to be device coordinates within the device context. The previous clip region, if any, is converted to a region, and a handle to it is returned. This can be used in a subsequent GpiSetClipRegion to reinstate the same clipping as before. If no clip region exists, a null handle is returned. It is the responsibility of the application to free the previous clip region (if any) with GpiDestroyRegion, even if this region was not originally created explicitly by the application. Note: This function must not be used when creating SAA-conforming metafiles; see "MetaFile Resolutions" in the Presentation Manager Programming Reference for more information.
Errors
Possible returns from WinGetLastError:
- PMERR_INV_HPS (0x207F)
- An invalid presentation-space handle was specified.
- PMERR_PS_BUSY (0x20F4)
- An attempt was made to access the presentation space from more than one thread simultaneously.
- PMERR_INV_HRGN (0x2080)
- An invalid region handle was specified.
- PMERR_HRGN_BUSY (0x2034)
- An internal region busy error was detected. The region was locked by one thread during an attempt to access it from another thread.
Example Code
#define INCL_GPIREGIONS /* Or use INCL_GPI, INCL_PM, */ #include <os2.h> HPS hps; /* Presentation-space handle. */ HRGN hrgn; /* Region handle. */ PHRGN phrgnOld; /* Old region handle (if any). */ LONG lComplexity; /* Complexity of clipping and error indicators. */ lComplexity = GpiSetClipRegion(hps, hrgn, phrgnOld);