AICustomColorSuite Struct Reference
[API Suite List]

Use the functions in this suite to access, create, delete, and modify custom colors. More...

#include <AICustomColor.h>

Public Attributes
AIAPI AIErr(*	NewCustomColor )(AICustomColor color, const ai::UnicodeString &name, AICustomColorHandle customColor)
	Creates a new custom color.
AIAPI AIErr(*	DeleteCustomColor )(AICustomColorHandle customColor)
	Deletes a custom color.
AIAPI AIErr(*	GetCustomColor )(AICustomColorHandle customColor, AICustomColor *color)
	Retrieves the color specification from a custom color, which includes the CMYK or RGB values.
AIAPI AIErr(*	SetCustomColor )(AICustomColorHandle customColor, AICustomColor *color)
	Sets the color specification for a custom color, which includes the CMYK or RGB values.
AIAPI AIErr(*	GetCustomColorName )(AICustomColorHandle customColor, ai::UnicodeString &name)
	Retrieves the unique name of a custom color.
AIAPI AIErr(*	SetCustomColorName )(AICustomColorHandle customColor, const ai::UnicodeString &name)
	Sets the name of a custom color.
AIAPI AIErr(*	CountCustomColors )(ai::int32 *count)
	Gets the number of defined custom colors currently available.
AIAPI AIErr(*	GetNthCustomColor )(ai::int32 n, AICustomColorHandle *customColor)
	Retrieves a custom color by position index.
AIAPI AIErr(*	GetCustomColorByName )(const ai::UnicodeString &name, AICustomColorHandle *customColor)
	Retrieves a custom color by name.
AIAPI AIErr(*	NewCustomColorName )(ai::UnicodeString &name)
	Generates a unique name for a custom color If the specified base name does not already exist, it is returned.
AIAPI AIErr(*	GetCustomColorDisplayName )(ai::UnicodeString &name)
AIAPI AIErr(*	GetCurrentRegistrationColor )(AICustomColorHandle *customColor)
	Retrieves the custom color currently used as the registration color.
AIAPI AIErr(*	NewRegistrationColor )(AICustomColorHandle *customColor, AIReal cyan, AIReal magenta, AIReal yellow, AIReal black, AICustomColorTag kind)
	Retrieves the registration color for the current document, or creates a new registration color if needed, using default values.
AIAPI AIBoolean(*	ValidateCustomColor )(AICustomColorHandle customColor)
	Reports whether a custom color handle represents a valid custom color in the current document.
AIAPI AIBoolean(*	HasExternalUses )(AICustomColorHandle customColor)
	Reports whether a custom color is a spot color that is used by a linked file.
AIAPI AIErr(*	ConvertToNonGlobal )(AICustomColorHandle customColor, AIReal tint, AIColor *color)
	Converts a tint of a custom color to its closest non-global approximation that is consistent with the document color model.
AIAPI AIErr(*	GetAppearanceApproximation )(AICustomColorHandle customColor, AIReal tint, ai::int32 space, AIFloatSampleComponent values)
	Converts a tint of a custom color to its best appearance approximation, a color that approximates the way the custom color looks.
AIAPI AIErr(*	SetCustomColorBookID )(AICustomColorHandle customColor, ai::int32 bookid)
	Sets the book id for global spot color.
AIAPI ai::int32(*	GetCustomColorBookID )(AICustomColorHandle customColor)
	Gets the source book id for global spot color.

Detailed Description

Use the functions in this suite to access, create, delete, and modify custom colors.

Custom colors represent both spot colors and global process colors.

Acquire this suite using SPBasicSuite::AcquireSuite() with the constants kAICustomColorSuite and kAICustomColorVersion.

Member Data Documentation

AIAPI AIErr(* AICustomColorSuite::ConvertToNonGlobal)(AICustomColorHandle customColor, AIReal tint, AIColor *color)

Converts a tint of a custom color to its closest non-global approximation that is consistent with the document color model.

For example, in a CMYK document, Lab and RGB based spot colors are converted to CMYK.

If the custom color is a global process color, the returned color is the process equivalent.
If the custom color is a spot color, the returned color is the process approximation of the appearance of the spot color.
If the custom color is a registration color, the returned color is the process color used to represent the registration color.

Parameters:

	customColor	The custom color reference.
	tint	The amount of the color used in paint, a percentage value in the range [0..1], where 0 is full tint and 1 is white.
	color	[out] A buffer in which to return the converted color.

AIAPI AIErr(* AICustomColorSuite::CountCustomColors)(ai::int32 *count)

Gets the number of defined custom colors currently available.

Use with GetNthCustomColor() to iterate through the list of custom colors.

Parameters:

count

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

AIAPI AIErr(* AICustomColorSuite::DeleteCustomColor)(AICustomColorHandle customColor)

Deletes a custom color.

Deletes it from the swatches palette if present and replaces any usages by the process equivalent.

Parameters:

customColor

The custom color reference. Upon return, this reference is invalid.

AIAPI AIErr(* AICustomColorSuite::GetAppearanceApproximation)(AICustomColorHandle customColor, AIReal tint, ai::int32 *space, AIFloatSampleComponent *values)

Converts a tint of a custom color to its best appearance approximation, a color that approximates the way the custom color looks.

For global process colors, returns the process color with the given tint.
For spot colors, returns a color that approximates the appearance of the tint of the spot ink.

This differs from ConvertToNonGlobal() in that the resulting color need not be consistent with the document color model.

