AISwatchGroupSuite Struct Reference
[API Suite List]

Swatch lists are hierarchically organized into swatch groups, which can be named. More...

#include <AISwatchList.h>

Public Attributes
ai::int32 ASAPI(*	CountSwatchGroups )(AISwatchListRef list)
	Reports the number of swatch groups in a swatch list.
AISwatchGroupRef(*	GetNthSwatchGroup )(AISwatchListRef list, ai::int32 index)
	Retrieves a swatch group from a swatch list.
AISwatchGroupRef ASAPI(*	GetSwatchGroupByName )(AISwatchListRef list, const ai::UnicodeString &name)
	Retrieves a swatch group by name from a swatch list.
ASErr ASAPI(*	NewSwatchGroup )(AISwatchListRef list, AISwatchGroupKind groupKind, ai::int32 atIndex, AISwatchGroupRef *newGroup)
	Creates a new swatch group in a swatch list.
ASBoolean ASAPI(*	SwatchGroupIsInList )(AISwatchListRef list, AISwatchGroupRef swatchGroup, ai::int32 *indexFoundAt)
	Reports whether a swatch group is in a swatch list.
ASErr ASAPI(*	RemoveNthSwatchGroup )(AISwatchListRef list, ai::int32 index, ASBoolean deleteSwatches)
	Removes a swatch group from a swatch list by index position.
ASErr ASAPI(*	RemoveSwatchGroup )(AISwatchListRef list, AISwatchGroupRef swatchGroup, ASBoolean deleteSwatches)
	Removes a specific swatch group from a swatch list.
ASErr ASAPI(*	ReorderNthSwatchGroup )(AISwatchListRef list, ai::int32 fromIndex, ai::int32 newIndex)
	Changes the position of a swatch group specified by index within a swatch list.
ASErr ASAPI(*	ReorderSwatchGroup )(AISwatchListRef list, AISwatchGroupRef swatchGroup, ai::int32 newIndex)
	Changes the position of a swatch group specified by reference within a swatch list.
ASErr ASAPI(*	GetSwatchGroupName )(AISwatchGroupRef swatchGroup, ai::UnicodeString &name)
	Retrieves the name of a swatch group.
ASErr ASAPI(*	SetSwatchGroupName )(AISwatchGroupRef swatchGroup, const ai::UnicodeString &name)
	Sets the name of a swatch group.
AISwatchGroupKind ASAPI(*	GetSwatchGroupKind )(AISwatchGroupRef swatchGroup)
	Reports what kind of swatches a group can contain.
ASBoolean ASAPI(*	AllowsColorKind )(AISwatchGroupRef swatchGroup, AIColorTag colorKind)
	Reports whether a swatch group allows colors of a specific type.
ASErr ASAPI(*	ReorderSwatch )(AISwatchGroupRef swatchGroup, AISwatchRef swatch, ai::int32 toIndex)
	Moves a swatch to a new position within a swatch group.
ASErr ASAPI(*	ReorderNthSwatch )(AISwatchGroupRef swatchGroup, ai::int32 fromIndex, ai::int32 toIndex)
	Move the swatch at fromIndex to toIndex within the same group.
ai::int32 ASAPI(*	CountSwatches )(AISwatchGroupRef swatchGroup)
	Reports the number of swatches in a swatch group.
AISwatchRef ASAPI(*	GetNthSwatch )(AISwatchGroupRef swatchGroup, ai::int32 index)
	Retrieves a swatch from a swatch group by position index.
AISwatchRef ASAPI(*	GetSwatchByName )(AISwatchGroupRef swatchGroup, const ai::UnicodeString &name)
	Retrieves a swatch from a swatch group by name.
AISwatchRef ASAPI(*	GetSwatchByColor )(AISwatchGroupRef swatchGroup, const AIColor *aicolor)
	Retrieves the first swatch within a swatch group with a specified color.
AISwatchRef ASAPI(*	GetSwatchByNameAndType )(AISwatchGroupRef swatchGroup, const ai::UnicodeString &name, AIColorTag type)
	Retrieves the first swatch within a swatch group with a given name and color type.
AISwatchRef ASAPI(*	InsertNthSwatch )(AISwatchGroupRef swatchGroup, AIColor *aicolor, ai::int32 index)
	Creates a new swatch and inserts it into a swatch group.
ASErr ASAPI(*	RemoveNthSwatch )(AISwatchGroupRef swatchGroup, ai::int32 index, ASBoolean deleteCustomColor, bool swatchNotUsed)
	Removes a swatch specified by index position from a swatch group.
