SetTaggedValue Method
The SetTaggedValue method adds a tagged value to the component’s TaggedValues array if the tag is not already present, or amends the TaggedValue if it is present.
At least one of value, textvalue or item must be supplied as a parameter.
Note: For ClassSources, this will not alter an inherited tag, but will override it. Changing or creating a tag that already exists in a subclass of this component will not affect that subclass.
To amend an inherited tag, use
FindTag Method to get the classname of the tag's owner, then access that ClassSource (using AppSource.FetchComponent (see
FetchComponent Method)) and issue SetTaggedValue for that ClassSource.
This method has the following syntax:
status = CompSource.SetTaggedValue(tag = varchar(256),
[value = StringObject | textvalue = varchar(maxsize)][, item = Object])
This method has the following variable and parameters:
CompSource
Specifies the frame, procedure, or user class
tag
(Required) Specifies the name of the tag to be stored or accessed in the TaggedValues array.
If an Item parameter is supplied, the tag name must be suffixed by a subtag, delimited from the main tag name by the "#" character. This subtag is used to uniquely identify and access the object item being stored. If the specified subtag has already been used, the supplied item will replace whatever object was previously stored using that subtag; if the supplied item is a null, the subtag entry will be deleted.
For example, to store a tagged value with tag name "test" and two objects (items), the first with subtag "one", the second with subtag "two", use the following code:
myCompSource.SetTaggedValue(tag='test#one', item= myfirstitem);
myCompSource.SetTaggedValue(tag='test#two', item= myseconditem);
To replace the myfirstitem object in the tagged value "test", use the following code:
myCompSource.SetTaggedValue(tag='test#one', item= myreplacementitem);
To delete the subtag entry "one" (and the object it references) in the tagged value "test", use the following code:
myCompSource.SetTaggedValue(tag='test#one', item= null);
Note: The "#" and "&" characters are both reserved and must not be used within tag or subtag names. Use of either "#" and "&" within tag or subtag names leads to unpredictable results.
value
Specifies a StringObject to be stored as the Value attribute of the tagged value being created or changed.
textvalue
Specifies a text value to be stored as the Value attribute of the tagged value being created or changed.
This method returns TV_ROW_CHANGED if entry for this tag was already present, TV_ROW_ADDED if the tag was not already present, or TV_FAIL if unsuccessful. Descriptions of system constant values and their numeric equivalents are listed in
Tagged Value Settings.