View source for GpiQueryRegionRects

This function determines what rectangles that, when ORed together, define the specified region and then returns either the number of rectangles or the rectangles themselves. 

==Syntax==
 GpiQueryRegionRects(hps, hrgn, prclBound, prgnrcControl, prclRect);

==Parameters==
;hps (HPS) - input
:Presentation-space handle.
:The region must be owned by the device identified by the currently associated device context. 

;hrgn (HRGN) - input
:Region handle. 

;prclBound (PRECTL) - input
:Bounding rectangle.
:;NULL
::Return all the rectangles in the region. 
:;Other
::Return only rectangles that intersect with the bounding rectangle. Each rectangle returned is the intersection of the bounding rectangle with a rectangle in the region. 

;prgnrcControl (PRGNRECT) - in/out
:Processing-control structure. 

;prclRect (PRECTL) - output
:Pointer to an array of rectangle structures or NULL
:;NULL
::Return the number of rectangles in the region.

::The number of rectanges is returned in the crcReturned field of the RGNRECT structure identified by the prgnrcControl parameter. The ircStart field will always be 1. If a bounding rectangle is specified, the crc and crcReturned fields will be set as follows:

            ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄ¿
            ³If the given   ³crc         ³crcReturned ³
            ³rectangle is:  ³            ³            ³
            ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄ´
            ³Completely     ³RRGN_INSIDE ³1           ³
            ³inside.        ³            ³            ³
            ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄ´
            ³Completely     ³RRGN_OUTSIDE³0           ³
            ³outside.       ³            ³            ³
            ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄ´
            ³Partially      ³RRGN_PARTIAL³Number of   ³
            ³inside.        ³            ³rectangles  ³
            ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÁÄÄÄÄÄÄÄÄÄÄÄÄÁÄÄÄÄÄÄÄÄÄÄÄÄÙ

:;Other
::Return only rectangles that intersect with the bounding rectangle. Each rectangle returned is the intersection of the bounding rectangle with a rectangle in the region.

::Pointer to an array of rectangle structures in which the rectangles are returned.
::The maximum number of rectangles that can be returned is specified by the crc parameter of the RGNRECT structure identified by the prgnrcControl parameter. 

        

==Returns==
;rc (BOOL) - returns
:Success indicator.

:;TRUE
::Successful completion 
:;FALSE
::Error occurred.

==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_INV_REGION_CONTROL (0x20BE)
        An invalid control parameter was specified with GpiQueryRegionRects. 
;PMERR_INV_COORDINATE (0x205B)
        An invalid coordinate value was specified. 
;PMERR_INV_RECT (0x20BD)
        An invalid rectangle parameter was specified. 
;PMERR_REGION_IS_CLIP_REGION (0x20F8)
        An attempt was made to perform a region operation on a region that is selected as a clip region. 
;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.


==Remarks==
Points on the right-hand and top boundaries are not included in the region. Points on the left-hand and bottom boundaries, that are not also on the right-hand or top boundaries (that is, the top-left and bottom-right corner points), are included.

It is invalid if the specified region is currently selected as the clip region (by GpiSetClipRegion). 
==Example Code==
<pre>
#define INCL_GPIREGIONS /* Or use INCL_GPI, INCL_PM, */
#include <os2.h>

HPS         hps;            /*  Presentation-space handle. */
HRGN        hrgn;           /*  Region handle. */
PRECTL      prclBound;      /*  Bounding rectangle. */
PRGNRECT    prgnrcControl;  /*  Processing-control structure. */
PRECTL      prclRect;       /*  Pointer to an array of rectangle structures. */
BOOL        rc;             /*  Success indicator. */

rc = GpiQueryRegionRects(hps, hrgn, prclBound, prgnrcControl, prclRect);
</pre>
In this example we determine the rectangles that can be OR'ed together to determine the specified region.
<pre> 
#define INCL_GPIREGIONS
#include <OS2.H>
#define MAXRECTS 12

BOOL flResult;      /* success indicator.         */
HPS hps;            /* presentation space handle. */
HRGN hrgn;          /* region handle.             */
RECTL rclBound;     /* bounding rectangle         */
RGNRECT rgnrcControl;  /* processing control      */
RECTL arclRect[MAXRECTS];  /* array of rectangle structures */
                           /* in which the rectangles are   */
                           /* returned.                     */

rgnrcControl.ircStart = 1;    /* start numbering rectangles */
                              /* from 1.                    */
rgnrcControl.crc = MAXRECTS;  /* maximum number of rectangles */
                              /* that can be returned.        */
rgnrcControl.usDirection = RECTDIR_LFRT_TOPBOT;
                               /* order rectangles left-to-right */
                               /* and top-to-bottom.             */
flResult =  GpiQueryRegionRects(hps,
                                hrgn,
                                &rclBound,      /* output */
                                &rgnrcControl,
                              /* rgnrcControl.crcReturned is the */
                              /* number of rectangles returned.  */
                                &arclRect[0]);


</pre>

[[Category:Gpi]]