GpiQueryClipBox
This function returns the dimensions of the tightest rectangle which completely encloses the intersection of all the clipping definitions.
Syntax
GpiQueryClipBox(hps, prclBound)
Parameters
- hps (HPS) - input
- Presentation-space handle.
- prclBound (PRECTL) - output
- Bounding rectangle.
- The coordinates of the bounding rectangle, in world coordinates.
Return Value
- lComplexity (LONG) - returns
- Complexity and error indicators.
- RGN_NULL
- Null region
- RGN_RECT
- Rectangular region
- RGN_COMPLEX
- Complex region
- RGN_ERROR
- Error.
Remarks
The clipping definitions include the combined effects of:
- Clip path
- Viewing limits
- Graphics field
- Clip region
- Visible region (windowing considerations).
Points on the borders of the rectangle returned are considered to be included within the rectangle. If the intersection is null, the rectangle returned has the right boundary less than the left, and the top boundary less than the bottom.
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_COORDINATE_OVERFLOW (0x2014)
- An internal coordinate overflow error occurred. This can occur if coordinates or matrix transformation elements (or both) are invalid or too large.
Example Code
#define INCL_GPIREGIONS /* Or use INCL_GPI, INCL_PM, */ #include <os2.h> HPS hps; /* Presentation-space handle. */ PRECTL prclBound; /* Bounding rectangle. */ LONG lComplexity; /* Complexity and error indicators. */ lComplexity = GpiQueryClipBox(hps, prclBound);
This example uses GpiQueryClipBox to return the dimensions of the tightest rectangle which completely encloses the intersection of all the clipping definitions. The example queries the clip box and, if a rectangular region is returned, assigns the x-coordinate of the lower left hand corner of the clip box region to a variable.
#define INCL_GPIREGIONS /* Region functions */ #include <os2.h> LONG lComplexity; /* complexity/error indicator */ HPS hps; /* Presentation-space handle */ RECTL prclBound; /* bounding rectangle */ LONG lLwrLftxCoord; /* lower left x coordinate of clip box */ lComplexity = GpiQueryClipBox(hps, &prclBound); /* if returned region is a rectangle, assign lower left x coordinate */ if (lComplexity == RGN_RECT) lLwrLftxCoord = prclBound.xLeft;