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
 
BOOL GpiBeginElement(hps, lType, pszDesc)
HPS hps;        /* presentation-space handle      */
LONG lType;     /* element type                   */
PSZ pszDesc;    /* address of element description */
 
The GpiBeginElement function starts an element bracket, that is, a sequence
of functions that define the contents of an element. All subsequent graphics
functions, up to the next GpiEndElement or GpiCloseSegment function, apply
to the new element.
 
The GpiBeginElement may only be used while creating a segment. The element
type and element description, specified by the lType and pszDesc parameters,
are values that the application supplies to distinguish one element from
another within a segment.
 
Parameter  Description
────────────────────────────────────────────────────────────────────────────
 
hps        Identifies the presentation space.
 
lType      Specifies the element type. It can be any integer value.
 
pszDesc    Points to a null-terminated string. If no description is needed,
           it may point to an empty string.
 
Return Value
 
The return value is GPI_OK if the function is successful or GPI_ERROR if an
error occurred.
 
Errors
 
Use the WinGetLastError function to retrieve the error value, which may be
one of the following:
 
     PMERR_ALREADY_IN_ELEMENT
     PMERR_INV_HPS
     PMERR_INV_MICROPS_FUNCTION
     PMERR_PS_BUSY
 
Comments
 
The GpiBeginElement function cannot be used within an element bracket.
 
Example
 
This example uses the GpiBeginElement function to create an element in a
segment. The element type is 1 and the element description is "Triangle".
The application can use these later to identify the element.
 
POINTL ptlStart = { 0, 0 };
POINTL ptlTriangle[] = { 100, 100, 200, 0, 0, 0 };
GpiBeginElement(hps,                   /* start element bracket      */
    1L,                                /* element type is 1          */
    "Triangle");                       /* element description        */
GpiMove(hps, &ptlStart);               /* move to start point (0, 0) */
GpiPolyLine(hps, 3L, ptlTriangle);     /* draw triangle              */
GpiEndElement(hps);                    /* end element bracket        */
 
See Also
 
GpiCloseSegment, GpiDeleteElement, GpiEndElement, GpiQueryElement,
GpiQueryElementPointer, GpiSetElementPointer, WinGetLastError
 
                                      ♦