AISwatchLibrariesSuite Struct Reference

Supplied by the Swatch Libraries plug-in, these functions allow you to open, access, and manipulate libraries of color, custom color, pattern, and gradient swatches, also called swatch lists. More...

#include <AISwatchLibraries.h>

List of all members.

Public Attributes
AIErr ASAPI(*	CountLibraries )(ai::int32 *num)
	Gets the number of currently known swatch libraries, including the swatch list of the current open document.
AIErr ASAPI(*	GetNthLibrary )(ai::int32 num, AISwatchListRef *swatchlist)
	Retrieves the swatch list for a known swatch library by position index.
AIErr ASAPI(*	GetNthLibraryName )(ai::int32 num, ai::UnicodeString &name)
	Retrieves the name of any swatch library in the list, whether it has been opened or not.
AIErr ASAPI(*	CountLibrarySwatches )(ai::int32 *num)
	Counts the aggregate number of all swatches in all libraries that have swatch lists.
AIErr ASAPI(*	GetNthLibrarySwatch )(ai::int32 num, AISwatchRef *swatch)
	Retrieves a swatch by position index from the list of all swatches.
AIErr ASAPI(*	CountLibraryPatterns )(ai::int32 *num)
	Counts the aggregate number of all pattern swatches in all open libraries.
AIErr ASAPI(*	GetNthLibraryPattern )(ai::int32 num, AIPatternHandle *pattern)
	Retrieves a pattern swatch by position index from the list of all patterns.
AIErr ASAPI(*	CountLibraryGradients )(ai::int32 *num)
	Counts the aggregate number of all gradient swatches in all open libraries.
AIErr ASAPI(*	GetNthLibraryGradient )(ai::int32 num, AIGradientHandle *gradient)
	Retrieves a gradient swatch by position index from the list of all gradients.
AIErr ASAPI(*	CountLibraryCustomColors )(ai::int32 *num)
	Counts the aggregate number of all custom color swatches in all open libraries.
AIErr ASAPI(*	GetNthLibraryCustomColor )(ai::int32 num, AICustomColorHandle *ccolor)
	Retrieves a custom color swatch by position index from the list of all custom color swatches.
AIBoolean ASAPI(*	FindStandardBookColor )(const ai::UnicodeString &name, AICustomColor *color)
	Searches the color books to find the definition of a specific named color.
AIBoolean ASAPI(*	FindLegacyBookColor )(const ai::UnicodeString &name, AICustomColor *color)
	Searches the legacy color books to find the previous definition of a specific named color.
AIErr ASAPI(*	MapLegacyColorName )(const ai::UnicodeString &src, ai::UnicodeString &dst)
	Maps a legacy color name to its corresponding name in the current color books.
AIErr ASAPI(*	OpenNthLibrary )(ai::int32 num, AIBoolean showPalette, AISwatchListRef *swatchList)
	Retrieves a swatch list from a swatch library.
AIBoolean ASAPI(*	NthLibraryIsOpen )(ai::int32 num, bool shouldBeVisible)
	Reports whether a swatch library is currently displayed in an open palette.
AIBoolean ASAPI(*	SelectNthDocumentSwatchIfVisible )(ai::int32 index, AIBoolean deselectOthers)
	Selects a swatch in the main Swatches palette, if it is open and its color kind is shown.
AIBoolean ASAPI(*	SelectNthDocColorGroupIfVisible )(ai::int32 index, AIBoolean deselectOthers)
	Selects a color group and all of the group's swatches in the main Swatches palette, if it is open and the group is shown.
AIErr ASAPI(*	BuildLibrariesList )(AIMenuPtr librariesList, AISwatchLibraryType includeLibraryTypes, ai::int32 startIndex, ai::int32 contentChangeStampRef, int checkLibraryID)
	Rebuilds the libraries menu, populating it with the current list of libraries.
AIErr ASAPI(*	GetActiveSwatchList )(AISwatchListRef *swatchlist, ai::int32 activeLibraryID)
	Retrieves the swatch list for a swatch library by active list entry, opening the file and reading the swatches from it if it has not yet been opened during the session.
ai::int32 ASAPI(*	CountSelectedDocSwatches )()
	Counts the total number of selected swatches in the main document Swatches palette.
AIErr ASAPI(*	GetSelectedDocSwatchColors )(AIColor *colors, ai::int32 bufferSize)
	Retrieves an array of colors for the selected document swatches.
ai::int32 ASAPI(*	CountSelectedDocSwatchGroups )()
	Counts the total number of selected swatch groups in the document Swatch palette.
