Important Notice

The pages on this site contain documentation for very old MS-DOS software, purely for historical purposes. If you're looking for up-to-date documentation, particularly for programming, you should not rely on the information found here, as it will be woefully out of date.

◄Function Group►  ◄Overview►                          ◄Up► ◄Next► ◄Previous►
────────────────────────────────────────────────────────────────────────────
 
#define INCL_GPIREGIONS
 
BOOL GpiQueryRegionRects(hps, hrgn, prclBound, prgnrc, arcl)
HPS hps;             /* presentation-space handle                    */
HRGN hrgn;           /* region handle                                */
PRECTL prclBound;    /* address of structure for enclosing rectangle */
PRGNRECT prgnrc;     /* address of structure controlling processing  */
PRECTL arcl;         /* address of array of rectangle structures     */
 
The GpiQueryRegionRects function retrieves the rectangles that define the
region identified by the hrgn parameter. The rectangles can be used to
recreate the region, by using the GpiCreateRegion function. The function
copies the coordinates of one or more of the defining rectangles to the
array of structures pointed to by the arcl parameter. It uses the rectangle
pointed to by the prclBound parameter to determine which rectangles to
retrieve. Only rectangles within this rectangle are retrieved. If the
prclBound parameter is NULL, the function retrieves all rectangles in the
region.
 
The GpiQueryRegionRects function uses the fields of the RGNRECT structure
pointed to by the prgnrc parameter to control how the defining rectangles
are retrieved. Since a region may comprise several rectangles, the RGNRECT
structure lets an application retrieve a few rectangles at a time. The
structure specifies which rectangle to start with and how many to retrieve.
The function copies the actual number of rectangles retrieved to the
structure. Also, a field in this structure specifies the direction through
the region the function is to take as it retrieves rectangles.
 
The GpiQueryRegionRects function cannot be used if no device context is
associated with the presentation space.
 
Parameter  Description
────────────────────────────────────────────────────────────────────────────
 
hps        Identifies the presentation space.
 
hrgn       Identifies the region.
 
prclBound  Points to the RECTL structure that contains the enclosing
           rectangle. Only rectangles within this rectangle are retrieved.
 
prgnrc     Points to the RGNRECT structure that specifies how to retrieve
           the rectangles.
 
arcl       Points to the array of RECTL structures that receives the
           defining rectangles.
 
Return Value
 
The return value is GPI_OK if the function is successful or GPI_ERROR if an
error occurred.
 
Errors
 
Use the WinGetLastError function to retrieve the error value, which may be
one of the following:
 
     PMERR_INV_COORDINATE
     PMERR_INV_HPS
     PMERR_INV_HRGN
     PMERR_INV_RECT
     PMERR_INV_REGION_CONTROL
     PMERR_PS_BUSY
 
See Also
 
GpiCombineRegion, GpiCreateRegion, WinGetLastError, RECTL, RGNRECT
 
                                      ♦