Important Notice

The pages on this site contain documentation for very old MS-DOS software, purely for historical purposes. If you're looking for up-to-date documentation, particularly for programming, you should not rely on the information found here, as it will be woefully out of date.

◄Function Group►  ◄Overview►                          ◄Up► ◄Next► ◄Previous►
────────────────────────────────────────────────────────────────────────────
 
#define INCL_GPISEGEDITING
 
LONG GpiQueryElementType(hps, plType, cbDesc, pszDesc)
HPS hps;         /* presentation-space handle         */
PLONG plType;    /* address of variable for type      */
LONG cbDesc;     /* length in bytes of buffer         */
PSZ pszDesc;     /* address of buffer for description */
 
The GpiQueryElementType function retrieves the type and description for an
element in current open segment. It also returns the size in bytes of the
element. The element pointer must point to the element to retrieve. The
function copies the type to the variable pointed to by the plType parameter,
and copies the description, up to the number of bytes specified by cbDesc,
to the buffer pointed to by the pszDesc parameter.
 
The function can be used only in an open segment and only when the drawing
mode is DM_RETAIN. It cannot be used in an element bracket.
 
Parameter  Description
────────────────────────────────────────────────────────────────────────────
 
hps        Identifies the presentation space.
 
plType     Points to the variable that receives the element type.
 
cbDesc     Specifies the maximum number of bytes of description to copy to
           the buffer specified by the pszDesc parameter.
 
pszDesc    Points to the buffer that receives the description, a
           null-terminated string, for the element. The buffer must have the
           number of bytes specified by cbDesc. If the description is longer
           than the buffer, it is truncated.
 
Return Value
 
The return value is the size of the data required to hold the element if the
function is successful or GPI_ALTERROR if an error occurred.
 
Errors
 
Use the WinGetLastError function to retrieve the error value, which may be
one of the following:
 
     PMERR_INV_HPS
     PMERR_INV_IN_ELEMENT
     PMERR_INV_LENGTH
     PMERR_INV_LENGTH_OR_COUNT
     PMERR_INV_MICROPS_FUNCTION
     PMERR_NO_CURRENT_ELEMENT
     PMERR_NOT_IN_RETAIN_MODE
     PMERR_PS_BUSY
 
Example
 
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.
 
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 */
    (PSZ) NULL);     /* no buffer for description      */
 
GpiQueryElement(hps, 0L, cbElement, abElement);
 
See Also
 
GpiBeginElement, GpiElement, GpiQueryElement, GpiQueryElementPointer,
WinGetLastError
 
                                      ♦