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 */