AIPathSuite Struct Reference
[API Suite List]

This suite provides functions that allow you to examine and manipulate paths, which are art objects of type kPathArt. More...

#include <AIPath.h>

List of all members.

Public Attributes
AIAPI AIErr(*	GetPathSegmentCount )(AIArtHandle path, ai::int16 *count)
	Gets the number of anchor points on a path, including the two at each end.
AIAPI AIErr(*	SetPathSegmentCount )(AIArtHandle path, ai::int16 count)
	Removes segments from or appends segments to the end of a path.
AIAPI AIErr(*	GetPathSegments )(AIArtHandle path, ai::int16 segNumber, ai::int16 count, AIPathSegment segments[])
	Retrieves a set of segments from a path.
AIAPI AIErr(*	SetPathSegments )(AIArtHandle path, ai::int16 segNumber, ai::int16 count, const AIPathSegment segments[])
	Adds or updates segments in a path.
AIAPI AIErr(*	InsertPathSegments )(AIArtHandle path, ai::int16 segNumber, ai::int16 count, const AIPathSegment segments[])
	Inserts segments into a path.
AIAPI AIErr(*	DeletePathSegments )(AIArtHandle path, ai::int16 segNumber, ai::int16 count)
	Deletes segments from a path.
AIAPI AIErr(*	GetPathClosed )(AIArtHandle path, AIBoolean *closed)
	Reports whether a path is closed.
AIAPI AIErr(*	SetPathClosed )(AIArtHandle path, AIBoolean closed)
	Opens or closes a path.
AIAPI AIErr(*	GetPathGuide )(AIArtHandle path, AIBoolean *isGuide)
	Reports whether a path is used as a guide.
AIAPI AIErr(*	SetPathGuide )(AIArtHandle path, AIBoolean isGuide)
	Sets whether a path is used as a guide.
AIAPI AIErr(*	GetPathSegmentSelected )(AIArtHandle path, ai::int16 segNumber, ai::int16 *selected)
	Reports whether any part of a path segment is selected.
AIAPI AIErr(*	SetPathSegmentSelected )(AIArtHandle path, ai::int16 segNumber, ai::int16 selected)
	Sets the selection state for a segment.
AIAPI AIErr(*	ReversePathSegments )(AIArtHandle path)
	Reverses the order of segments in a path.
AIAPI AIErr(*	ReversePathDirection )(AIArtHandle path)
	Reverses the direction of a path.
AIAPI AIErr(*	GetPathArea )(AIArtHandle path, AIReal *area)
	Calculates the area of a path.
AIAPI AIErr(*	GetPathLength )(AIArtHandle path, AIReal *length, AIReal flatness)
	Calculates the length of the perimeter of a path measured in points.
AIAPI AIErr(*	GetPathBezier )(AIArtHandle path, ai::int16 segNumber, AIRealBezier *bezier)
	Calculates the bezier values of a path segment.
AIAPI AIErr(*	PathHasLength )(AIArtHandle path, AIBoolean *hasLength)
	Reports whether a path has length.
AIAPI AIErr(*	GetPathIsClip )(AIArtHandle path, AIBoolean *isClip)
	Reports whether a path is a clipping path.
AIAPI AIErr(*	GetPathAllSegmentsSelected )(AIArtHandle path, AIBoolean *selected)
	Reports whether all segments of a path are selected.
AIAPI AIErr(*	GetKeySegment )(AIArtHandle path, ai::int16 segmentNumber)
	Retrieves path object and segment number of the key anchor point (that is, the one to which other anchor points are aligned).
AIAPI AIErr(*	CancelKeySegment )(void)
AIAPI AIBoolean(*	IsPath9SliceSplitter )(AIArtHandle path)
	Reports whether a path is 9-slice splitter; that is, a guide that defines a line splitting the art board into 9 regions.
AIAPI AIErr(*	SetKeySegment )(AIArtHandle path, ai::int16 segmentNumber)
	Sets the key anchor point of an art object.
AIAPI AIErr(*	MeasureSegments )(AIArtHandle path, ai::int16 startSeg, ai::int16 count, AIReal pieceLengths[], AIReal accumulatedLengths[])
	Measures the lengths of the segments of a path.
