AIGradientSuite Struct Reference
[API Suite List]

This suite provides the basic definition of the gradient, a graduated blend between two or more colors. More...

#include <AIGradient.h>

Public Attributes
AIAPI AIErr(*	NewGradient )(AIGradientHandle *gradient)
	Creates a new gradient, initializing it as a linear gradient with two stops, white and black.
AIAPI AIErr(*	DeleteGradient )(AIGradientHandle gradient)
	Frees the memory associated with a gradient object that is no longer needed.
AIAPI AIErr(*	CountGradients )(ai::int32 *count)
	Gets the number of available gradients .
AIAPI AIErr(*	GetNthGradient )(ai::int32 n, AIGradientHandle *gradient)
	Retrieves a gradient by position index.
AIAPI AIErr(*	GetGradientByName )(const ai::UnicodeString &name, AIGradientHandle *gradient)
	Retrieves a gradient by its unique name.
AIAPI AIErr(*	GetGradientName )(AIGradientHandle gradient, ai::UnicodeString &name)
	Retrieves the unique name of a gradient.
AIAPI AIErr(*	SetGradientName )(AIGradientHandle gradient, const ai::UnicodeString &name)
	Sets the name of a gradient.
AIAPI AIErr(*	GetGradientType )(AIGradientHandle gradient, ai::int16 *type)
	Retrieves the type of a gradient, linear or radial.
AIAPI AIErr(*	SetGradientType )(AIGradientHandle gradient, ai::int16 type)
	Sets the type of a gradient, linear or radial.
AIAPI AIErr(*	GetGradientStopCount )(AIGradientHandle gradient, ai::int16 *count)
	Gets the number of stops (color transition or ramp points) in a gradient.
AIAPI AIErr(*	GetNthGradientStop )(AIGradientHandle gradient, ai::int16 n, AIGradientStop *stop)
	Retrieves a stop (color transition or ramp point) from a gradient by position index.
AIAPI AIErr(*	SetNthGradientStop )(AIGradientHandle gradient, ai::int16 n, AIGradientStop *stop)
	Updates an existing stop (color transition or ramp point) in a gradient.
AIAPI AIErr(*	InsertGradientStop )(AIGradientHandle gradient, ai::int16 n, AIGradientStop *stop)
	Creates a new stop (color transition or ramp point) in a gradient.
AIAPI AIErr(*	DeleteGradientStop )(AIGradientHandle gradient, ai::int16 n, AIGradientStop *stop)
	Removes a stop (color transition or ramp point) from a gradient.
AIAPI AIErr(*	IterateGradient )(AIArtHandle art, AIPathStyle style, AIGradientProcs procs, ai::int16 iterations)
	Iterates over a gradient in an art object applying a set of developer-defined drawing routines, in order to break the gradient into a set of discrete paths containing solid colors, which together approximate the gradient.
AIAPI AIErr(*	NewGradientName )(ai::UnicodeString &name)
	Creates a unique name for a gradient, which can be passed to `SetGradientName()`.
AIAPI AIErr(*	GradientUsesAIColor )(AIGradientHandle gradient, const AIColor color, AIBoolean matchTint, AIBoolean usesColor)
	Reports whether a gradient uses a particular color in any stop.
AIAPI AIBoolean(*	ValidateGradient )(AIGradientHandle gradient)
	Reports whether a gradient is defined for the current document.
AIAPI AIErr(*	GetGradientColor )(AIGradientHandle gradient, AIReal percent, AIColor *color)
	Retrieves the color at a given point on a gradient ramp.
AIAPI AIErr(*	IsGradientAlphaRequired )(AIGradientHandle gradient, AIBoolean *useAlpha)
	Reports whether a gradient has any transparency.

Detailed Description

This suite provides the basic definition of the gradient, a graduated blend between two or more colors.

The functions allow you to examine or modify existing gradients, create new gradients, or delete existing ones.

The gradient attributes correspond to the settings in the Gradient palette. A gradient has:

A unique name, which is required and is used when an object with a gradient is saved in a file.
A type, linear (kLinearGradient) or radial (kRadialGradient).
A gradient ramp, defined by a set of color stops. A stop is a point at which a color change occurs, within the ramp range of [0..100]. The number of gradient stops is equal to the number of colors specified. There must be at least two. The actual colors and their positions on the ramp are defined with the AIGradientStop structure.

