AIPatternSuite Struct Reference
[API Suite List]

This suite provides functions that allow you to create, delete, and modify patterns. More...

#include <AIPattern.h>

Public Attributes
AIAPI AIErr(*	NewPattern )(AIPatternHandle *newPattern)
	Creates and initialized a new pattern object.
AIAPI AIErr(*	DeletePattern )(AIPatternHandle pattern)
	Deletes a pattern from the current document.
AIAPI AIErr(*	GetPattern )(AIPatternHandle pattern)
	Creates a copy of the pattern source artwork and places it into the current document at the center of the current view, in the current layer and insertion group.
AIAPI AIErr(*	SetPattern )(AIPatternHandle pattern)
	Collects the selected artwork in the current document and makes it the source art for a pattern.
AIAPI AIErr(*	CountPatterns )(ai::int32 *count)
	Gets the number of patterns available to the current document.
AIAPI AIErr(*	GetNthPattern )(ai::int32 n, AIPatternHandle *pattern)
	Retrieves a pattern reference by index position.
AIAPI AIErr(*	GetPatternArt )(AIPatternHandle pattern, AIArtHandle *art)
	Retrieves the art object (of type `kGroupArt`) that defines the source art for a pattern.
AIAPI AIErr(*	SetPatternArt )(AIPatternHandle pattern, AIArtHandle art)
	Sets the source art for a pattern.
AIAPI AIErr(*	GetPatternName )(AIPatternHandle pattern, ai::UnicodeString &name)
	Retrieves the name of a pattern.
AIAPI AIErr(*	SetPatternName )(AIPatternHandle pattern, const ai::UnicodeString &name)
	Sets the name of a pattern.
AIAPI AIErr(*	GetPatternByName )(const ai::UnicodeString &name, AIPatternHandle *pattern)
	Retrieves a pattern by name.
AIAPI AIErr(*	IteratePattern )(AIArtHandle art, AIPathStyle *style, AIPatternProcPtr proc)
	Renders a path filled with a pattern.
AIAPI AIErr(*	NewPatternName )(ai::UnicodeString &newName)
	Creates a unique name for a pattern, which can be passed to `SetPatternName()`.
AIAPI AIErr(*	GetPatternTileBounds )(AIPatternHandle pattern, AIRealRectPtr bounds)
	Retrieves the tile bounds for a pattern.
AIAPI AIBoolean(*	ValidatePattern )(AIPatternHandle pattern)
	Reports whether a pattern object references a valid pattern in the current document.
AIAPI AIErr(*	EnterPatternEditMode )(AIPatternHandle pattern)
AIAPI AIErr(*	EndPatternEditMode )(AIPatternHandle pattern, AIBoolean updatePattern)
AIAPI AIBoolean(*	GetPatternEditMode )(AIPatternHandle patternUnderEdit, AIArtHandle isolatedPatternArt)
	Reports whether PatternEditMode is currently active, either globally or on a specified pattern.

Detailed Description

This suite provides functions that allow you to create, delete, and modify patterns.

Illustrator uses patterns to fill or stroke with a repeating tile of art objects, which can be transformed before painting.

A pattern definition is the artwork that defines the pattern tile. It is a group of art objects where the backmost object is a square that defines the size of the tile. The square must be parallel to the X and Y axes.

Instance parameters, in an AIPatternStyle structure, define how a pattern is used to paint a particular instance of a fill or stroke. A transformation matrix is used to position the pattern for the painting operation.

Each document keeps a list of associated patterns. To copy a pattern from another document into the current document, put the pattern object into an AIColor structure and use AIPathStyleSuite::RetargetForCurrentDoc().

Acquire this suite using SPBasicSuite::AcquireSuite() with the constants kAIPatternSuite and kAIPatternVersion.

Member Data Documentation

AIAPI AIErr(* AIPatternSuite::CountPatterns)(ai::int32 *count)

Gets the number of patterns available to the current document.

Use with GetNthPattern() to iterate through all patterns.

Parameters:

count

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

AIAPI AIErr(* AIPatternSuite::DeletePattern)(AIPatternHandle pattern)

Deletes a pattern from the current document.

If the pattern is used for an objectís fill, the fill becomes black.

Parameters:

pattern

The pattern object.

AIAPI AIErr(* AIPatternSuite::EndPatternEditMode)(AIPatternHandle pattern, AIBoolean updatePattern)

AIAPI AIErr(* AIPatternSuite::EnterPatternEditMode)(AIPatternHandle pattern)