AIAPI AIErr(*	LengthFractionToBezierPos )(AIArtHandle path, AIReal lengthFraction, ai::int16 &segIndex, AIReal &bezierT, const AIReal pieceLengths[], const AIReal accumulatedLengths[])
	Computes the segment index and the parametric bezier t value of the point that is a given fraction of the path length along a path.
AIAPI AIErr(*	BezierPosToLengthFraction )(AIArtHandle path, ai::int16 segIndex, AIReal bezierT, AIReal &lengthFraction, const AIReal pieceLengths[], const AIReal accumulatedLengths[])
	Computes the fraction of the total path length corresponding to a position along the path expressed as a segment index and a parametric bezier t value into that segment.
AIAPI AIErr(*	BezierPosToAnchoredPos )(AIArtHandle path, ai::int16 segIndex, AIReal t, AIReal segLength, AIReal segLengthFraction)
	Converts from a parametric bezier t value to a fraction of the segment length.
AIAPI AIErr(*	PerpendicularsAtBezierT )(AIArtHandle path, ai::int16 segIndex, AIReal t, AIReal leftDistance, AIReal rightDistance, AIRealPoint &pointOnPath, AIRealPoint leftPoint, AIRealPoint rightPoint)
	Computes the endpoints of line segments perpendicular (normal) to a path at a position expressed as a segment index and a parametric bezier t value.

Detailed Description

This suite provides functions that allow you to examine and manipulate paths, which are art objects of type kPathArt.

The shape of a path is defined by one or more path segments. Every segment of a path corresponds to an anchor point, which is the handle shown when the path is selected. The number of anchor points on a path, or segment count, includes the two at each end. A segment is defined by the AIPathSegment structure. Segment index numbers begin at zero. A path can have a single anchor point.

The in and out points of a segment define the tangent of the curve at a point p. The in point is not used for the initial and final segments of an open path. A segment can be a corner point or a smooth point. For a corner, the in and out points can be anywhere. To make a straight line, place the in and out points of each end on their p points.

A path can be can be closed or open. If a path is open, it is defined only by its segments. If it is closed, Illustrator draws a segment between the first and last anchor points, which uses the out tangent of the last segment and the in tangent of the first.

Some paths are also used as guides. In all other respects they are paths, with the same contents and attributes. Paint attributes are associated with a path through a path style. See the AIPathStyleSuite.

Acquire this suite using SPBasicSuite::AcquireSuite() with the constants kAIPathSuite and kAIPathVersion.

Member Data Documentation

AIAPI AIErr(* AIPathSuite::BezierPosToAnchoredPos)(AIArtHandle path, ai::int16 segIndex, AIReal t, AIReal *segLength, AIReal *segLengthFraction)

Converts from a parametric bezier t value to a fraction of the segment length.

(See AIRealBezierSuite for a discussion of bezier t values.) You can optionally pass segment length measurements, to improve performance when calling this function repeatedly at multiple locations along the same path.

Parameters:

	path	The path object.
	segIndex	The 0-based index of the segment.
	t	The parametric t value of a point along the path.
	segLength	[optional, in/out] If positive on input, the length of the bezier segment as calculated by `MeasureSegments()`. (Do not use `AIRealBezierSuite::Length()` to measure the length; the flatness might be different, causing an inaccurate result.) If negative or 0 on input, this function measures the segment length and returns it here on output.
	segLengthFraction	[out] A buffer in which to return the ratio between the whole segment length and the length of the shorter segment obtained by splitting the bezier at the t value.

AIAPI AIErr(* AIPathSuite::BezierPosToLengthFraction)(AIArtHandle path, ai::int16 segIndex, AIReal bezierT, AIReal &lengthFraction, const AIReal pieceLengths[], const AIReal accumulatedLengths[])

Computes the fraction of the total path length corresponding to a position along the path expressed as a segment index and a parametric bezier t value into that segment.

(See AIRealBezierSuite for a discussion of bezier t values.) You can optionally pass segment length measurements, to improve performance when calling this function repeatedly at multiple locations along the same path.

Parameters:

	path	The path object.
	segIndex	The 0-based index of a segment in the path.
	t	A bezier parametric t value at which to split the segment.
	lengthFraction	[out] A buffer in which to return the fraction of the path length at which the given position falls
	pieceLengths	[in] Optional, the piece-lengths result of a call to `MeasureSegments()` for the same path.
	accumulatedLengths	[in] Optional, the accumulated-lengths result of a call to `MeasureSegments()` for the same path.