When a gradient is applied to an object, the gradient ramp is scaled to the length of the gradient vector. The gradient stops are from 0 to 100% of the length needed to fully create the gradient along the vector.

A gradient instance applied to an art object is further defined by an AIGradientStyle, which is part of an object's fill or stroke style.

See also:: AIPathStyleSuite, AIPatternSuite, AICustomColorSuite.

Acquire this suite using SPBasicSuite::AcquireSuite() with the constants kAIGradientSuite and kAIGradientVersion.

Member Data Documentation

AIAPI AIErr(* AIGradientSuite::CountGradients)(ai::int32 *count)

Gets the number of available gradients .

Use with GetNthGradient() to iterate through all gradients defined in the current document. This can exceed the number of defined gradient swatches, as shown in the Swatches palette.

Parameters:

count

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

AIAPI AIErr(* AIGradientSuite::DeleteGradient)(AIGradientHandle gradient)

Frees the memory associated with a gradient object that is no longer needed.

If an art object uses this gradient for its fill value, the fill color is set to black.

Parameters:

gradient

The gradient. Upon return, this reference is invalid.

AIAPI AIErr(* AIGradientSuite::DeleteGradientStop)(AIGradientHandle gradient, ai::int16 n, AIGradientStop *stop)

Removes a stop (color transition or ramp point) from a gradient.

There must always be at least two stops.

Parameters:

	gradient	The gradient object.
	n	The position index of the stop to remove, in the range `[0..numStops -1]`.
	stop	[out] A buffer in which to return the gradient stop object that was removed.

AIAPI AIErr(* AIGradientSuite::GetGradientByName)(const ai::UnicodeString &name, AIGradientHandle *gradient)

Retrieves a gradient by its unique name.

Parameters:

	name	The name.
	gradient	[out] A buffer in which to return the gradient object.

Returns:: The error kNameNotFoundErr if a gradient with the specified name is not found.

AIAPI AIErr(* AIGradientSuite::GetGradientColor)(AIGradientHandle gradient, AIReal percent, AIColor *color)

Retrieves the color at a given point on a gradient ramp.

If the point is a stop, returns the color of that stop. Otherwise, the returns an interpolated color between stops.

Parameters:

	gradient	The gradient object.
	percent	The point on the ramp, a percentage value in the range [0..100].
	color	[out] A buffer in which to return the color.

AIAPI AIErr(* AIGradientSuite::GetGradientName)(AIGradientHandle gradient, ai::UnicodeString &name)

Retrieves the unique name of a gradient.

Parameters:

	gradient	The gradient object.
	name	[out] A buffer in which to return the name string.

AIAPI AIErr(* AIGradientSuite::GetGradientStopCount)(AIGradientHandle gradient, ai::int16 *count)

Gets the number of stops (color transition or ramp points) in a gradient.

There are always at least two. Use with GetNthGradientStop() to iterate through the stops.

Parameters:

	gradient	The gradient object.
	count	[out] A buffer in which to return the number of stops.

AIAPI AIErr(* AIGradientSuite::GetGradientType)(AIGradientHandle gradient, ai::int16 *type)

Retrieves the type of a gradient, linear or radial.

Parameters:

	gradient	The gradient object.
	type	[out] A buffer in which to return the type constant, either .`kLinearGradient` or `kRadialGradient`.

AIAPI AIErr(* AIGradientSuite::GetNthGradient)(ai::int32 n, AIGradientHandle *gradient)

Retrieves a gradient by position index.

Use with CountGradients() to iterate through all available gradients.

Parameters:

	n	The position index, in the range `[0..numGradients -1]`.
	gradient	[out] A buffer in which to return the gradient object.

AIAPI AIErr(* AIGradientSuite::GetNthGradientStop)(AIGradientHandle gradient, ai::int16 n, AIGradientStop *stop)

Retrieves a stop (color transition or ramp point) from a gradient by position index.

Use with GetGradientStopCount() to iterate through all stops in a gradient.

Parameters:

	gradient	The gradient object.
	n	The position index, in the range `[0..numStops -1]`.
	stop	[out] A buffer in which to return the gradient stop object.

AIAPI AIErr(* AIGradientSuite::GradientUsesAIColor)(AIGradientHandle gradient, const AIColor *color, AIBoolean matchTint, AIBoolean *usesColor)

Reports whether a gradient uses a particular color in any stop.

