GpiFrameRegion

This function draws a frame inside a region using the current pattern attributes.

Syntax

GpiFrameRegion(hps, hrgn, thickness)

Parameters

hps (HPS) - input: Presentation-space handle.

hrgn (HRGN) - input: Region handle.

thickness (PSIZEL) - input: Thickness of frame.; The width and height of the rectangle, in device coordinates, used to trace the frame. Both the cx and cy fields must be greater than or equal to zero.

Return Value

lHits (LONG) - returns

Correlation and error indicators.

GPI_OK: Successful
GPI_HITS: Correlate hits
GPI_ERROR: Error.

Remarks

The frame is drawn by tracing around the inner boundary of the region with a rectangle of size given by the thickness parameter. The edge of the frame includes the pels on the left and bottom boundaries of the region, unless those pels are also on the top and right boundaries, in which case they are excluded. No part of the frame is drawn outside the region. The region is assumed to be defined in device coordinates. It is invalid if the specified region is currently selected as the clip region (by GpiSetClipRegion). Note: This function must not be used when creating SAA-conforming metafiles; see "MetaFile Resolutions" in the Presentation Manager Programming Reference for more information.

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_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): An invalid region handle was specified.
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;      /* Region handle. */
PSIZEL thickness; /* Thickness of frame. */
LONG   lHits;     /* Correlation and error indicators. */

lHits = GpiFrameRegion(hps, hrgn, thickness);

This example uses GpiFrameRegion to draw a frame of width 5 around an existing region.

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

LONG lHits; /* correlation/error indicator */
HPS hps; /* presentation-space handle */
HRGN hrgn; /* handle for region */
SIZEL psizlThickness = {5L,5L}; /* Thickness of frame */
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);

lHits = GpiFrameRegion(hps, hrgn, &psizlThickness);