AIAPI AIErr(* AIPathSuite::CancelKeySegment)(void)

Deprecated:: . use SetKeySegment() intsead. Clears the key anchor point (the one to which other anchor points are aligned). This is usually the last anchor point selected with the direct select tool.

AIAPI AIErr(* AIPathSuite::DeletePathSegments)(AIArtHandle path, ai::int16 segNumber, ai::int16 count)

Deletes segments from a path.

If you delete segments from a closed path, the path remains closed.

Parameters:

	path	The path object.
	segNumber	The 0-based index of the first segment.
	count	The number of segments to delete.

AIAPI AIErr(* AIPathSuite::GetKeySegment)(AIArtHandle *path, ai::int16 *segmentNumber)

Retrieves path object and segment number of the key anchor point (that is, the one to which other anchor points are aligned).

The key anchor point is usually the last anchor point selected with the direct select tool.

Parameters:

	path	[out] A buffer in which to return the path object.
	segmentNumber	[out] A buffer in which to return the segment number.

AIAPI AIErr(* AIPathSuite::GetPathAllSegmentsSelected)(AIArtHandle path, AIBoolean *selected)

Reports whether all segments of a path are selected.

Parameters:

	path	The path object.
	selected	[out] A buffer in which to return true if the path is fully selected.

AIAPI AIErr(* AIPathSuite::GetPathArea)(AIArtHandle path, AIReal *area)

Calculates the area of a path.

A pathﾒs winding order is determined by the sign of area. If the area is negative, the path is wound counter-clockwise. Self-intersecting paths can contain sub-areas that cancel each other out. This makes it possible for the function to return zero for a path that does have area.

Parameters:

	path	The path object.
	area	[out] A buffer in which to return the area, in square points.

AIAPI AIErr(* AIPathSuite::GetPathBezier)(AIArtHandle path, ai::int16 segNumber, AIRealBezier *bezier)

Calculates the bezier values of a path segment.

For the last anchor point of an open path, wraps to the beginning.
For the last anchor point of a closed path, all four bezier points are equal--that is, the outgoing control point is ignored, so that the visible bounding box, length, and other function treat it correctly.

Parameters:

	path	The path object.
	segNumber	The 0-based index of the segment.
	bezier	[out] A buffer in which to return the bezier values.

AIAPI AIErr(* AIPathSuite::GetPathClosed)(AIArtHandle path, AIBoolean *closed)

Reports whether a path is closed.

Parameters:

	path	The path object.
	closed	[out] A buffer in which to return true if the path is closed, false if it is open.

AIAPI AIErr(* AIPathSuite::GetPathGuide)(AIArtHandle path, AIBoolean *isGuide)

Reports whether a path is used as a guide.

Parameters:

	path	The path object.
	isGuide	[out] A buffer in which to return true if the path is a guide

AIAPI AIErr(* AIPathSuite::GetPathIsClip)(AIArtHandle path, AIBoolean *isClip)

Reports whether a path is a clipping path.

The path can be a compound path. To be a clipping object a path must have at least two segments. To make a path into a clipping path use AIArtSuite::SetArtUserAttr()

Parameters:

	path	The path object.
	isClip	[out] A buffer in which to return true if the path is a clipping path.

AIAPI AIErr(* AIPathSuite::GetPathLength)(AIArtHandle path, AIReal *length, AIReal flatness)

Calculates the length of the perimeter of a path measured in points.

Parameters:

	path	The path object.
	length	[out] A buffer in which to return the length, in points.
	flatness	Not used.

AIAPI AIErr(* AIPathSuite::GetPathSegmentCount)(AIArtHandle path, ai::int16 *count)

Gets the number of anchor points on a path, including the two at each end.

Parameters:

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

AIAPI AIErr(* AIPathSuite::GetPathSegments)(AIArtHandle path, ai::int16 segNumber, ai::int16 count, AIPathSegment segments[])

Retrieves a set of segments from a path.

Parameters:

	path	The path object.
	segNumber	The 0-based index of the first segment.
	count	The number of segments to retrieve.
	segments	[out] An array in which to return the segments. You must allocate an array of `AIPathSegment` the size of `count`.

AIAPI AIErr(* AIPathSuite::GetPathSegmentSelected)(AIArtHandle path, ai::int16 segNumber, ai::int16 *selected)

