GpiQueryElementType

This function returns information about the element to which the element pointer currently points.

Syntax

GpiQueryElementType(hps, plType, lLength, pszData)

Parameters

hps (HPS) - input

Presentation-space handle.

plType (PLONG) - output

Element type.

The element type can be system-defined or application-defined; see GpiElement and GpiBeginElement.

lLength (LONG) - input

Data length.

Length of the description data buffer.

pszData (PSZ) - output

Description of data buffer.

The description may be system-defined or application-defined; see GpiElement and GpiBeginElement. The string is null-terminated, even if it has to be truncated.

Return Value

lReqLength (LONG) - returns

Size of the data required to hold the element content.

This can be used for a subsequent GpiQueryElement function.

>=0 : Size of data

GPI_ALTERROR : Error.

Remarks

This function is only valid when the drawing mode (see GpiSetDrawingMode) is set to retain (not draw-and-retain), and a segment bracket is currently in progress. It is not valid in an element bracket.

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_NO_CURRENT_ELEMENT (0x20E5)

An attempt has been made to issue GpiQueryElementType or GpiQueryElement while there is no currently open element.

PMERR_NOT_IN_RETAIN_MODE (0x20E2)

An attempt was made to issue a segment editing element function that is invalid when the actual drawing mode is not set to retain.

PMERR_INV_LENGTH_OR_COUNT (0x2092)

An invalid length or count parameter was specified.

PMERR_INV_IN_ELEMENT (0x2089)

An attempt was made to issue a function invalid inside an element bracket.

PMERR_NO_CURRENT_SEG (0x20E6)

An attempt has been made to issue GpiQueryElementType or GpiQueryElement while there is no currently open segment.

Example Code

This example uses the GpiQueryElementType function to retrieve the size of the current element. The size is used to retrieve the graphics-order data in the element.

#define INCL_GPISEGEDITING /* GPI Segment Edit functions */
#include <os2.h>

HPS hps; /* presentation space handle */
BYTE abElement[512];
LONG cbElement;
LONG lType;

/* move pointer to first element in segment */
GpiSetElementPointer(hps, 1L);

cbElement = GpiQueryElementType(
    hps, /* presentation space */
    &lType, /* variable to receive type */
    0L, /* copy zero bytes of description */
    NULL); /* no buffer for description */

GpiQueryElement(hps, 0L, cbElement, abElement);