AIErr ASAPI(*	GetSelectedDocSwatchGroups )(AISwatchGroupRef *swatchGroups, ai::int32 bufferSize)
	Returns an array of the document's selected swatch groups.
AIErr ASAPI(*	GetRelativeDocSwatch )(AIRelativeDocSwatchKind selectKind, AIBoolean selectIt, AIBoolean wrap, AIWhichDocSwatchesPalette targetPalette, AISwatchRef *relativeSwatch)
	Retrieves a document swatch in a specified position in the list, relative to the currently active document swatch, as determined by `IADMHierachyList::GetActiveLeafEntry()`.
AIErr ASAPI(*	GetSelectedDocSwatchRefs )(AISwatchRef *swatchRefs, ai::int32 bufferSize)
	Retrieves an array of references of the selected document swatches.
AIBoolean ASAPI(*	FindColorInBook )(const ai::UnicodeString &name, ai::int32 bookID, AICustomColor *color)
	Searches the color book with specified ID to find the definition of a specified named color.
ai::int32 ASAPI(*	CountSelectedDocSwatchesNotInAnySelectedGroup )()
	Counts the total number of selected swatches in the main document Swatches palette not in a selected group.
AIErr ASAPI(*	GetSelectedDocSwatchRefsNotInAnySelectedGroup )(AISwatchRef *colors, ai::int32 bufferSize)
	Retrieves an array of colors for the selected document swatches not in any selected group.
AIErr ASAPI(*	GetNthLibraryPath )(ai::int32 num, ai::FilePath &path)
	Retrieves the absolute path of any swatch library in the list, whether it has been opened or not.
AIErr ASAPI(*	OpenLibraryByPath )(const ai::FilePath &path)
	Open the SwatchLibrary using library path.

Detailed Description

Supplied by the Swatch Libraries plug-in, these functions allow you to open, access, and manipulate libraries of color, custom color, pattern, and gradient swatches, also called swatch lists.

You can collect all swatches, or all patterns, gradients, or custom colors from all open libraries into a single list sorted by name, and iterate through the resulting swatch list.

Color books contain collections of pre-defined colors, such as the Pantone colors. Some color book definitions and names have changed from previous versions. For example, in Illustrator 12 and later, Pantone solids are LAB, but were formerly CMYK.

FindStandardBookColor() finds named colors in the current color books.
FindLegacyBookColor() find the previous color definition.
MapLegacyColorName() maps a legacy color name to a current one.

Member Data Documentation

AIErr ASAPI(* AISwatchLibrariesSuite::BuildLibrariesList)(AIMenuPtr librariesList, AISwatchLibraryType includeLibraryTypes, ai::int32 startIndex, ai::int32 *contentChangeStampRef, int *checkLibraryID)

Rebuilds the libraries menu, populating it with the current list of libraries.

The list is refreshed if the supplied change stamp does not match the supplied change stamp. The internal change stamp has an initial value of 1. Pass a change stamp of 0 to build the list the first time, or to force an update, or to uncheck all libraries in the list.

Parameters:

	librariesList	The ADM hierarchy list object for the libraries list.
	startIndex	The 0-based index at which the first library entry is created.
	includeLibraryTypes	The library types to include when building the list, a logical OR of `AISwatchLibraryType` values.
	contentChangeStampRef	[in/out] On input, a pointer to a change stamp number to compare with the current internal latest-change stamp. If the input stamp is less than the internal stamp, the list is updated, and this buffer filled with the new internal stamp value.
	checkLibraryID	Optional. A pointer to a library's unique identifier. The entry for that library is drawn with a check mark in the ADM list.

AIErr ASAPI(* AISwatchLibrariesSuite::CountLibraries)(ai::int32 *num)

Gets the number of currently known swatch libraries, including the swatch list of the current open document.

Use with GetNthLibrary() to iterate through known libraries.

A library is known if it is located in the Presets folder and appears in the Swatch Libraries menu, or if it has been opened at some time during the current session with the Other Libraries command. You can get a swatch list from a known library regardless of whether it is open or closed.

Note:: Closing a swatch palette does not remove its swatches from memory, but closing a document does clear the corresponding swatch list.

Parameters:

num

[out] A buffer in which to return the number of open libraries.

AIErr ASAPI(* AISwatchLibrariesSuite::CountLibraryCustomColors)(ai::int32 *num)

Counts the aggregate number of all custom color swatches in all open libraries.

Use with GetNthLibraryCustomColor() to iterate through all custom color swatches.

Parameters:

num

[out] A buffer in which to return the number of custom color swatches.

AIErr ASAPI(* AISwatchLibrariesSuite::CountLibraryGradients)(ai::int32 *num)

