AISwatchListSuite Struct Reference
[API Suite List]

This suite provides functions that allow you to access and modify swatches and swatch lists. More...

#include <AISwatchList.h>

Public Attributes
ai::int32 ASAPI(*	CountSwatches )(AISwatchListRef list)
	Gets the total number of swatches in a swatch list, including those in all groups.
AISwatchRef ASAPI(*	GetFirstSwatch )(AISwatchListRef list)
	Retrieves the first swatch in a swatch list.
AISwatchRef ASAPI(*	GetNextSwatch )(AISwatchRef prev)
AISwatchRef ASAPI(*	GetNthSwatch )(AISwatchListRef list, ai::int32 index)
	Retrieves a swatch from a swatch list by position index.
AISwatchRef ASAPI(*	GetSwatchByName )(AISwatchListRef list, const ai::UnicodeString &name)
	Retrieves a swatch by name from a swatch list.
AISwatchRef ASAPI(*	InsertNthSwatch )(AISwatchListRef list, ai::int32 index)
	Creates a new swatch and inserts it into a swatch list.
ASErr ASAPI(*	RemoveNthSwatch )(AISwatchListRef list, ai::int32 index)
	Removes a swatch specified by index position from a swatch list.
ASErr ASAPI(*	GetAIColor )(AISwatchRef swatch, AIColor *aicolor)
	Retrieves the color definition of a swatch.
ASErr ASAPI(*	SetAIColor )(AISwatchRef swatch, AIColor *aicolor)
	Sets the color definition for a swatch.
ASErr ASAPI(*	GetSwatchName )(AISwatchRef swatch, ai::UnicodeString &name)
	Retrieves the name of a swatch.
ASErr ASAPI(*	SetSwatchName )(AISwatchRef swatch, const ai::UnicodeString &name)
	Sets the name of a swatch.
ASErr ASAPI(*	GetSwatchList )(AIDocumentHandle document, AISwatchListRef *list)
	Retrieves the swatch list for a document.
AISwatchRef ASAPI(*	GetSwatchByColor )(AISwatchListRef list, const AIColor *aicolor)
	Retrieves the first swatch in a list that uses a specified color.
AISwatchRef ASAPI(*	GetSwatchByNameAndType )(AISwatchListRef list, const ai::UnicodeString &name, AIColorTag type)
	Retrieves the first swatch in a list with a given name and color type.
ASErr ASAPI(*	RemoveSwatch )(AISwatchListRef list, AISwatchRef swatch, ASBoolean deleteCustomColor)
	Removes a specific swatch from a swatch list.

Detailed Description

This suite provides functions that allow you to access and modify swatches and swatch lists.

Each Illustrator document has an associated swatch list which contains the document�s color swatches as shown in the Swatches palette.

You can use GetSwatchList() or functions from the AISwatchLibrariesSuite to obtain a swatch list reference. Typically, however, you need only the current document's swatch list, so for convenience all functions that take an AISwatchListRef accept NULL to indicate the current document's swatch list.

The elements in a swatch list are of type AISwatchRef. A swatch is an AIColor and an associated name. For AIColor types that are themselves defined by a named object (custom colors, patterns and gradients) the swatch name is always the same as the name of the object. For other types of AIColor, the swatch name is independent.

Swatch lists are hierarchically organized into swatch groups, which can be named; see the AISwatchGroupSuite. In InsertNthSwatch(), an index of -1 inserts at the end of the general swatches group (group 0). Accessor functions in this suite treat groups as if they were flattened, so that an index of 0 is the first swatch in the first group, and index numbers simply continue into the next group. An exception is the deprecated GetNextSwatch(), which works only within a group. Use GetNthSwatch() instead for iteration.

There are three notifiers associated with swatch lists:
kAISwatchListChangedNotifier
kAISwatchListChangedInternallyNotifier
kAISwatchReplaceColorNotifier

Acquire this suite using SPBasicSuite::AcquireSuite() with the constants kAISwatchListSuite and kAISwatchListVersion.

Member Data Documentation

ai::int32 ASAPI(* AISwatchListSuite::CountSwatches)(AISwatchListRef list)

Gets the total number of swatches in a swatch list, including those in all groups.

(Note that this function returns a numeric value, not an error code.)

Parameters:

list The swatch list, or NULL for the current document's swatch list.

Returns:: The number of swatches in the list.

ASErr ASAPI(* AISwatchListSuite::GetAIColor)(AISwatchRef swatch, AIColor *aicolor)

Retrieves the color definition of a swatch.

Parameters:

	swatch	The swatch reference.
	aicolor	[out] A buffer in which to return the color definition. Can be any color type supported by Illustrator.

AISwatchRef ASAPI(* AISwatchListSuite::GetFirstSwatch)(AISwatchListRef list)

Retrieves the first swatch in a swatch list.

(Note that this function returns an object, not an error code.)

Parameters:

list The swatch list, or NULL for the current document's swatch list.

Returns:: The swatch reference.

See also:: GetNextSwatch()

AISwatchRef ASAPI(* AISwatchListSuite::GetNextSwatch)(AISwatchRef prev)

Deprecated:: Retrieves the next swatch in a swatch group within a swatch list. Use to find the swatch following one for which you do not have an index (retrieved, for example, with AISwatchListSuite::GetSwatchByNameAndType()). Do not use for iteration. (Note that this function returns an object, not an error code.)

Note:: It is recommended that you use CountSwatches() and GetNthSwatch() for iteration. This function cannot be used to iterate through a list that contains multiple groups, and is inefficient for iteration even within a group. .

Parameters:

prev

The previous swatch in the list.

Returns:: The swatch reference, or NULL if the previous swatch is the last in the group.

