AIPlanarObjectSuite Struct Reference
[API Suite List]

This suite provides functions for working with planar objects, which are temporary objects used to construct a planar plug-in-group art object. More...

#include <AIPlanarObject.h>

List of all members.

Public Attributes
AIAPI AIPlanarObjectHandle(*	NewPlanarObject )(const AIRealMatrix *matrix, const AIGapOptions *gapOptions)
	Begins construction of a planar object.
AIAPI AIErr(*	AddPath )(AIPlanarObjectHandle object, int segmentCount, AIPathSegment *segments, AIArtStyleHandle *leftFill, AIArtStyleHandle *rightFill, AIArtStyleHandle *stroke, AIBoolean closed)
	Adds a path to a planar object.
AIAPI AIErr(*	AddPathUniform )(AIPlanarObjectHandle object, int segmentCount, AIPathSegment *segments, AIArtStyleHandle leftFill, AIArtStyleHandle rightFill, AIArtStyleHandle stroke, AIBoolean closed)
AIAPI AIErr(*	Abandon )(AIPlanarObjectHandle object)
	Abandons the creation of a planar object.
AIAPI AIErr(*	CreateArt )(AIPlanarObjectHandle object, ai::int16 paintOrder, AIArtHandle prep, AIArtHandle *newArt)
	Creates a new planar plug-in group art object from a planar object.
AIAPI AIBoolean(*	IsPlanarArtObject )(AIArtHandle art)
	Reports whether an art object is a planar plug-in group.
AIAPI AIErr(*	ComplexConversionCanceled )(AIBoolean fromPlanarMap, ai::int32 pathOrEdgeCount, const AIGapOptions *gapOptions, AIBoolean *warningDisplayed)
	Reports whether a selection can be converted to a planar object, based on the amount of memory available.
AIAPI AIErr(*	EraseBlob )(AIArtHandle pathBlob, AIArtHandle planarObject, AIBoolean *erasedSomething)
	Erases a shape from a Live Paint planar object.
AIAPI AIErr(*	SelectSimilarFaceStyle )(void)
	Selects all faces that have the same style (fill color) as the currently selected faces.
AIAPI AIBoolean(*	CanSelectSimilarFaceStyle )(void)
	Reports whether all faces that have the same style (fill color) as the currently selected faces can be selected using SelectSimilarFaceStyle().
AIAPI AIErr(*	SelectSimilarEdgeWeights )(void)
	Selects all edges that have the same edge weight as the currently selected edges.
AIAPI AIBoolean(*	CanSelectSimilarEdgeWeights )(void)
	Reports whether all edges that have the same edge weight as the currently selected edges can be selected using SelectSimilarEdgeWeights().
AIAPI AIErr(*	SelectSimilarEdgeColors )(void)
	Selects all edges that have the same color as the currently selected edges.
AIAPI AIBoolean(*	CanSelectSimilarEdgeColors )(void)
	Reports whether all edges that have the same color as the currently selected edges can be selected using SelectSimilarEdgeColors().

---

Detailed Description

This suite provides functions for working with planar objects, which are temporary objects used to construct a planar plug-in-group art object.

Use these functions to create, populate, and query the attributes of planar objects, and to create art from planar objects.

• Acquire this suite using SPBasicSuite::AcquireSuite() with the constants kAIPlanarObjectSuite and kAIPlanarObjectVersion.

---

Member Data Documentation

AIAPI AIErr(* AIPlanarObjectSuite::Abandon)(AIPlanarObjectHandle object)

Abandons the creation of a planar object.

Parameters:

object

The planar object. After the call, this handle is no longer valid.

AIAPI AIErr(* AIPlanarObjectSuite::AddPath)(AIPlanarObjectHandle object, int segmentCount, AIPathSegment *segments, AIArtStyleHandle *leftFill, AIArtStyleHandle *rightFill, AIArtStyleHandle *stroke, AIBoolean closed)

Adds a path to a planar object.

Note:

Even when consecutive segments share the same stroke and same styles on each side, the styles are not coalesced into a multi-segment data structure. For example, a path that separates only two faces must have the same styles repeated in each style array.

Parameters:

	object	The planar object.
	segmentCount	The number of segments in the path.
	segments	The path segments, an array of size segmentCount for a closed path, or of size segmentCount+1 for an open path. (A path segment is an anchor point with its two handles, and an open path has one more anchor point than it has bezier segments.)
	leftFill	Style objects containing the paint style for the fill to the left of each corresponding segment. An array of size segmentCount. A NULL entry specifies no fill. An entry that refers to the outside of the planar object must be NULL.
	rightFill	Style objects containing the paint style for the fill to the right of each corresponding segment. An array of size segmentCount. A NULL entry specifies no fill. An entry that refers to the outside of the planar object must be NULL.
	stroke	Style objects containing the paint style for the stroke of each corresponding segment. An array of size segmentCount. A NULL entry specifies no stroke.
	closed	True to create a closed path.

Note:

The added paths must, collectively, specify a consistent planar map. in which paths intersect only at endpoints of the Bezier curves (except for intersections that result from rounding and path flattening inaccuracy), Each face of the map must have a consistent style, as defined by the style of each bounding path.

Returns:

An error if a violation of conditions is detected; however, it is not always possible to detect whether conditions have been violated. The results of a violation are, in general, undefined.

