GpiIntersectClipRectangle
This function sets the new clip region to the intersection of the current clip region and the specified rectangle.
Syntax
GpiIntersectClipRectangle(hps, prclRectangle)
Parameters
- hps (HPS) - input
- Presentation-space handle.
- prclRectangle (PRECTL) - input
- prclRectangle, the coordinates of which 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 possible values for this parameter are:
- 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 not clipped (removed) if it was previously within the clip region.
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; /* , the coordinates of which are world coordinates. */ LONG lComplexity; /* Complexity of clipping and error indicators. */ lComplexity = GpiIntersectClipRectangle(hps, prclRectangle);
This example uses GpiIntersectClipRectangle to create a new clipping region, consisting of the intersection of the old clipping region and a 100x100 rectangle, anchored at (100,100).
#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}; /* intersect rectangle */
lComplexity = GpiIntersectClipRectangle(hps, &prclRectangle);