Counts the aggregate number of all gradient swatches in all open libraries.

Use with GetNthLibraryGradient() to iterate through all gradients.

Parameters:

num

[out] A buffer in which to return the number of gradients.

AIErr ASAPI(* AISwatchLibrariesSuite::CountLibraryPatterns)(ai::int32 *num)

Counts the aggregate number of all pattern swatches in all open libraries.

Use with GetNthLibraryPattern() to iterate through all patterns.

Parameters:

num

[out] A buffer in which to return the number of patterns.

AIErr ASAPI(* AISwatchLibrariesSuite::CountLibrarySwatches)(ai::int32 *num)

Counts the aggregate number of all swatches in all libraries that have swatch lists.

Use with GetNthLibrarySwatch() to iterate through all swatches.

Parameters:

num

[out] A buffer in which to return the number of swatches.

ai::int32 ASAPI(* AISwatchLibrariesSuite::CountSelectedDocSwatches)()

Counts the total number of selected swatches in the main document Swatches palette.

Use this function to allocate an appropriately sized array of AIColors before calling GetSelectedDocSwatchColors(). (Note that this function returns an integer value, not an error code.)

Returns:: The number of selected swatches.

ai::int32 ASAPI(* AISwatchLibrariesSuite::CountSelectedDocSwatchesNotInAnySelectedGroup)()

Counts the total number of selected swatches in the main document Swatches palette not in a selected group.

Use this function to allocate an appropriately sized array of AIColors before calling GetSelectedDocSwatchRefsNotInAnySelectedGroup(). (Note that this function returns an integer value, not an error code.)

Returns:: The number of selected swatches.

ai::int32 ASAPI(* AISwatchLibrariesSuite::CountSelectedDocSwatchGroups)()

Counts the total number of selected swatch groups in the document Swatch palette.

Use to allocate an array of AISwatchGroupRef before calling GetSelectedDocSwatchGroups().

Returns:: The number of selected swatch groups, or 0 if there is no document open or no Swatches palette.

AIBoolean ASAPI(* AISwatchLibrariesSuite::FindColorInBook)(const ai::UnicodeString &name, ai::int32 bookID, AICustomColor *color)

Searches the color book with specified ID to find the definition of a specified named color.

Color books contain collections of predefined colors, such as the Pantone colors. (Note that this function returns a boolean value, not an error code.)

Parameters:

	name	The name string of the desired color.
	bookID	The id for the book in which color should be searched.
	color	[out] A buffer in which to return the custom color definition, if found.

Returns:: True if the color is found, false otherwise.

AIBoolean ASAPI(* AISwatchLibrariesSuite::FindLegacyBookColor)(const ai::UnicodeString &name, AICustomColor *color)

Searches the legacy color books to find the previous definition of a specific named color.

A legacy color book need not have been opened to be included in the search. (Note that this function returns a boolean value, not an error code.)

Parameters:

	name	The name string of the desired color.
	color	[out] A buffer in which to return the custom color definition, if found.

Returns:: True if the color is found in a legacy color book, false otherwise.

AIBoolean ASAPI(* AISwatchLibrariesSuite::FindStandardBookColor)(const ai::UnicodeString &name, AICustomColor *color)

Searches the color books to find the definition of a specific named color.

Color books contain collections of predefined colors, such as the Pantone colors. A color book need not have been opened to be included in the search. (Note that this function returns a boolean value, not an error code.)

Parameters:

	name	The name string of the desired color.
	color	[out] A buffer in which to return the custom color definition, if found.

Returns:: True if the color is found in a color book, false otherwise.

AIErr ASAPI(* AISwatchLibrariesSuite::GetActiveSwatchList)(AISwatchListRef *swatchlist, ai::int32 activeLibraryID)

Retrieves the swatch list for a swatch library by active list entry, opening the file and reading the swatches from it if it has not yet been opened during the session.

Use the AISwatchListSuite to access and modify the returned list.

Parameters:

	librariesList	The ADM hierarchy list object for the libraries menu with the active entry.
	swatchlist	[out] A buffer in which to return the swatch list.
	activeLibraryID	[out] Optional, a buffer in which to return the active library's unique indentifier.

AIErr ASAPI(* AISwatchLibrariesSuite::GetNthLibrary)(ai::int32 num, AISwatchListRef *swatchlist)

Retrieves the swatch list for a known swatch library by position index.

Use with CountLibraries() to iterate through libraries. Use the AISwatchListSuite to access and modify the returned list.

Parameters:

	num	The 0-based position index. Use 0 or a negative number to get the swatch list for the current document. The first real library starts at index 1.
	swatchlist	[out] A buffer in which to return the swatch list, or `NULL` if the swatch library has not been opened during this session.

