◄Function Group►  ◄Overview►                          ◄Up► ◄Next► ◄Previous►
────────────────────────────────────────────────────────────────────────────
 
#define INCL_GPICORRELATION
 
BOOL GpiSetTag(hps, lTag)
HPS hps;      /* presentation-space handle */
LONG lTag;    /* tag                       */
 
The GpiSetTag function sets the current primitive tag. A primitive tag is a
way of identifying a primitive stored in a segment. The function sets the
primitive tag and the system applies this tag to all subsequent primitives.
The default tag is zero.
 
Primitive tags are typically used when correlating segments. The
GpiCorrelateChain, GpiCorrelateFrom, and GpiCorrelateSegment functions
return the segment identifier and the primitive tag of objects that lie in
the pick aperture.
 
The GpiSetTag function cannot be used in an area bracket, but can be used
before an area bracket to give all primitives in the area the same tag. If
the attribute mode is AM_PRESERVE, the function saves the previous tag on
the attribute stack when it sets the new tag. The previous tag can be
retrieved using the GpiPop function.
 
Parameter  Description
────────────────────────────────────────────────────────────────────────────
 
hps        Identifies the presentation space.
 
lTag       Specifies a tag. It must be an integer value.
 
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
the following:
 
     PMERR_INV_HPS
     PMERR_INV_MICROPS_FUNCTION
     PMERR_PS_BUSY
 
Comments
 
Although primitives in an unnamed segment can be tagged, the correlation
functions cannot pick or correlate unnamed segments or any tags applied to
them are ignored.
 
See Also
 
GpiBeginArea, GpiCorrelateChain, GpiCorrelateFrom, GpiCorrelateSegment,
GpiEndArea, GpiSetAttrMode, WinGetLastError
 
                                      ♦