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 GpiLabel(hps, idLabel)
HPS hps;         /* presentation-space handle */
LONG idLabel;    /* label                     */
 
The GpiLabel function creates a label element. A label element is an element
in a segment that contains nothing more than a 32-bit value. The function
creates a label for an element in the current open segment. If no segment is
open, no label is created.
 
The GpiLabel function cannot be used in an element bracket.
 
Parameter  Description
────────────────────────────────────────────────────────────────────────────
 
hps        Identifies the presentation space.
 
idLabel    Specifies the label. It can be any value in the range 0x00000000
           through 0xFFFFFFFF.
 
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_INV_HPS
     PMERR_INV_IN_ELEMENT
     PMERR_INV_MICROPS_FUNCTION
     PMERR_PS_BUSY
 
Comments
 
The GpiLabel function is intended to be used to uniquely identify elements
in a segment that may be edited. Label elements are typically placed near
elements to be edited. The label can be used with the
GpiSetElementPointerAtLabel function to move the element pointer to the
given element.
 
Example
 
This example uses the GpiLabel function to create label elements in a
segment. If the segment is subsequently edited, the label elements can still
be used to locate the elements near it.
 
POINTL ptlStart = { 0, 0 };
POINTL ptlTriangle[] = { 100, 100, 200, 0, 0, 0 };
 
GpiOpenSegment(hps, 4L);          /* creates a segment */
GpiLabel(hps, 5L);                /* creates label 5   */
GpiLabel(hps, 10L);               /* creates label 10  */
GpiMove(hps, &ptlStart);
GpiCloseSegment(hps);
GpiPolyLine(hps, 3L, ptlTriangle);
 
See Also
 
GpiSetElementPointerAtLabel, WinGetLastError
 
                                      ♦