GpiSetTag: Difference between revisions

Revision as of 00:20, 3 April 2025

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);

Related Functions

GpiCorrelateChain
GpiQueryDefTag
GpiQueryTag
GpiSetDefTag

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

@@ Line 23: / Line 23: @@
 ;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.
+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.
+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.
+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.
-The attribute mode (see GpiSetAttrMode) determines whether the current value of the tag is preserved.
 ==Example Code==
 <pre>