AIAPI AIErr(* AIPlanarObjectSuite::AddPathUniform)(AIPlanarObjectHandle object, int segmentCount, AIPathSegment *segments, AIArtStyleHandle leftFill, AIArtStyleHandle rightFill, AIArtStyleHandle stroke, AIBoolean closed)

AIAPI AIBoolean(* AIPlanarObjectSuite::CanSelectSimilarEdgeColors)(void)

Reports whether all edges that have the same color as the currently selected edges can be selected using SelectSimilarEdgeColors().

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

Returns:

True if similar edge colors can be selected, false otherwise.

AIAPI AIBoolean(* AIPlanarObjectSuite::CanSelectSimilarEdgeWeights)(void)

Reports whether all edges that have the same edge weight as the currently selected edges can be selected using SelectSimilarEdgeWeights().

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

Returns:

True if similar edge weights can be selected, false otherwise.

AIAPI AIBoolean(* AIPlanarObjectSuite::CanSelectSimilarFaceStyle)(void)

Reports whether all faces that have the same style (fill color) as the currently selected faces can be selected using SelectSimilarFaceStyle().

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

Returns:

True if similar face styles can be selected, false otherwise.

AIAPI AIErr(* AIPlanarObjectSuite::ComplexConversionCanceled)(AIBoolean fromPlanarMap, ai::int32 pathOrEdgeCount, const AIGapOptions *gapOptions, AIBoolean *warningDisplayed)

Reports whether a selection can be converted to a planar object, based on the amount of memory available.

Warns if the complexity is too great, and allows the user to choose whether to continue or cancel.

Succeeds if the conversion is simple enough that no warning is needed, or if the user chooses to continue. If user interaction is disabled (by using ASUserInteractionSuite or because you are running a script), the function succeeds, but still reports whether the complexity merits a warning.

Parameters:

	fromPlanarMap	True if pathOrEdgeCount specifies the number of edges in the planar map. False if pathOrEdgeCount specifies the number of legacy paths in a selection or in the result art of a tracing object.
	pathOrEdgeCount	The number of edges in the planar map, or the number of legacy paths in a selection or in the result art of a tracing object.
	gapOptions	Proposed gap detection options. Can be NULL; default is no gap detection.
	warningDisplayed	[out] Optional. A buffer in which to return true if the complexity warning was displayed. You might want to check this to prevent displaying a redundant warning if complexity checks might be made at multiple places. If user interaction is disabled, returns true if the complexity was sufficient to merit the warning.

Returns:

kNoErr if no warning was necessary, or if the complexity warning was displayed and the user clicked Continue to accept the risk, or if user interaction is disabled,
The error kCanceledErr if the complexity warning was displayed and the user clicked Cancel.

AIAPI AIErr(* AIPlanarObjectSuite::CreateArt)(AIPlanarObjectHandle object, ai::int16 paintOrder, AIArtHandle prep, AIArtHandle *newArt)

Creates a new planar plug-in group art object from a planar object.

The new edit group contains paths constructed from the segments and styles of the paths added to the planar object.There might not be a one-to-one correspondence between the number of paths added and the final contents of the edit group, as the function can coalesce or split paths to maximize editability and preserve validity of the planar map.

Parameters:

	object	The planar object. After the call, this handle is no longer valid.
	paintOrder	The paint order position, relative to the prep object, an AITypes::AIPaintOrder value.
	prep	The prepositional art object.
	newArt	[out] A buffer in which to return the new art object.

AIAPI AIErr(* AIPlanarObjectSuite::EraseBlob)(AIArtHandle pathBlob, AIArtHandle planarObject, AIBoolean *erasedSomething)

Erases a shape from a Live Paint planar object.

Parameters:

	pathBlob	A path or compound path object for the shape to erase. It is always be treated as closed. The object is not modified.
	planarObject	A planar object plug-in group. This object is modified in place.
	erasedSomething	[out] Optional. A buffer in which to return true if the function made any modification in the planar object.

AIAPI AIBoolean(* AIPlanarObjectSuite::IsPlanarArtObject)(AIArtHandle art)

Reports whether an art object is a planar plug-in group.

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

Parameters:

art

The art object.

Returns:

True if the art is a planar plug-in group.

AIAPI AIPlanarObjectHandle(* AIPlanarObjectSuite::NewPlanarObject)(const AIRealMatrix *matrix, const AIGapOptions *gapOptions)

Begins construction of a planar object.

After creation, add paths to the object using functions such as AddPath().

Parameters:

	matrix	A transformation matrix that translates from the art-object space into the planar-object space.
	gapOptions	Creation options for gap detection. Optional; gap detection is off by default.

AIAPI AIErr(* AIPlanarObjectSuite::SelectSimilarEdgeColors)(void)

Selects all edges that have the same color as the currently selected edges.

If the currently selected edges have mixed colors, or if there are no edges selected, does nothing. Use CanSelectSimilarEdgeColors() to check whether this is the case.

AIAPI AIErr(* AIPlanarObjectSuite::SelectSimilarEdgeWeights)(void)

Selects all edges that have the same edge weight as the currently selected edges.

If the currently selected edges have mixed edge weights, or if there are no edges selected, does nothing. Use CanSelectSimilarEdgeWeights() to check whether this is the case.

AIAPI AIErr(* AIPlanarObjectSuite::SelectSimilarFaceStyle)(void)

Selects all faces that have the same style (fill color) as the currently selected faces.

If the currently selected faces have mixed styles, or if there are no faces selected, does nothing. Use CanSelectSimilarFaceStyle() to check whether this is the case.

---

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

• AIPlanarObject.h