Reports whether any part of a path segment is selected.

Parameters:

	path	The path object.
	segNumber	The 0-based index of the segment.
	selected	[out] A buffer in which to return the selection state of the segment, an `AIPathSegementSelectionState` value.

AIAPI AIErr(* AIPathSuite::InsertPathSegments)(AIArtHandle path, ai::int16 segNumber, ai::int16 count, const AIPathSegment segments[])

Inserts segments into a path.

Parameters:

	path	The path object.
	segNumber	The 0-based index of an existing segment in the path. The new segments are inserted after this one.
	count	The number of segments to insert.
	segments	An array of new segments. You must allocate and fill an array of `AIPathSegment` the size of `count`.

Returns:: The error kTooManySegmentsErr if the new segment count exceeds the maximum number of path segments.

AIAPI AIBoolean(* AIPathSuite::IsPath9SliceSplitter)(AIArtHandle path)

Reports whether a path is 9-slice splitter; that is, a guide that defines a line splitting the art board into 9 regions.

Parameters:

path

The path object.

Returns:: True if the path is 9-slice splitter, false if not, or if the path is not used as a guide.

See also:: GetPathGuide()

AIAPI AIErr(* AIPathSuite::LengthFractionToBezierPos)(AIArtHandle path, AIReal lengthFraction, ai::int16 &segIndex, AIReal &bezierT, const AIReal pieceLengths[], const AIReal accumulatedLengths[])

Computes the segment index and the parametric bezier t value of the point that is a given fraction of the path length along a path.

(See AIRealBezierSuite for a discussion of bezier t values.) You can optionally pass segment length measurements, to improve performance when calling this function repeatedly at multiple locations along the same path.

Parameters:

	path	The path object.
	lengthFraction	The fraction of the total path length at which to calculate the position.
	segIndex	[out] A buffer in which to return the 0-based index of the segment that contains the position.
	t	[out] A buffer in which to return the bezier parametric t value of splitting the segment at that position.
	pieceLengths	[in] Optional, the piece-lengths result of a call to `MeasureSegments()` for the same path.
	accumulatedLengths	[in] Optional, the accumulated-lengths result of a call to `MeasureSegments()` for the same path.

AIAPI AIErr(* AIPathSuite::MeasureSegments)(AIArtHandle path, ai::int16 startSeg, ai::int16 count, AIReal pieceLengths[], AIReal accumulatedLengths[])

Measures the lengths of the segments of a path.

Storage is managed by the client, as for GetPathSegments().

Parameters:

	path	The path object.
	startSeg	The 0-based index of the first segment to be measured.
	count	The number of segments to measure.
	pieceLengths	[out] A buffer in which to return the lengths of each bezier segment looking forward; that is, `pieceLength`[i] is the length of the bezier from anchor point i to anchor point i+1. If i is the last segment of a closed path, it wraps around and reports the distance from anchor point i to anchor point 0. Can be a null pointer if only the accumulated lengths are needed.
	accumulatedLengths	[out] A buffer in which to return the length of the path from the starting point through anchor point i. Can be a null pointer if only the individual lengths are needed. If `startSeg` is 0, then `accumulatedLengths(i)` is the sum from j = 0 to i-1 of `pieceLengths(j)`. So strictly speaking, it is redundant, but for repeated operations it may be more efficient to sum the partial lengths once instead of each time they are needed.

AIAPI AIErr(* AIPathSuite::PathHasLength)(AIArtHandle path, AIBoolean *hasLength)

Reports whether a path has length.

This is more efficient than checking whether GetPathLength() != 0.

Parameters:

	path	The path object.
	hasLength	[out] A buffer in which to return true if the path length is not zero.

AIAPI AIErr(* AIPathSuite::PerpendicularsAtBezierT)(AIArtHandle path, ai::int16 segIndex, AIReal t, AIReal leftDistance, AIReal rightDistance, AIRealPoint &pointOnPath, AIRealPoint *leftPoint, AIRealPoint *rightPoint)

Computes the endpoints of line segments perpendicular (normal) to a path at a position expressed as a segment index and a parametric bezier t value.

(See AIRealBezierSuite for a discussion of bezier t values.)

