GpiDestroyRegion: Difference between revisions

Latest revision as of 01:39, 17 November 2025

This function destroys a region.

Syntax

GpiDestroyRegion(hps, hrgn)

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: Handle of region to be destroyed.; If this is NULLHANDLE, the call takes no action, and completes without error.

Return Value

rc (BOOL) - returns

Success indicator.

TRUE - Successful completion

FALSE - Error occurred.

Remarks

This function cannot be used to destroy the clip region; the clip region must first be deselected with GpiSetClipRegion.

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.

Example Code

This example uses the GpiDestroyRegion function to destroy a region after drawing a complex figure.

#define INCL_GPIREGIONS /* Region functions */
#include <os2.h>

HPS hps; /* presentation space handle */
HRGN hrgn;
RECTL arcl[3] = { 10,10,20,20,15,15,25,25,20,20,30,30 };

hrgn = GpiCreateRegion(hps, 3L, arcl); /* use 3 rectangles */
GpiPaintRegion(hps, hrgn); /* paint the region */
GpiDestroyRegion(hps, hrgn); /* destroy the region */

Related Functions

Prerequisite Functions

GpiSetClipRegion (if the region to be destroyed is a clip region)

Related Functions

@@ Line 5: / Line 5: @@
 ==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.
+; hrgn ([[HRGN]]) - input: Handle of region to be destroyed.
-; hrgn ([[HRGN]]) - input
-: Handle of region to be destroyed.
 : If this is NULLHANDLE, the call takes no action, and completes without error.
 ==Return Value==
-; rc ([[BOOL]]) - returns
+; rc ([[BOOL]]) - returns: Success indicator.
-: Success indicator.
+::TRUE - Successful completion
-:; TRUE
+::FALSE - Error occurred.
-:: Successful completion
-:; FALSE
-:: Error occurred.
 ==Remarks==
@@ Line 26: / Line 20: @@
 ==Errors==
 Possible returns from WinGetLastError:
-; PMERR_INV_HPS (0x207F)
+; PMERR_INV_HPS (0x207F): An invalid presentation-space handle was specified.
-: 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_PS_BUSY (0x20F4)
+; PMERR_INV_HRGN (0x2080): An invalid region handle was specified.
-: An attempt was made to access the presentation space from more than one thread simultaneously.
+; 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_INV_HRGN (0x2080)
+; 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.
-: 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.
 ==Example Code==
-<PRE>
-#define INCL_GPIREGIONS /* Or use INCL_GPI, INCL_PM, */
-#include &lt;os2.h&gt;
-HPS     hps;  /* Presentation-space handle. */
-HRGN    hrgn; /* Handle of region to be destroyed. */
-BOOL    rc;   /* Success indicator. */
-rc = GpiDestroyRegion(hps, hrgn);
-</PRE>
 This example uses the GpiDestroyRegion function to destroy a region after drawing a complex figure.
 <pre>
 #define INCL_GPIREGIONS /* Region functions */
-#include &lt;os2.h&gt;
+#include <os2.h>
 HPS hps; /* presentation space handle */