Jump to content

GpiQueryRegionBox: Difference between revisions

From EDM2
Created page with "This function checks whether a point lies within a region. ==Syntax== GpiPtInRegion(hps, hrgn, pptlPoint) ==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. ; pptlPoint (PPOINTL) - input : Point to be checked. : The point is in device coordinates. ==Return Value== ; lInside (LONG) - returns : Inside and..."
 
No edit summary
 
(One intermediate revision by one other user not shown)
Line 1: Line 1:
This function checks whether a point lies within a region.
This function returns the dimensions of the smallest rectangle able to bound the region.  


==Syntax==
==Syntax==
  GpiPtInRegion(hps, hrgn, pptlPoint)
  GpiQueryRegionBox(hps, hrgn, prclBound)


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


; hrgn ([[HRGN]]) - input
;hrgn (HRGN) - input
: Region handle.
:Region handle.  


; pptlPoint ([[PPOINTL]]) - input
;prclBound (PRECTL) - output
: Point to be checked.
:Bounding rectangle.  
: The point is in device coordinates.


==Return Value==
 
; lInside ([[LONG]]) - returns
==Returns==
: Inside and error indicators.
;lComplexity (LONG) - returns: Complexity of region and error indicators.
:; PRGN_OUTSIDE
 
:: Not in region
:;RGN_NULL
:; PRGN_INSIDE
::Null region
:: In region
:;RGN_RECT
:; PRGN_ERROR
::Rectangular region  
:: Error.
:;RGN_COMPLEX
::Complex region  
:;RGN_ERROR
::Error.
 
==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_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==
==Remarks==
It is invalid if the specified region is currently selected as the clip region (by [[GpiSetClipRegion]]).
If the region is null, the rectangle returned has the left boundary equal to the right, and the top boundary equal to the bottom.


==Errors==
It is invalid if the specified region is currently selected as the clip region (by GpiSetClipRegion).  
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_COORDINATE (0x205B)
: An invalid coordinate value 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.


==Example Code==
==Example Code==
<PRE>
<pre>
#define INCL_GPIREGIONS /* Or use INCL_GPI, INCL_PM, */
#define INCL_GPIREGIONS /* Or use INCL_GPI, INCL_PM, */
#include &lt;os2.h&gt;
#include <os2.h>


HPS     hps;       /* Presentation-space handle. */
HPS       hps;         /* Presentation-space handle. */
HRGN   hrgn;       /* Region handle. */
HRGN     hrgn;         /* Region handle. */
PPOINTL pptlPoint; /* Point to be checked. */
PRECTL    prclBound;   /* Bounding rectangle. */
LONG   lInside;   /* Inside and error indicators. */
LONG     lComplexity; /* Complexity of region and error indicators. */


lInside = GpiPtInRegion(hps, hrgn, pptlPoint);
lComplexity = GpiQueryRegionBox(hps, hrgn,
</PRE>
                prclBound);
</pre>
In this example we determine the dimensions of the smallest rectangle able to bound the region.
<pre>
#define INCL_GPIPREGIONS
#include <OS2.H>


This example uses GpiPtInRegion to determine if the point (150,150) lies within a region.
LONG lResult;    /* number of elements returned */
HPS hps;          /* Presentation space handle. */
HRGN hrgn;        /* region handle */
RECTL rclBound; /* bounding rectangle */


<pre>
lResult = GpiQueryRegionBox(hps,
#define INCL_GPIREGIONS /* Region functions */
                            (VOID *)hrgn,
#include &lt;os2.h&gt;
                            (PRECTL)&rclBound);


LONG lInside; /* inside/error indicator */
HPS hps; /* Presentation-space handle */
HRGN hrgn; /* handle for region */
POINTL pptlPoint = {150L,150L};/* point to be checked */
RECTL arcl[3] = { 100, 100, 200, 200, /* 1st rectangle */
                  150, 150, 250, 250, /* 2nd rectangle */
                  200, 200, 300, 300 }; /* 3rd rectangle */


/* create a region comprising three rectangles */
hrgn = GpiCreateRegion(hps, 3L, arcl);
lInside = GpiPtInRegion(hps, hrgn, &pptlPoint);
</pre>
</pre>
==Related Functions==
* [[GpiCombineRegion]]
* [[GpiCreateRegion]]
* [[GpiDestroyRegion]]
* [[GpiEqualRegion]]
* [[GpiOffsetRegion]]
* [[GpiPaintRegion]]
* [[GpiQueryRegionBox]]
* [[GpiQueryRegionRects]]
* [[GpiRectInRegion]]
* [[GpiSetRegion]]


[[Category:Gpi]]
[[Category:Gpi]]

Latest revision as of 19:23, 7 April 2025

This function returns the dimensions of the smallest rectangle able to bound the region.

Syntax

GpiQueryRegionBox(hps, hrgn, prclBound)

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) - output
Bounding rectangle.


Returns

lComplexity (LONG) - returns
Complexity of region and error indicators.
RGN_NULL
Null region
RGN_RECT
Rectangular region
RGN_COMPLEX
Complex region
RGN_ERROR
Error.

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_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

If the region is null, the rectangle returned has the left boundary equal to the right, and the top boundary equal to the bottom.

It is invalid if the specified region is currently selected as the clip region (by GpiSetClipRegion).

Example Code

#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. */
LONG      lComplexity;  /*  Complexity of region and error indicators. */

lComplexity = GpiQueryRegionBox(hps, hrgn,
                prclBound);

In this example we determine the dimensions of the smallest rectangle able to bound the region. 

#define INCL_GPIPREGIONS
#include <OS2.H>

LONG lResult;     /* number of elements returned */
HPS hps;          /* Presentation space handle. */
HRGN hrgn;        /* region handle */
RECTL rclBound; /* bounding rectangle */

lResult = GpiQueryRegionBox(hps,
                            (VOID *)hrgn,
                            (PRECTL)&rclBound);
Retrieved from "https://www.edm2.com/index.php?title=GpiQueryRegionBox&oldid=84664"