See also:: OpenNthLibrary() to open a library.

AIErr ASAPI(* AISwatchLibrariesSuite::GetNthLibraryCustomColor)(ai::int32 num, AICustomColorHandle *ccolor)

Retrieves a custom color swatch by position index from the list of all custom color swatches.

Use with CountLibraryCustomColors() to iterate through all custom color swatches.

Parameters:

	num	The 0-based position index.
	ccolor	[out] A buffer in which to return the custom color swatch.

AIErr ASAPI(* AISwatchLibrariesSuite::GetNthLibraryGradient)(ai::int32 num, AIGradientHandle *gradient)

Retrieves a gradient swatch by position index from the list of all gradients.

Use with CountLibraryGradients() to iterate through all gradients.

Parameters:

	num	The 0-based position index.
	gradient	[out] A buffer in which to return the gradient.

AIErr ASAPI(* AISwatchLibrariesSuite::GetNthLibraryName)(ai::int32 num, ai::UnicodeString &name)

Retrieves the name of any swatch library in the list, whether it has been opened or not.

Parameters:

	num	The 0-based position index of the library.
	name	[out] A buffer in which to return the name. The name of the swatch library for the current document (`num` <= 0) is the empty string.

AIErr ASAPI(* AISwatchLibrariesSuite::GetNthLibraryPath)(ai::int32 num, ai::FilePath &path)

Retrieves the absolute path of any swatch library in the list, whether it has been opened or not.

Parameters:

	num	The 0-based position index of the library.
	path	[out] returns the path of the nth Swatch Library

AIErr ASAPI(* AISwatchLibrariesSuite::GetNthLibraryPattern)(ai::int32 num, AIPatternHandle *pattern)

Retrieves a pattern swatch by position index from the list of all patterns.

Use with CountLibraryPatterns() to iterate through all patterns.

Parameters:

	num	The 0-based position index.
	pattern	[out] A buffer in which to return the pattern.

AIErr ASAPI(* AISwatchLibrariesSuite::GetNthLibrarySwatch)(ai::int32 num, AISwatchRef *swatch)

Retrieves a swatch by position index from the list of all swatches.

Use with CountLibrarySwatches() to iterate through all swatches.

Parameters:

	num	The 0-based position index.
	swatch	[out] A buffer in which to return the swatch.

AIErr ASAPI(* AISwatchLibrariesSuite::GetRelativeDocSwatch)(AIRelativeDocSwatchKind selectKind, AIBoolean selectIt, AIBoolean wrap, AIWhichDocSwatchesPalette targetPalette, AISwatchRef *relativeSwatch)

Retrieves a document swatch in a specified position in the list, relative to the currently active document swatch, as determined by IADMHierachyList::GetActiveLeafEntry().

If one swatch is selected, it is the active swatch. If multiple swatches are selected, the active one is the last swatch entry to be selected.

Parameters:

	selectKind	The position of the desired swatch, relative to the active swatch.
	selectIt	When true, the relative swatch becomes selected and all other swatches are deslected. When false, the swatch selection state remains unchanged.
	wrap	When true, the last swatch in a swatch group wraps to the first swatch in the same group, and the last swatch group wraps to the first group. When wrapping is on, if a swatch group only contains one swatch, the next or previous swatch is the same one. Similarly, if there is only one swatch group the next or previous group is the same group. Ungrouped swatches in the document swatch list are treated as if they are in a group that follows the last defined swatch group.
	targetPalette	The swatch palette to search in (main, fill, or stroke).
	relativeSwatch	[out] A buffer in which to return the swatch in the specified relation to the active swatch, or `NULL` if there is no active swatch or if there is no swatch at the relative location. The returned error reflects which condition occurred.

Returns:: The error kSwatchDoesNotExistErr if the next or previous swatch does not exist. When wrapping is on, this error cannot occur.
The error kNoActiveSwatchError if no swatch is currently selected in the specified Swatch palette.

AIErr ASAPI(* AISwatchLibrariesSuite::GetSelectedDocSwatchColors)(AIColor *colors, ai::int32 bufferSize)

Retrieves an array of colors for the selected document swatches.

The members are ordered as they appear in the document Swatches palette, left to right and top to bottom.

Parameters:

	colors	[out] A buffer in which to return the colors. Use `CountSelectedDocSwatches()` to determine how much memory to allocate.
	bufferSize	The number of elements in the colors array. If there are more selected colors, only this many are returned.

AIErr ASAPI(* AISwatchLibrariesSuite::GetSelectedDocSwatchGroups)(AISwatchGroupRef *swatchGroups, ai::int32 bufferSize)

