GpiBeginElement

This function defines the start of an element within a segment.

Syntax

GpiBeginElement(hps, lType, pszDesc)

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 to avoid conflict with system-generated elements.

pszDesc (PSZ) - input

Description.

Variable-length character string, recorded with the type.

Returns

rc (BOOL) - returns

Success indicator.

TRUE Successful completion

FALSE Error occurred

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_ALREADY_IN_ELEMENT (0x2002)

An attempt was made to begin a new element while an existing element bracket was already open. P

MERR_DESC_STRING_TRUNCATED (0x2018)

An attempt was made to supply a description string with GpiBeginElement that was greater then the permitted maximum length (251 characters). The string was truncated.

Remarks

This function starts an element, stored in the current segment, in retain or draw-and-retain mode (see GpiSetDrawingMode). The element is drawn in draw or draw-and-retain mode.

The drawing functions that form the contents of the element are passed on subsequent GPI functions (only those functions that can generate orders are logically part of the element). The element extends up to the next GpiEndElement function (or GpiCloseSegment, which causes an implicit GpiEndElement to be generated).

Grouping drawing functions together into an element is useful if the set of functions is to be changed or replaced together at a later time. Drawing functions that are not explicitly grouped together in an element bracket (GpiBeginElement - GpiEndElement pair) generate a single element for each GPI function.

The GpiElement function, that itself generates a complete element, is not allowed within an element bracket. The GpiLabel function is also not allowed within an element bracket. Elements must not be nested within one segment.

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;  /*  Description. */
BOOL    rc;       /*  Success indicator. */

rc = GpiBeginElement(hps, lType, pszDesc);

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.

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

HPS  hps;
POINTL ptlStart = { 0, 0 }; /* first vertex                     */
POINTL ptlTriangle[] = { 100, 100, 200, 0, 0, 0 }; /* vertices  */

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

Graphic Elements and Orders

The element type is defined by the lType parameter.

Order: Begin Element

Related Functions

• GpiCloseSegment
• GpiDeleteElement
• GpiDeleteElementRange
• GpiDeleteElementsBetweenLabels
• GpiElement
• GpiEndElement
• GpiLabel
• GpiOffsetElementPointer
• GpiQueryElement
• GpiQueryElementPointer
• GpiQueryElementType
• GpiSetElementPointer
• GpiSetElementPointerAtLabel