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 GpiElement(hps, lType, psz, cb, pb)
HPS hps;       /* presentation-space handle                     */
LONG lType;    /* element type                                  */
PSZ psz;       /* address of element descriptor                 */
LONG cb;       /* length in bytes of buffer for graphics orders */
PBYTE pb;      /* address of buffer for graphics orders         */
 
The GpiElement function draws an element. The element consists of one or
more graphics orders in the buffer pointed to by pb. The function executes
each order as if it were the corresponding Gpi function.
 
The function adds the element to the current open segment if the drawing
mode is DM_RETAIN or DM_DRAWANDRETAIN. Otherwise, it just draws the element.
The element must not contain graphics orders for an element bracket.
Similarly, the function cannot be used in an element bracket.
 
The function sets the type and descriptor for the element to the values
given by lType and psz. The type and descriptor are a useful way of uniquely
identifying the element when it is added to a segment. The type and
descriptor can be retrieved at any time by using the GpiQueryElementType
function.
 
Parameter  Description
────────────────────────────────────────────────────────────────────────────
 
hps        Identifies the presentation space.
 
lType      Specifies the integer value to use for the element type.
 
psz        Points to the null-terminated string to use for the element
           descriptor.
 
cb         Specifies the length of graphics order data for the element.
 
pb         Points to the buffer that contains the graphics orders for the
           element. The buffer must not exceed 63K.
 
Return Value
 
The return value is GPI_OK or GPI_HITS if the function is successful. (It is
GPI_HITS if the detectable attribute is set for the presentation space and a
correlation hit occurs.) The return value is GPI_ERROR if an error occurs.
 
Errors
 
Use the WinGetLastError function to retrieve the error value, which may be
one of the following:
 
     PMERR_ALREADY_IN_ELEMENT
     PMERR_DATA_TOO_LONG
     PMERR_INV_HPS
     PMERR_INV_LENGTH
     PMERR_INV_LENGTH_OR_COUNT
     PMERR_INV_MICROPS_FUNCTION
     PMERR_PS_BUSY
 
Comments
 
GpiElement does not convert coordinates. This may affect drawing the element
if the format for the coordinates in the graphics orders is not the correct
format for the presentation space.
 
See Also
 
GpiBeginElement, GpiDeleteElement, GpiEndElement, GpiQueryElement,
GpiQueryElementPointer, GpiQueryElementType, GpiSetElementPointer,
WinGetLastError
 
                                      ♦