GpiDestroyRegion

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

#define INCL_GPIREGIONS /* Or use INCL_GPI, INCL_PM, */
#include <os2.h>

HPS     hps;  /* Presentation-space handle. */
HRGN    hrgn; /* Handle of region to be destroyed. */
BOOL    rc;   /* Success indicator. */

rc = GpiDestroyRegion(hps, hrgn);

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