Parameters:

	customColor	The custom color reference.
	tint	The amount of the color used in paint, a percentage value in the range [[0..1], where 0 is full tint and 1 is white.
	space	[out] A buffer in which to return the color space, a `AIColorConversionSpaceValue`.
	color	[out] A buffer in which to return the converted color.

AIAPI AIErr(* AICustomColorSuite::GetCurrentRegistrationColor)(AICustomColorHandle *customColor)

Retrieves the custom color currently used as the registration color.

Parameters:

customColor

[out] A buffer in which to return the custom color reference.

AIAPI AIErr(* AICustomColorSuite::GetCustomColor)(AICustomColorHandle customColor, AICustomColor *color)

Retrieves the color specification from a custom color, which includes the CMYK or RGB values.

Parameters:

	customColor	The custom color reference.
	color	[out] A buffer in which to return the color information.

AIAPI ai::int32(* AICustomColorSuite::GetCustomColorBookID)(AICustomColorHandle customColor)

Gets the source book id for global spot color.

If color is not spot then this method returns -1

Parameters:

customColor

The custom color reference.

AIAPI AIErr(* AICustomColorSuite::GetCustomColorByName)(const ai::UnicodeString &name, AICustomColorHandle *customColor)

Retrieves a custom color by name.

Parameters:

	name	The name.
	customColor	[out] A buffer in which to return the custom color reference.

AIAPI AIErr(* AICustomColorSuite::GetCustomColorDisplayName)(ai::UnicodeString &name)

Deprecated:: This function is now a no-op. An earlier version of Illustrator stored unique internal names for custom colors different from those displayed in the UI.

AIAPI AIErr(* AICustomColorSuite::GetCustomColorName)(AICustomColorHandle customColor, ai::UnicodeString &name)

Retrieves the unique name of a custom color.

Parameters:

	customColor	The custom color reference.
	name	[out] A buffer in which to return the color name.

AIAPI AIErr(* AICustomColorSuite::GetNthCustomColor)(ai::int32 n, AICustomColorHandle *customColor)

Retrieves a custom color by position index.

Use with CountCustomColors() to iterate through the list of custom colors.

Parameters:

	n	The position index, in the range `[0..numColors-1]`.
	customColor	[out] A buffer in which to return the custom color reference.

AIAPI AIBoolean(* AICustomColorSuite::HasExternalUses)(AICustomColorHandle customColor)

Reports whether a custom color is a spot color that is used by a linked file.

If this is the case it cannot be modified. (Note that this function returns a boolean value, not an error code.)

Parameters:

customColor

The custom color reference.

Returns:: True if the custom color is used externally.

AIAPI AIErr(* AICustomColorSuite::NewCustomColor)(AICustomColor *color, const ai::UnicodeString &name, AICustomColorHandle *customColor)

Creates a new custom color.

The color is not added to the swatch list.

Parameters:

	color	The color specification.
	name	The color name. The PostScript/PDF language reserves the names `All`, `None`, `Cyan`, `Magenta`, `Yellow` and `Black`. These names cannot be used for spot colors.
	customColor	[out] A buffer in which to return the new custom color reference.

AIAPI AIErr(* AICustomColorSuite::NewCustomColorName)(ai::UnicodeString &name)

Generates a unique name for a custom color If the specified base name does not already exist, it is returned.

If the base name already exists, the function concatenates the string "\nxxx", where xxx is an integer, starting at 000 and incrementing as necessary to create a unique name. This allows you to keep track of multiple versions of the same color name..

Parameters:

name

[in, out] A string containing the base name. The string is modified in place if needed.

AIAPI AIErr(* AICustomColorSuite::NewRegistrationColor)(AICustomColorHandle *customColor, AIReal cyan, AIReal magenta,AIReal yellow, AIReal black, AICustomColorTag kind)

Retrieves the registration color for the current document, or creates a new registration color if needed, using default values.

Ignores the color and kind input parameters.

Parameters:

customColor

[out] A buffer in which to return the current registration color, or the new registration color.

AIAPI AIErr(* AICustomColorSuite::SetCustomColor)(AICustomColorHandle customColor, AICustomColor *color)

Sets the color specification for a custom color, which includes the CMYK or RGB values.

Parameters:

	customColor	The custom color reference.
	color	The new color information.

AIAPI AIErr(* AICustomColorSuite::SetCustomColorBookID)(AICustomColorHandle customColor, ai::int32 bookid)

Sets the book id for global spot color.

If color is not spot then this method returns an error.

Parameters:

	customColor	The custom color reference.
	bookid	The custom color source book id.

AIAPI AIErr(* AICustomColorSuite::SetCustomColorName)(AICustomColorHandle customColor, const ai::UnicodeString &name)

Sets the name of a custom color.

Parameters:

	customColor	The custom color reference.
	name	The new name. The PostScript/PDF language reserves the names `All`, `None`, `Cyan`, `Magenta`, `Yellow` and `Black`. These names cannot be used for spot colors.

AIAPI AIBoolean(* AICustomColorSuite::ValidateCustomColor)(AICustomColorHandle customColor)

Reports whether a custom color handle represents a valid custom color in the current document.

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

Parameters:

customColor

The custom color reference.

Returns:: True if the reference is valid.

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

AICustomColor.h

AICustomColorSuite Struct Reference [API Suite List]

Public Attributes

Detailed Description

Member Data Documentation

AICustomColorSuite Struct Reference
[API Suite List]