See also:: AISwatchGroupSuite::LocateSwatch() to find a swatch with an unknown index.

AISwatchRef ASAPI(* AISwatchListSuite::GetNthSwatch)(AISwatchListRef list, ai::int32 index)

Retrieves a swatch from a swatch list by position index.

Use with CountSwatches() to iterate through swatches. This is more efficient than GetNextSwatch() (Note that this function returns an object, not an error code.)

Parameters:

	list	The swatch list, or `NULL` for the current document's swatch list.
	index	The 0-based position index in the list, disregarding groups.

Returns:: The swatch reference.

AISwatchRef ASAPI(* AISwatchListSuite::GetSwatchByColor)(AISwatchListRef list, const AIColor *aicolor)

Retrieves the first swatch in a list that uses a specified color.

For patterns and gradients, checks only that the gradient or pattern objects match, does not check that other parameters such as the gradient matrix also match. For all other types, checks all color fields. (Note that this function returns an object, not an error code.)

Parameters:

	list	The swatch list, or `NULL` for the current document's swatch list.
	aicolor	The color to match.

Returns:: The matching swatch reference.

AISwatchRef ASAPI(* AISwatchListSuite::GetSwatchByName)(AISwatchListRef list, const ai::UnicodeString &name)

Retrieves a swatch by name from a swatch list.

(Note that this function returns an object, not an error code.)

Parameters:

	list	The swatch list, or `NULL` for the current document's swatch list.
	name	The swatch name.

Returns:: The swatch reference, or a NULL swatch reference if no such swatch name is found.

AISwatchRef ASAPI(* AISwatchListSuite::GetSwatchByNameAndType)(AISwatchListRef list, const ai::UnicodeString &name, AIColorTag type)

Retrieves the first swatch in a list with a given name and color type.

(Note that this function returns an object, not an error code.)

Parameters:

	list	The swatch list, or `NULL` for the current document's swatch list.
	name	The color name to match.
	type	The color type to match.

Returns:: The matching swatch reference.

ASErr ASAPI(* AISwatchListSuite::GetSwatchList)(AIDocumentHandle document, AISwatchListRef *list)

Retrieves the swatch list for a document.

Parameters:

	document	The document, or `NULL` for the current document. Use the `AIDocumentListSuite` or `AIPathStyleSuite::ImportStyles()` to obtain a document handle.
	list	[out] A buffer in which to return the swatch list.

ASErr ASAPI(* AISwatchListSuite::GetSwatchName)(AISwatchRef swatch, ai::UnicodeString &name)

Retrieves the name of a swatch.

Parameters:

	swatch	The swatch reference.
	name	[out] A buffer in which to return the name string.

AISwatchRef ASAPI(* AISwatchListSuite::InsertNthSwatch)(AISwatchListRef list, ai::int32 index)

Creates a new swatch and inserts it into a swatch list.

Use SetSwatchName() and SetAIColor() to set the name and color of the swatch after it has been inserted. (Note that this function returns an object, not an error code.)

Parameters:

list The swatch list, or NULL for the current document's swatch list.

index

The 0-based position index for the insertion point, disregarding groups.

If this is the first position of a named group in the list, the swatch is inserted into the preceding group. Use AISwatchGroupSuite to control the group placement explicitly.
A value of -1 appends the new swatch at the end of the general swatches group (group 0).

The positions of the swatch previously at this index, and of all succeeding swatches, are incremented.

Returns:: The swatch reference for the new swatch.

ASErr ASAPI(* AISwatchListSuite::RemoveNthSwatch)(AISwatchListRef list, ai::int32 index)

Removes a swatch specified by index position from a swatch list.

If the swatch is a custom color swatch and it contains the last reference to that global color in the swatch list, then the custom color is also deleted from the document and any usages replaced by the equivalent process color.

Parameters:

	list	The swatch list, or `NULL` for the current document's swatch list.
	index	The 0-based position index of the swatch, disregarding groups. The positions of all succeeding swatches, are decremented.

Returns:: kCantDeleteSwatchErr if the index is out of range.

ASErr ASAPI(* AISwatchListSuite::RemoveSwatch)(AISwatchListRef list, AISwatchRef swatch, ASBoolean deleteCustomColor)

Removes a specific swatch from a swatch list.

This is relatively inefficient, because it must search the entire swatch list for the swatch. If you know the swatch group and index, and if it is not a custom color or you want to remove custom colors, then AISwatchGroupSuite::RemoveNthSwatch() is more efficient.

Parameters:

	list	The swatch list, or `NULL` for the current document's swatch list.
	swatch	The swatch reference.
	deleteCustomColor	When true, and the swatch references a custom color, also deletes the custom color. In this case, objects that use the color are converted to process colors.

ASErr ASAPI(* AISwatchListSuite::SetAIColor)(AISwatchRef swatch, AIColor *aicolor)

Sets the color definition for a swatch.

Parameters:

	swatch	The swatch reference.
	aicolor	The new color definition. Can be any color type supported by Illustrator, if the type is allowed in the containing swatch group.

Returns:: The error kInvalidSwatchTypeForDest if the color type is not allowed in the containing swatch group.

ASErr ASAPI(* AISwatchListSuite::SetSwatchName)(AISwatchRef swatch, const ai::UnicodeString &name)

Sets the name of a swatch.

If the swatch identifies a custom color, pattern, or gradient, also changes the name of the underlying object.

Parameters:

	swatch	The swatch reference.
	name	The new name string.Limit is 31 chars, more than 31 chars will be removed

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

AISwatchList.h

AISwatchListSuite Struct Reference [API Suite List]

Public Attributes

Detailed Description

Member Data Documentation

AISwatchListSuite Struct Reference
[API Suite List]