GpiElement

This function adds a single element to the current segment.

Syntax

GpiElement(hps, lType, pszDesc, lLength, pbData)

Parameters

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

lType (LONG) - input: Type to be associated with the element.; Application-defined elements should have type values in the range 0x81xxxxxx through 0xFFxxxxxx so as to avoid conflict with system-generated elements.

pszDesc (PSZ) - input: Element description.; This is a variable length character string that is recorded with the element.

lLength (LONG) - input: Length of content data for the element.; This must not be greater than 64 512 bytes (63KB).

pbData (PBYTE) - input: Buffer pointer.; Element content data.

Return Value

lHits (LONG) - returns

Correlation and error indicators.

GPI_OK: Successful
GPI_HITS: Correlate hits
GPI_ERROR: Error.

Remarks

The element is stored in the current segment if the drawing mode (see GpiSetDrawingMode) is retain or draw-and-retain. It is drawn if the drawing mode is draw or draw-and-retain. It is an error if the element data contains any begin or end element orders. Similarly, this function is not valid within an element bracket. Note: No coordinate conversion is performed by this function. The application must ensure that the coordinates within the element are in the correct format for the presentation space (see GpiCreatePS).

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_MICROPS_FUNCTION (0x20A1): An attempt was made to issue a function that is invalid in a micro presentation space.
PMERR_INV_LENGTH_OR_COUNT (0x2092): An invalid length or count parameter was specified.
PMERR_DATA_TOO_LONG (0x2016): An attempt was made to transfer more than the maximum permitted amount of data (64512 bytes) using GpiPutData, GpiGetData, or GpiElement.
PMERR_ALREADY_IN_ELEMENT (0x2002): An attempt was made to begin a new element while an existing element bracket was already open.

Example Code

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

HPS   hps;     /* Presentation-space handle. */
LONG  lType;   /* Type to be associated with the element. */
PSZ   pszDesc; /* Element description. */
LONG  lLength; /* Length of content data for the element. */
PBYTE pbData;  /* Buffer pointer. */
LONG  lHits;    /* Correlation and error indicators. */

lHits = GpiElement(hps, lType, pszDesc, lLength, pbData);

This example uses GpiElement to add a single element to the current segment: an arc starting at the current position, passing through (10,10), and ending at (5,5).

#define INCL_GPISEGEDITING /* GPI Segment Edit functions */
#define INCL_GPISEGMENTS /* Segment functions */
#define INCL_ORDERS /* Graphical Order Formats */
#include <os2.h>

LONG lHits; /* correlation/error indicator */
HPS hps; /* presentation-space handle */
LONG lType; /* element type */
char pszDesc[4]; /* element description */
LONG lLength; /* length of element data */
LORDER pbData; /* pointer to element data */
ORDERL_GCARC lArcPts = {10L,10L,5L,5L}; /* arc points structure */

GpiOpenSegment(hps, 3L); /* opens segment to receive element */

/* type is order code for arc at current position (GARC) */
lType = OCODE_GCARC;

/* call the element 'Arc' */
strcpy(pszDesc,"Arc");

/* length of element data */
lLength = sizeof(LORDER);

/* fill element data structure */
pbData.idCode = OCODE_GCARC; /* order code: arc at current
                               position */
pbData.uchLength = sizeof(ORDERL_GCARC);
/* order data contains arc points structure */
memcpy(pbData.uchData, lArcPts, sizeof(ORDERL_GCARC));

/* add element */
lHits = GpiElement(hps, lType, pszDesc, lLength, (BYTE *)&pbData);

GpiCloseSegment(hps); /* closes segment that received data */