ASErr ASAPI(*	RemoveSwatch )(AISwatchGroupRef swatchGroup, AISwatchRef swatch, ASBoolean deleteCustomColor)
	Removes a specific swatch from a group.
ASErr ASAPI(*	LocateSwatch )(AISwatchListRef list, AISwatchRef swatch, AISwatchGroupRef containingSwatchGroup, ai::int32 groupIndex, ai::int32 *swatchIndex)
	Retrieves the group of a specific swatch in a swatch list.
ASErr ASAPI(*	ReorderSwatchBetweenGroups )(AISwatchGroupRef fromGroup, ai::int32 fromIndex, AISwatchGroupRef toGroup, ai::int32 toIndex)
	Moves a swatch from one group to another within the same list.
ASBoolean ASAPI(*	WantsToBeOpenIfInListView )(AISwatchGroupRef swatchGroup)
	Reports whether a swatch group is displayed in the open state (showing swatches) the next time it is loaded into a palette that is in list view and shows color groups.
ASErr ASAPI(*	SetWantsToBeOpenIfInListView )(AISwatchGroupRef swatchGroup, ASBoolean whatItWants)
	Sets whether a swatch group is displayed in the open state (showing swatches) the next time it is loaded into a palette that is in list view and shows color groups.

Detailed Description

Swatch lists are hierarchically organized into swatch groups, which can be named.

This suite provides functions to create, access, and manipulate the groups, and explicitly control the group placement of swatches within the list. Swatch groups were introduced in Illustrator 13.

The first group, called the general swatch group, is typically unnamed and can contain any type of swatch. The first swatch group can be named, but cannot be removed or reordered. Swatches that are not assigned to a specific group are considered part of the general swatch group. If no groups have been defined, all swatches are in this group, whose index is 0.

Other groups are explicitly created and named, and can restrict the types of swatches that belong to them. The first such group is at index 1.

See also:: AISwatchListSuite

Acquire this suite using SPBasicSuite::AcquireSuite() with the constants kAISwatchGroupSuite and kAISwatchGroupVersion.

Member Data Documentation

ASBoolean ASAPI(* AISwatchGroupSuite::AllowsColorKind)(AISwatchGroupRef swatchGroup, AIColorTag colorKind)

Reports whether a swatch group allows colors of a specific type.

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

Parameters:

	swatchGroup	The swatch group object.
	colorKind	The color type constant.

Returns:: True if the type is allowed.

ai::int32 ASAPI(* AISwatchGroupSuite::CountSwatches)(AISwatchGroupRef swatchGroup)

Reports the number of swatches in a swatch group.

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

Parameters:

swatchGroup

The swatch group object.

Returns:: The number of swatches.

ai::int32 ASAPI(* AISwatchGroupSuite::CountSwatchGroups)(AISwatchListRef list)

Reports the number of swatch groups in a swatch list.

There is always at least one, the unnamed general swatch group. (Note that this function returns an integer value, not an error code.)

Parameters:

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

Returns:: The number of swatch groups.

AISwatchRef ASAPI(* AISwatchGroupSuite::GetNthSwatch)(AISwatchGroupRef swatchGroup, ai::int32 index)

Retrieves a swatch from a swatch group by position index.

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

Parameters:

	swatchGroup	The swatch group object.
	index	The 0-based position index.

Returns:: The swatch object, or a NULL object if the index is invalid.

AISwatchGroupRef(* AISwatchGroupSuite::GetNthSwatchGroup)(AISwatchListRef list, ai::int32 index)

Retrieves a swatch group from a swatch list.

