GpiSetTag

This function specifies a tag by which the following primitives are to be known.

Syntax

GpiSetTag(hps, lTag)

Parameters

hps (HPS) - input

Presentation-space handle.

lTag (LONG) - input

Tag identifier.

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_INV_MICROPS_FUNCTION (0x20A1)

An attempt was made to issue a function that is invalid in a micro presentation space.

Remarks

When GpiCorrelateChain, GpiCorrelateFrom, or GpiCorrelateSegment is used to locate an object, both the segment identifier and the primitive tag of the object are returned to the application program.

If a tag of 0 is specified, the primitives have no name and are not returned by the correlate call.

Initially, the default and current tag are 0. The default tag can be changed with GpiSetDefTag.

Primitives within an unnamed segment cannot be picked or correlated, and any tag applied to them is ignored.

This function is not allowed between GpiBeginArea and GpiEndArea calls, therefore, all primitives within an area have the same tag.

The attribute mode (see GpiSetAttrMode) determines whether the current value of the tag is preserved.

Example Code

#define INCL_GPICORRELATION /* Or use INCL_GPI, INCL_PM, */
#include <os2.h>

HPS     hps;   /*  Presentation-space handle. */
LONG    lTag;  /*  Tag identifier. */
BOOL    rc;    /*  Success indicator. */

rc = GpiSetTag(hps, lTag);

This example opens a segment and calls GpiSetTag so that all of the following primitives will be associated with that tag.

 
#define INCL_GPICORRELATION
#include <OS2.H>
HPS hps;         /* Presentation-space handle. */

GpiOpenSegment(hps, 0L);
GpiSetTag(hps, 0L);

Graphic Elements and Orders

Element Type

OCODE_GSPIK

This element type is generated if the attribute mode (see GpiSetAttrMode) is set to AM_NOPRESERVE.

Order: Set Pick Identifier

Element Type

OCODE_GPSPIK

This element type is generated if the attribute mode is set to AM_PRESERVE.

Order: Push and Set Pick Identifier