Returns an array of the document's selected swatch groups.

The groups are ordered as they appear in the document Swatches palette, left to right and top to bottom.

Parameters:

	swatchGroups	[out] A buffer in which to return the groups. Use `CountSelectedDocSwatchGroups()` to determine how much memory to allocate.
	bufferSize	The number of elements in the groups array. If there are more selected groups, only this many are returned.

AIErr ASAPI(* AISwatchLibrariesSuite::GetSelectedDocSwatchRefs)(AISwatchRef *swatchRefs, ai::int32 bufferSize)

Retrieves an array of references of the selected document swatches.

The members are ordered as they appear in the document Swatches palette, left to right and top to bottom.

Parameters:

	swatchRefs	[out] A buffer in which to return the references of swatches. Use `CountSelectedDocSwatches()` to determine how much memory to allocate.
	bufferSize	The number of elements in the return array. If there are more selected swatches, only this many are returned.

AIErr ASAPI(* AISwatchLibrariesSuite::GetSelectedDocSwatchRefsNotInAnySelectedGroup)(AISwatchRef *colors, ai::int32 bufferSize)

Retrieves an array of colors for the selected document swatches not in any selected group.

The members are ordered as they appear in the document Swatches palette, left to right and top to bottom.

Parameters:

	colors	[out] A buffer in which to return the colors. Use `CountSelectedDocSwatches()` to determine how much memory to allocate.
	bufferSize	The number of elements in the colors array. If there are more selected colors, only this many are returned.

AIErr ASAPI(* AISwatchLibrariesSuite::MapLegacyColorName)(const ai::UnicodeString &src, ai::UnicodeString &dst)

Maps a legacy color name to its corresponding name in the current color books.

Parameters:

	src	The legacy color-book name.
	dst	[out] A buffer in which to return the current color-book name, or the empty string if no mapping is defined.

AIBoolean ASAPI(* AISwatchLibrariesSuite::NthLibraryIsOpen)(ai::int32 num, bool shouldBeVisible)

Reports whether a swatch library is currently displayed in an open palette.

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

Parameters:

	num	The 0-based position index of the swatch library in the list of known libraries.
	shouldBeVisible	: Default value is true If set true, it ensures that the library asked for, must be currently visible. else it returns true for all libraries, which were ever opened.

AIErr ASAPI(* AISwatchLibrariesSuite::OpenLibraryByPath)(const ai::FilePath &path)

Open the SwatchLibrary using library path.

To support open as swatches library from the script api.

Parameters:

path

[in] the path of file containing Swatch Library

AIErr ASAPI(* AISwatchLibrariesSuite::OpenNthLibrary)(ai::int32 num, AIBoolean showPalette, AISwatchListRef *swatchList)

Retrieves a swatch list from a swatch library.

Opens the library file and reads swatches even if the library has not yet been opened during the session. Use the AISwatchListSuite to access and modify the returned list.

Parameters:

	num	The 0-based position index. Use 0 or a negative number to get the swatch list for the current open document, if any.
	showPalette	True to create and show a palette for the library.
	swatchlist	[out] A buffer in which to return the swatch list.

AIBoolean ASAPI(* AISwatchLibrariesSuite::SelectNthDocColorGroupIfVisible)(ai::int32 index, AIBoolean deselectOthers)

Selects a color group and all of the group's swatches in the main Swatches palette, if it is open and the group is shown.

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

Parameters:

	index	The 0-based position index into the main document's list of color groups, or -1 to select the last color group in the document, or -2 or less to deselect all fully selected color groups. Selected swatches in partially selected color groups are not deselected.
	deselectOthers	True to also deselect any other selected swatches or color groups if the specified group is visible.

Returns:: True if the group was successfully selected, false if it was not. This can occur if the palette is closed or does not show the specified swatch, or if the index is invalid.

Note:: This function is intended to used by other plug-ins that create color groups, to select the groups they have just inserted into the list.

AIBoolean ASAPI(* AISwatchLibrariesSuite::SelectNthDocumentSwatchIfVisible)(ai::int32 index, AIBoolean deselectOthers)

Selects a swatch in the main Swatches palette, if it is open and its color kind is shown.

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

Parameters:

	index	The 0-based position index into the main document's list of the swatch.
	deselectOthers	True to also deselect any other selected swatches if the specified color is visible.

Returns:: True if the swatch was successfully selected, false if it was not. This can occur if the palette is closed or does not show the specified swatch, or if the index is invalid.

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

AISwatchLibraries.h

AISwatchLibrariesSuite Struct Reference

Public Attributes

Detailed Description

Member Data Documentation