(Note that this function returns an object value, 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 of groups. The first named group, if any, is at index 1.

Returns:: The swatch group reference.

AISwatchRef ASAPI(* AISwatchGroupSuite::GetSwatchByColor)(AISwatchGroupRef swatchGroup, const AIColor *aicolor)

Retrieves the first swatch within a swatch group with a specified color.

For patterns and gradients, checks that the gradient or pattern objects match, but does not check that the other parameters such as the gradient matrix or pattern matrix also match. For all other types, checks all fields for a match. In particular, spot color and global color swatches check the tint. (Note that this function returns an object value, not an error code.)

Parameters:

	swatchGroup	The swatch group object.
	aicolor	The color.

Returns:: The swatch object, or a NULL object if no matching swatch is found.

AISwatchRef ASAPI(* AISwatchGroupSuite::GetSwatchByName)(AISwatchGroupRef swatchGroup, const ai::UnicodeString &name)

Retrieves a swatch from a swatch group by name.

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

Parameters:

	swatchGroup	The swatch group object.
	name	The swatch name string.

Returns:: The swatch object, or a NULL object if no matching swatch is found.

AISwatchRef ASAPI(* AISwatchGroupSuite::GetSwatchByNameAndType)(AISwatchGroupRef swatchGroup, const ai::UnicodeString &name, AIColorTag type)

Retrieves the first swatch within a swatch group with a given name and color type.

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

Parameters:

	swatchGroup	The swatch group object.
	name	The swatch name string.
	type	The color type constant.

Returns:: The swatch object, or a NULL object if no matching swatch is found.

AISwatchGroupRef ASAPI(* AISwatchGroupSuite::GetSwatchGroupByName)(AISwatchListRef list, const ai::UnicodeString &name)

Retrieves a swatch group by name from a swatch list.

Group names need not be unique with a list; if there is more than one matching group, the first one is returned. (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 group name.

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

AISwatchGroupKind ASAPI(* AISwatchGroupSuite::GetSwatchGroupKind)(AISwatchGroupRef swatchGroup)

Reports what kind of swatches a group can contain.

This is set on creation and cannot be modified. (Note that this function returns a constant value, not an error code.)

Parameters:

swatchGroup

The swatch group object.

Returns:: The allowed-swatch-type constant.

ASErr ASAPI(* AISwatchGroupSuite::GetSwatchGroupName)(AISwatchGroupRef swatchGroup, ai::UnicodeString &name)

Retrieves the name of a swatch group.

Parameters:

	swatchGroup	The swatch group object.
	name	[out] A buffer in which to return the name string, or the empty string if no name has been assigned.

AISwatchRef ASAPI(* AISwatchGroupSuite::InsertNthSwatch)(AISwatchGroupRef swatchGroup, AIColor *aicolor, ai::int32 index)

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

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

Parameters:

	swatchGroup	The swatch group object.
	aicolor	The color for the new swatch.
	index	The 0-based index position at which to insert the new swatch, or -1 to append it to the end of the group. The swatch previously at this index and all swatches following it in the list are bumped down the list by one position.

Returns:: The new swatch object, or a NULL object if the index is invalid, there is not enough memory, the swatch group already contains kMaxNumberSwatchesPerGroup, or the swatch type is not allowed for this group. See AISwatchGroupKind.

ASErr ASAPI(* AISwatchGroupSuite::LocateSwatch)(AISwatchListRef list, AISwatchRef swatch, AISwatchGroupRef *containingSwatchGroup, ai::int32 *groupIndex, ai::int32 *swatchIndex)

Retrieves the group of a specific swatch in a swatch list.

Requires an exact match with the swatch object; swatches for the same color and name are not considered equivalent.

Parameters:

	list	The swatch list, or `NULL` for the current document's swatch list.
	swatch	The swatch object.
	containingSwatchGroup	[out] A buffer in which to return the containing group object, or a `NULL` object if the swatch is not in the list.
	groupIndex	[out] Optional. A buffer in which to return the 0-based index position of this group within the list.
	swatchIndex	[out] Optional. A buffer in which to return the 0-based index position of this swatch within the group.

ASErr ASAPI(* AISwatchGroupSuite::NewSwatchGroup)(AISwatchListRef list, AISwatchGroupKind groupKind, ai::int32 atIndex, AISwatchGroupRef *newGroup)

Creates a new swatch group in a swatch list.

The new group is initially unnamed and contains no swatches. Use SetSwatchGroupName() to assign a name, and InsertNthSwatch() or ReorderSwatchBetweenGroups() to add members.

Parameters:

	list	The swatch list, or `NULL` for the current document's swatch list.
	groupKind	The types of swatches that are allowed in the group.
	atIndex	The group position index at which to insert the group, or -1 to append it to the current groups.
	swatchGroup	[out] A buffer in which to return the new swatch group object.

Returns:: kBadParameterErr if index is 0.
kTooManySwatchGroupsErr if there are already kMaxNumberSwatchGroups in the swatch list.

ASErr ASAPI(* AISwatchGroupSuite::RemoveNthSwatch)(AISwatchGroupRef swatchGroup, ai::int32 index, ASBoolean deleteCustomColor, bool swatchNotUsed)

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

Parameters:

	swatchGroup	The swatch group object.
	index	The 0-based index position of the swatch in the group. Other swatch position index values are adjusted accordingly.
	deleteCustomColor	When true, and the swatch is a custom color swatch and contains the last reference to that custom color in the entire swatch list, the custom color is also deleted from the document and any usages replaced by the equivalent process color. When false, deletes a custom color only if it is unused. Otherwise, moves it to the general group. If this is the general group, the swatch is in use, and this is the only reference in the list, the function returns `kCantDeleteSwatchErr`.
	swatchNotUsed	When true, global colors are not replaced in the document and are forcefully deleted. It should be used, if it is already been ensured that the color is not used anywhere.

Returns:: kBadParameterErr if the index is not within the swatch group.
kCantDeleteSwatchErr if the swatch cannot be deleted for any reason.

ASErr ASAPI(* AISwatchGroupSuite::RemoveNthSwatchGroup)(AISwatchListRef list, ai::int32 index, ASBoolean deleteSwatches)

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

You cannot remove the general swatch group (index 0). The index positions of all later groups are decremented.

Parameters:

	list	The swatch list, or `NULL` for the current document's swatch list.
	index	The 0-based index position of the swatch to remove.
	deleteSwatches	When false, moves the member swatches into the general group, unless a swatch with the same name and definition is already in that group. When true, deletes the member swatches along with the group. If a member swatch is a custom color swatch and it contains the last reference to a global color in the swatch list, the custom color is not deleted from the document. Use `AISwatchGroupSuite::RemoveSwatch()` to delete the last reference to a spot color.

Returns:: kCantDeleteSwatchErr if the index is 0 or greater than the number of swatch groups, or if the swatch group contains an undeletable swatch.

ASErr ASAPI(* AISwatchGroupSuite::RemoveSwatch)(AISwatchGroupRef swatchGroup, AISwatchRef swatch, ASBoolean deleteCustomColor)

Removes a specific swatch from a group.

Swatch position index values are adjusted accordingly. (If the index is known, RemoveNthSwatch() is more efficient.)

Parameters:

	swatchGroup	The swatch group object.
	swatch	The swatch object.
	deleteCustomColor	When true, and the swatch is a custom color swatch and contains the last reference to that custom color in the entire swatch list, the custom color is also deleted from the document and any usages replaced by the equivalent process color. When false, deletes a custom color only if it is unused. Otherwise, moves it to the general group. If this is the general group, the swatch is in use, and this is the only reference in the list, the function returns `kCantDeleteSwatchErr`.

Returns:: kBadParameterErr if the swatch is not in the swatch group.
kCantDeleteSwatchErr if the swatch cannot be deleted for any reason.

ASErr ASAPI(* AISwatchGroupSuite::RemoveSwatchGroup)(AISwatchListRef list, AISwatchGroupRef swatchGroup, ASBoolean deleteSwatches)

Removes a specific swatch group from a swatch list.

Parameters:

	list	The swatch list, or `NULL` for the current document's swatch list.
	swatchGroup	The swatch group object.
	deleteSwatches	When false, moves the member swatches into the general group, unless a swatch with the same name and definition is already in that group. When true, deletes the member swatches along with the group. If a member swatch is a custom color swatch and it contains the last reference to a global color in the swatch list, the custom color is not deleted from the document. Use `AISwatchGroupSuite::RemoveSwatch()` to delete the last reference to a spot color.

Returns:: kBadParameterErr if the swatch group is not in the list.

Note:: This function must search the entire list. If you have the index position of the group, RemoveNthSwatchGroup () is more efficient.

ASErr ASAPI(* AISwatchGroupSuite::ReorderNthSwatch)(AISwatchGroupRef swatchGroup, ai::int32 fromIndex, ai::int32 toIndex)

Move the swatch at fromIndex to toIndex within the same group.

toIndex can be -1 to move to the end. Returns kBadParameterErr if either fromIndex or toIndex is greater than count-1, or if fromIndex is less than 0. Moves a swatch to a new position within a swatch group.

Parameters:

	swatchGroup	The swatch group object.
	fromIndex	The current 0-based index position of the swatch.
	toIndex	The new 0-based index position, or -1 to move the swatch to the end of the group. Other position index values change accordingly.

Returns:: kBadParameterErr if either index is greater than the number of swatches in the group, or if the from index is less than 0.

ASErr ASAPI(* AISwatchGroupSuite::ReorderNthSwatchGroup)(AISwatchListRef list, ai::int32 fromIndex, ai::int32 newIndex)

Changes the position of a swatch group specified by index within a swatch list.

Other group index values change accordingly. You cannot move another group to position 0, or move the general group to any other position.

Parameters:

	list	The swatch list, or `NULL` for the current document's swatch list.
	fromIndex	The current 0-based position index of the group to move.
	newIndex	The new 0-based position index.

Returns:: kBadParameterErr if either index is 0, or is greater than the number of swatch groups.
If both index values are 0, returns kNoErr but does nothing.

ASErr ASAPI(* AISwatchGroupSuite::ReorderSwatch)(AISwatchGroupRef swatchGroup, AISwatchRef swatch, ai::int32 toIndex)

Moves a swatch to a new position within a swatch group.

Parameters:

	swatchGroup	The swatch group object.
	swatch	The swatch object.
	toIndex	The new 0-based index position, or -1 to move the swatch to the end of the group. Other position index values change accordingly.

Returns:: kBadParameterErr if the index is greater than the number of swatches in the group, or if the swatch is not in the group.

ASErr ASAPI(* AISwatchGroupSuite::ReorderSwatchBetweenGroups)(AISwatchGroupRef fromGroup, ai::int32 fromIndex, AISwatchGroupRef toGroup, ai::int32 toIndex)

Moves a swatch from one group to another within the same list.

Other index positions within both groups are adjusted accordingly.

Parameters:

	fromGroup	The group object that currently contains the swatch.
	fromIndex	The 0-based index of the swatch in the current group.
	toGroup	The destination group object.
	toIndex	The 0-based index at which to insert the swatch in the destination group, or -1 to append it to the end of the group.

Returns:: kBadParameterErr if the source index is less than 0, or if either index is greater than the number of swatches in its group, or if the two swatch groups are not in the same swatch list.
kInvalidSwatchTypeForDest if the swatch is a type that is not allowed in the destination group.

ASErr ASAPI(* AISwatchGroupSuite::ReorderSwatchGroup)(AISwatchListRef list, AISwatchGroupRef swatchGroup, ai::int32 newIndex)

Changes the position of a swatch group specified by reference within a swatch list.

Other group index values change accordingly. You cannot move another group to position 0, or move the general group to any other position.

Parameters:

	list	The swatch list, or `NULL` for the current document's swatch list.
	swatchGroup	The swatch group object.
	newIndex	The new 0-based position index.

Returns:: kBadParameterErr if the new index is 0, or is greater than the number of swatch groups. or if the group is not in the list, or is the general group.

Note:: This function must search the entire list. If you have the index position of the group, ReorderNthSwatchGroup () is more efficient.

ASErr ASAPI(* AISwatchGroupSuite::SetSwatchGroupName)(AISwatchGroupRef swatchGroup, const ai::UnicodeString &name)

Sets the name of a swatch group.

Group names need not be unique.

Parameters:

	swatchGroup	The swatch group object.
	name	The new name string.

ASErr ASAPI(* AISwatchGroupSuite::SetWantsToBeOpenIfInListView)(AISwatchGroupRef swatchGroup, ASBoolean whatItWants)

Sets whether a swatch group is displayed in the open state (showing swatches) the next time it is loaded into a palette that is in list view and shows color groups.

This status is saved on behalf of the Swatches palette, so that it can persist while the document is closed or inactive.

If a plug-in other than the Swatches palette changes this value, it does not, by itself, trigger an update to the Swatches palette. However, it the change is made at the same time as another change that does trigger an update, such as adding a new swatch group or a new swatch, the Swatches palette honors the setting when the swatch group is next displayed in list view.

Parameters:

	swatchGroup	The swatch group object.
	whatItWants	True to display the group in the open state, false to display it in the closed state.

Returns:: kBadParameterErr if the no swatch group is supplied.

ASBoolean ASAPI(* AISwatchGroupSuite::SwatchGroupIsInList)(AISwatchListRef list, AISwatchGroupRef swatchGroup, ai::int32 *indexFoundAt)

Reports whether a swatch group is in a swatch list.

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

Parameters:

	list	The swatch list, or `NULL` for the current document's swatch list.
	swatchGroup	The swatch group object.
	indexFoundAt	[out] A buffer in which to return the 0-based index into the swatch list at which the group was found.

Returns:: True if the group is in the list.

ASBoolean ASAPI(* AISwatchGroupSuite::WantsToBeOpenIfInListView)(AISwatchGroupRef swatchGroup)

Reports whether a swatch group is displayed in the open state (showing swatches) the next time it is loaded into a palette that is in list view and shows color groups.

This status is saved on behalf of the Swatches palette, so that it can persist while the document is closed or inactive.

This preference does not guarantee that the swatches are visible, even if this swatch group is in the active document, because the Swatches palette might not show color groups, or might not be in list view. (Note that this function returns a boolean value, not an error code.)

Parameters:

swatchGroup

The swatch group object.

Returns:: True if the swatch group should be open in list view.

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

AISwatchList.h

AISwatchGroupSuite Struct Reference [API Suite List]

Public Attributes

Detailed Description

Member Data Documentation

AISwatchGroupSuite Struct Reference
[API Suite List]