AITagSuite Struct Reference
[API Suite List]

Tags allow you to assign arbitrary data to Illustrator artwork objects. More...

#include <AITag.h>

List of all members.

Public Attributes
AIErr(*	SetTag )(void *object, const char *name, const char *type,...)
	Associates a tag with an art object.
AIErr(*	GetTag )(void *object, const char *name, const char *type,...)
	Retrieves a tag for an object.
AIErr(*	GetTagType )(void *object, const char *name, const char **type)
	Gets the type of a tag (always "string"), and can be used to determine whether a tag of a given name exists.
AIErr(*	GetTagChangeCount )(void *object, const char *name, ai::int32 *count)
	Retrieves the number of times an object tag has changed.
AIErr(*	RemoveTag )(void *object, const char *name)
	Frees memory associated with a tag.
AIErr(*	CountTags )(void *object, ai::int32 *count)
	Reports how many tags are associated with an object.
AIErr(*	GetNthTag )(void *object, ai::int32 n, char **name)
	Retrieves a tag from an art object by position index.

---

Detailed Description

Tags allow you to assign arbitrary data to Illustrator artwork objects.

This suite is generally deprecated in favor of the more powerful facilities provided by the AIDictionarySuite. Tags are actually stored as string entries in the art object dictionary. Use AIArtSuite::GetDictionary() to get the art object dictionary.

A tag is data attached to an artwork object, containing a descriptive name, a tag type, a change count, and the tag data itself.

• A tag name can contain up to 30 characters (alphanumeric characters and '_'). Illustrator does not check for duplicate names, so you should make sure you choose unique tag names. Do not use spaces in tag names.
• The only tag type supported by Illustrator is "string", which represents a null-terminated C string up to 200 characters.
• Each time an artwork tag is changed, Illustrator increments the change count.

The kAITagChangedNotifier is associated with the tag suite.

• Acquire this suite using SPBasicSuite::AcquireSuite() with the constants kAITagSuite and kAITagVersion.

---

Member Data Documentation

AIErr(* AITagSuite::CountTags)(void *object, ai::int32 *count)

Reports how many tags are associated with an object.

Use with GetNthTag() to iterate through tags.

Parameters:

	object	The object, an AIArtHandle.
	count	[out] A buffer in which to return the number of tags.

AIErr(* AITagSuite::GetNthTag)(void *object, ai::int32 n, char **name)

Retrieves a tag from an art object by position index.

Use with CountTags() to iterate through tags.

Parameters:

	object	The object, an AIArtHandle.
	n	The 0-based position index.
	name	[out] A buffer in which to return the unique identifier for the tag.

AIErr(* AITagSuite::GetTag)(void *object, const char *name, const char *type,...)

Retrieves a tag for an object.

Parameters:

	object	The object, an AIArtHandle.
	name	The unique identifier for the tag.
	type	The tag type, the literal "string".

Additional arguments that follow depend on the type of data. For string types, pass a pointer to a char * in which to return the string associated with the tag. You do not need to allocate space for the tag string; the function returns a pointer to the existing string. Do not directly modify the string; use SetTag() instead.

AIErr(* AITagSuite::GetTagChangeCount)(void *object, const char *name, ai::int32 *count)

Retrieves the number of times an object tag has changed.

Parameters:

	object	The object, an AIArtHandle.
	name	The unique identifier for the tag.
	count	[out] A buffer in which to return the number of changes.

AIErr(* AITagSuite::GetTagType)(void *object, const char *name, const char **type)

Gets the type of a tag (always "string"), and can be used to determine whether a tag of a given name exists.

Parameters:

	object	The object, an AIArtHandle.
	name	The unique identifier for the tag.
	type	[out] Optional. A pointer to a pointer in which to return the address of the tag type string if the tag exists. Call with NULL to opt out.

AIErr(* AITagSuite::RemoveTag)(void *object, const char *name)

Frees memory associated with a tag.

Do not remove tags that you did not create.

Parameters:

	object	The object, an AIArtHandle
	name	The unique identifier for the tag.

AIErr(* AITagSuite::SetTag)(void *object, const char *name, const char *type,...)

Associates a tag with an art object.

Parameters:

	object	The object, an AIArtHandle.
	name	A unique identifier for the tag.
	type	The tag type, the literal "string".

Additional arguments that follow depend on the type of data. For string types, pass a pointer to the C string to be associated with the tag.

---

The documentation for this struct was generated from the following file:

• AITag.h