GpiExcludeClipRectangle
This function excludes a rectangle from the clipping region.
Syntax
GpiExcludeClipRectangle(hps, prclRectangle)
Parameters
- hps (HPS) - input
- Presentation-space handle.
- prclRectangle (PRECTL) - input
- Rectangle to be excluded.
- The coordinates are world coordinates.
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 following list the possible values:
- RGN_NULL
- Null region
- RGN_RECT
- Rectangular region
- RGN_COMPLEX
- Complex region
- RGN_ERROR
- Error.
Remarks
The boundaries of the rectangle are considered to be part of the interior, so that a point on the rectangle boundary is clipped (removed). This function creates a clip region if one does not currently exist. The application is responsible for freeing this (with GpiDestroyRegion) if it subsequently selects another clip region (see GpiSetClipRegion). Any clip region still selected when the device context is closed is automatically freed. 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_COORDINATE (0x205B)
- An invalid coordinate value was specified.
- PMERR_INV_RECT (0x20BD)
- An invalid rectangle parameter was specified.
Example Code
#define INCL_GPIREGIONS /* Or use INCL_GPI, INCL_PM, */ #include <os2.h> HPS hps; /* Presentation-space handle. */ PRECTL prclRectangle; /* Rectangle to be excluded. */ LONG lComplexity; /* Complexity of clipping and error indicators. */ lComplexity = GpiExcludeClipRectangle(hps, prclRectangle);
This example uses GpiExcludeClipRectangle to exclude a 100x100 rectangle, anchored at (100,100), from the clipping region.
#define INCL_GPIREGIONS /* Region functions */
#include <os2.h>
LONG lComplexity; /* clipping complexity/error return */
HPS hps; /* Presentation-space handle */
RECTL prclRectangle = {100, 100, 200, 200};/* exclude rectangle */
lComplexity = GpiExcludeClipRectangle(hps, &prclRectangle);