Parameters:

	path	The path object.
	segIndex	The 0-based index of the segment.
	t	The bezier parametric t value at which to calculate the normals.
	leftDistance	The distance between `pointOnPath` and `leftPoint`. Must be non-negative.
	rightDistance	The distance between `pointOnPath` and `rightPoint`. Must be non-negative.
	pointOnPath	[out] A buffer in which to return the point along the path at the requested position.
	leftPoint	[out] A buffer in which to return the point normal to the path at a distance of `leftDistance` on the left side (as going from start to end point) Can be null if this point is not needed.
	rightPoint	[out] A buffer in which to return the point normal to the path at a distance of `rightDistance` on the right side (as going from start to end point) Can be null if this point is not needed.

AIAPI AIErr(* AIPathSuite::ReversePathDirection)(AIArtHandle path)

Reverses the direction of a path.

For open paths this works the same as ReversePathSegments(). For closed paths the transformation on segments is as follows: [0,1,2,...,n-2,n-1] => [0,n-1,n-2,...,2,1]. This changes the appearance of the path if variable width, arrowheads, certain kind of brushes etc. are applied.

Parameters:

path

The path object.

AIAPI AIErr(* AIPathSuite::ReversePathSegments)(AIArtHandle path)

Reverses the order of segments in a path.

The winding order is significant if the path is a subpath of a compound path. It controls the insideness of the compound path. This changes the appearance of the path if variable width, arrowheads, certain kind of brushes etc. are applied.

Parameters:

path

The path object.

AIAPI AIErr(* AIPathSuite::SetKeySegment)(AIArtHandle path, ai::int16 segmentNumber)

Sets the key anchor point of an art object.

The key is the one to which other anchor points are aligned. Setting a new anchor point as key replaces the previous one.

Parameters:

	path	[in] The art object that contains the new anchor point, or NULL to reset the key anchor of the selected art object to the currently selected point.
	segmentNumber	[in] The 0-based segment index of the anchor point in the specified art object to be set as key anchor point. Ignored if no art object is specified.

Returns:: The error kBadParameterErr if no anchor point is selected and no art object is specified.

AIAPI AIErr(* AIPathSuite::SetPathClosed)(AIArtHandle path, AIBoolean closed)

Opens or closes a path.

When you close a path, an additional segment is drawn between the last segment and the first segment. This is often the last step in creating a new path.

Parameters:

	path	The path object.
	closed	True to close the path, false to open it.

AIAPI AIErr(* AIPathSuite::SetPathGuide)(AIArtHandle path, AIBoolean isGuide)

Sets whether a path is used as a guide.

Parameters:

	path	The path object.
	isGuide	True if the path is to be used as a guide, false if it is not.

AIAPI AIErr(* AIPathSuite::SetPathSegmentCount)(AIArtHandle path, ai::int16 count)

Removes segments from or appends segments to the end of a path.

If the count is increased, new segments are initialized to default values, which are not guaranteed to always be the same.

Parameters:

	path	The path object.
	count	The new segment count.

Returns:: The error kTooManySegmentsErr if the new count exceeds the maximum number of path segments,

Note:: When AIArtSuite::NewArt() creates a path, it initially allocates space for 32 segments. When creating many small paths, this can waste memory. Use this function to free the memory of unused path segments immediately.

AIAPI AIErr(* AIPathSuite::SetPathSegments)(AIArtHandle path, ai::int16 segNumber, ai::int16 count, const AIPathSegment segments[])

Adds or updates segments in a path.

If segments are removed from a closed path, the path remains closed.

Parameters:

	path	The path object.
	segNumber	The 0-based index of the first segment.
	count	The number of segments to add.
	segments	An array of new segments. You must allocate and fill an array of `AIPathSegment` the size of `count`.

Returns:: The error kTooManySegmentsErr if the new segment count exceeds the maximum number of path segments.

AIAPI AIErr(* AIPathSuite::SetPathSegmentSelected)(AIArtHandle path, ai::int16 segNumber, ai::int16 selected)

Sets the selection state for a segment.

Parameters:

	path	The path object.
	segNumber	The 0-based index of the segment.
	selected	The new selection state of the segment, an `AIPathSegementSelectionState` value.

Note:: Modifying the selection state of one segment can affect adjacent segments. For example, if the out direction of one segment is selected, the in direction of the following segment is also selected.

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

AIPath.h

AIPathSuite Struct Reference [API Suite List]

Public Attributes

Detailed Description

Member Data Documentation

AIPathSuite Struct Reference
[API Suite List]