Parameters:

	gradient	The gradient object.
	color	The color.
	matchTint	When false, and if the color is a custom color, returns true for any tint of that color.
	usesColor	[out] A buffer in which to return true if the color is used in any stop.

AIAPI AIErr(* AIGradientSuite::InsertGradientStop)(AIGradientHandle gradient, ai::int16 n, AIGradientStop *stop)

Creates a new stop (color transition or ramp point) in a gradient.

To modify an existing gradient stop, use SetNthGradientStop().

Parameters:

	gradient	The gradient object.
	n	The position index at which to add this stop, in the range `[0..numStops]`. The new stop has this index, and the index of all later stops is incremented.
	stop	[out] A buffer in which to return the new gradient stop object.

AIAPI AIErr(* AIGradientSuite::IsGradientAlphaRequired)(AIGradientHandle gradient, AIBoolean *useAlpha)

Reports whether a gradient has any transparency.

This is the case if any stops have an opacity other than 1.0.

Parameters:

	gradient	The gradient object.
	useAlpha	[out] A buffer in which to return the result, true if the gradient has transparency, false otherwise.

AIAPI AIErr(* AIGradientSuite::IterateGradient)(AIArtHandle art, AIPathStyle *style, AIGradientProcs *procs, ai::int16 iterations)

Iterates over a gradient in an art object applying a set of developer-defined drawing routines, in order to break the gradient into a set of discrete paths containing solid colors, which together approximate the gradient.

The artwork is broken into iteration sections along the gradient�s vector. Each section is a region filled with a single color, represented by a path object.

For each section, the function generates any artwork needed to draw the object on the page, including a fill color, then passes the elements of the generated artwork to the supplied drawing procedures for further processing. These functions might, for example, write the information to a file in a particular format, or create artwork in Illustrator with the data.

Parameters:

	art	The art object.
	style	A pointer to the path style information.
	procs	A pointer to a set of drawing procedures. You must create and fill this with procedures you have defined before making the call.
	iterations	The number of iteration sections. Pass 0 to use the minimum number of iterations needed to produce a smooth color appearance.

AIAPI AIErr(* AIGradientSuite::NewGradient)(AIGradientHandle *gradient)

Creates a new gradient, initializing it as a linear gradient with two stops, white and black.

Use SetGradientName() to set its name, and other functions such as InsertGradientStop() to customize it after creation.

Parameters:

gradient

[out] A buffer in which to return the new gradient object.

AIAPI AIErr(* AIGradientSuite::NewGradientName)(ai::UnicodeString &name)

Creates a unique name for a gradient, which can be passed to SetGradientName().

Parameters:

name

The base name. The string is modified in place to create a unique name.

If no existing gradient has this name, it is returned.
If a gradient already has this name, a numeric value is appended to the string (or the existing numeric value is incremented) to make it unique.

AIAPI AIErr(* AIGradientSuite::SetGradientName)(AIGradientHandle gradient, const ai::UnicodeString &name)

Sets the name of a gradient.

You can create a unique name string using NewGradientName().

Parameters:

	gradient	The gradient object.
	name	The new name string.

Returns:: The error kNameNotFoundErr if a gradient with the specified name already exists.

AIAPI AIErr(* AIGradientSuite::SetGradientType)(AIGradientHandle gradient, ai::int16 type)

Sets the type of a gradient, linear or radial.

Parameters:

	gradient	The gradient object.
	type	The type constant, `kLinearGradient` or `kRadialGradient`.

AIAPI AIErr(* AIGradientSuite::SetNthGradientStop)(AIGradientHandle gradient, ai::int16 n, AIGradientStop *stop)

Updates an existing stop (color transition or ramp point) in a gradient.

The stop is specified by position index. To create a new stop, use InsertGradientStop().

Parameters:

	gradient	The gradient object.
	n	The position index, in the range `[0..numStops -1]`.
	stop	A pointer to the new gradient stop object. You must retrieve this structure with `GetNthGradientStop()` and modify it before making the call.

AIAPI AIBoolean(* AIGradientSuite::ValidateGradient)(AIGradientHandle gradient)

Reports whether a gradient is defined for the current document.

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

Parameters:

gradient

The gradient object.

Returns:: True if the gradient is defined for the current document.

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

AIGradient.h

AIGradientSuite Struct Reference [API Suite List]

Public Attributes

Detailed Description

Member Data Documentation

AIGradientSuite Struct Reference
[API Suite List]