AIAPI AIErr(* AIPatternSuite::GetNthPattern)(ai::int32 n, AIPatternHandle *pattern)

Retrieves a pattern reference by index position.

Use with CountPatterns() to iterate through all patterns.

Parameters:

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

Returns:: The error kBadParameterErr if the index is out of range.

AIAPI AIErr(* AIPatternSuite::GetPattern)(AIPatternHandle pattern)

Creates a copy of the pattern source artwork and places it into the current document at the center of the current view, in the current layer and insertion group.

This is the equivalent of using the Paste command.

Parameters:

pattern

The pattern object.

Returns:: The error kUntouchableLayerErr if the current layer or current insertion group is locked or hidden.

AIAPI AIErr(* AIPatternSuite::GetPatternArt)(AIPatternHandle pattern, AIArtHandle *art)

Retrieves the art object (of type kGroupArt) that defines the source art for a pattern.

Parameters:

	pattern	The pattern object.
	art	[out] A buffer in which to return the art object.

AIAPI AIErr(* AIPatternSuite::GetPatternByName)(const ai::UnicodeString &name, AIPatternHandle *pattern)

Retrieves a pattern by name.

Parameters:

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

Returns:: The error kNameNotFoundErr if there is no pattern with the given name.

AIAPI AIBoolean(* AIPatternSuite::GetPatternEditMode)(AIPatternHandle *patternUnderEdit, AIArtHandle *isolatedPatternArt)

Reports whether PatternEditMode is currently active, either globally or on a specified pattern.

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

Parameters:

	patternUnderEdit	[optional, in/out] if non-null and pointing to a non-null value on input, then the function returns true only if that pattern is being edited if null on input or pointing to a null value on input, then this function returns true if ANY pattern is being edited, and returns that pattern in this pointer
	isolatedPatternArt	[optional, out] if non-null, returns the art object that will be used to create the new pattern definition upon exit from PatternEditMode (May be either a plugin group or a group. If it is a plugin group, the plugin group is responsible for knowing how to redefine the pattern. If it is a group, the group will become the new pattern art.)

AIAPI AIErr(* AIPatternSuite::GetPatternName)(AIPatternHandle pattern, ai::UnicodeString &name)

Retrieves the name of a pattern.

Parameters:

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

AIAPI AIErr(* AIPatternSuite::GetPatternTileBounds)(AIPatternHandle pattern, AIRealRectPtr bounds)

Retrieves the tile bounds for a pattern.

Parameters:

	pattern	The pattern object.
	bounds	[out] A buffer in which to return the bounding rectangle.

AIAPI AIErr(* AIPatternSuite::IteratePattern)(AIArtHandle art, AIPathStyle *style, AIPatternProcPtr proc)

Renders a path filled with a pattern.

Breaks up the specified artwork into tiles the size of its pattern, and, for each tile, generates any artwork needed to draw that tile on the page. Passes the generated artwork to a procedure that you define for further processing.

Parameters:

	art	The path art object.
	style	A path style with a pattern fill.
	proc	The developer-defined callback procedure.

AIAPI AIErr(* AIPatternSuite::NewPattern)(AIPatternHandle *newPattern)

Creates and initialized a new pattern object.

Pass the returned reference to SetPatternName() and SetPatternArt() to set the name and source art.

Parameters:

newPattern

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

AIAPI AIErr(* AIPatternSuite::NewPatternName)(ai::UnicodeString &newName)

Creates a unique name for a pattern, which can be passed to SetPatternName().

Parameters:

newName

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

If no existing pattern has this name, it is returned.
If a pattern already has this name, appends a numeric value to the string or increments the current numeric end value to make the name unique.

AIAPI AIErr(* AIPatternSuite::SetPattern)(AIPatternHandle pattern)

Collects the selected artwork in the current document and makes it the source art for a pattern.

The selected artwork must be usable as a pattern. It can be any art object whose type is kGroupArt, as long as the bottom object is a bounding rectangle with no fill and no stroke, the size of the tile, parallel to the X and Y axes.

Parameters:

pattern

The pattern object.

Returns:: An error (non-zero) if the current selection is not usable as a pattern.

AIAPI AIErr(* AIPatternSuite::SetPatternArt)(AIPatternHandle pattern, AIArtHandle art)

Sets the source art for a pattern.

Parameters:

	pattern	The pattern object.
	art	The new source art, of type `kGroupArt`. The backmost object of the group must be a bounding rectangle with no fill and no stroke, to be used in tiling the pattern.