AITextFrameSuite Struct Reference
[API Suite List]

This suite provides functions that manage art objects of type kTextFrameArt. More...

#include <AITextFrame.h>

Public Attributes
AIAPI AIErr(*	NewPointText )(ai::int16 paintOrder, AIArtHandle prep, AITextOrientation orient, AIRealPoint anchor, AIArtHandle *newTextFrame)
	Creates a new point text object at a given position in the paint order.
AIAPI AIErr(*	NewInPathText )(ai::int16 paintOrder, AIArtHandle prep, AITextOrientation orient, AIArtHandle path, AIArtHandle baseFrame, AIBool8 append, AIArtHandle *newTextFrame)
	Creates a new in-path text object at a given position in the paint order.
AIAPI AIErr(*	NewOnPathText )(ai::int16 paintOrder, AIArtHandle prep, AITextOrientation orient, AIArtHandle path, AIReal startT, AIReal endT, AIArtHandle baseFrame, AIBool8 append, AIArtHandle *newTextFrame)
	Creates a new on-path text object at a given position in the paint order, placing the text with a starting and ending path segment.
AIAPI AIErr(*	NewOnPathText2 )(ai::int16 paintOrder, AIArtHandle prep, AITextOrientation orient, AIArtHandle path, AIRealPoint anchor, AIArtHandle baseFrame, AIBool8 append, AIArtHandle *newTextFrame)
	Creates a new on-path text object at a given position in the paint order, placing the text with an anchor point.
AIAPI AIErr(*	GetType )(AIArtHandle textFrame, AITextFrameType *type)
	Retrieves the type of a text frame.
AIAPI AIErr(*	GetOrientation )(AIArtHandle textFrame, AITextOrientation *orient)
	Retrieves the orientation of a text frame.
AIAPI AIErr(*	SetOrientation )(AIArtHandle textFrame, AITextOrientation orient)
	Sets the orientation of a text frame.
AIAPI AIErr(*	GetTextAntialias )(AIArtHandle textFrame, TextAntialiasingAvailableTypes *tAntialias)
	Retrieves the Antialiasing option of a text frame.
AIAPI AIErr(*	SetTextAntialias )(AIArtHandle textFrame, TextAntialiasingAvailableTypes tAntialias)
	Sets the Antialiasing option of a text frame.
AIAPI AIErr(*	GetPointTextAnchor )(AIArtHandle textFrame, AIRealPoint *anchor)
	Retrieves the anchor point of a point-text text frame.
AIAPI AIErr(*	GetPathObject )(AIArtHandle textFrame, AIArtHandle *pathObject)
	Retrieves the path associated with an in-path or on-path text range.
AIAPI AIErr(*	GetOnPathTextTRange )(AIArtHandle textFrame, AIReal startT, AIReal endT)
	Retrieves the starting and ending path segments of an on-path text range.
AIAPI AIErr(*	SetOnPathTextTRange )(AIArtHandle textFrame, AIReal startT, AIReal endT)
	Sets the starting and ending path segments of an on-path text range.
AIAPI AIErr(*	GetATETextRange )(AIArtHandle textFrame, TextRangeRef *textRange)
	Retrieves the ATE text range object for the text contained in an Illustrator text frame.
AIAPI AIErr(*	GetATETextFrame )(AIArtHandle textFrame, TextFrameRef *ATE_textFrame)
	Retrieves the ATE text frame object corresponding to an Illustrator text frame object.
AIAPI AIErr(*	GetAITextFrame )(TextFrameRef ATE_textFrame, AIArtHandle *textFrame)
	Retrieves the Illustrator text frame object corresponding to an ATE text frame object.
AIAPI AIErr(*	GetATETextSelection )(AIArtHandle textFrame, TextRangesRef *Selection)
	Retrieves the ATE text range object for the selected text contained in an Illustrator text frame.
AIAPI AIErr(*	DoTextFrameHit )(const AIHitRef hitRef, TextRangeRef *textRange)
	Retrieves the ATE text range object for the insertion point that corresponds to a hit on a text frame object, as obtained with the `AIHitTestSuite`.
AIAPI AIErr(*	CreateOutline )(AIArtHandle textFrame, AIArtHandle *outline)
	Converts the text in a text frame object to outlines in a new art object.
AIAPI AIErr(*	Link )(AIArtHandle baseFrame, AIArtHandle nextFrame)
	Links two in-path text frame objects.
AIAPI AIErr(*	Unlink )(AIArtHandle frame, AIBool8 before, AIBool8 after)
	Unlinks a text frame object from its current story, or breaks the story into two parts before or after a given frame.
AIAPI AIErr(*	CreateATEV2Text )(ai::int16 paintOrder, AIArtHandle prep, void data, size_t size, ai::int32 index, AIArtHandle newTextFrame)
	Creates a new Illustrator text frame object based on ATE version 2 blob data.
AIAPI AIErr(*	GetATEV2Data )(void *data, size_t size)
	Retrieves the ATE version 2 blob data for the current artwork.
AIAPI AIErr(*	GetStoryIndex )(AIArtHandle frame, ai::int32 *index)
	Retrieves the story index of a text frame.
AIAPI AIErr(*	GetFrameIndex )(AIArtHandle frame, ai::int32 *index)
	Retrieves the frame index of a linked text frame in its story.
AIAPI AIErr(*	PartOfLinkedText )(AIArtHandle frame, AIBool8 *linked)
	Reports whether a text frame is part of a linked text story.

Detailed Description

This suite provides functions that manage art objects of type kTextFrameArt.

Introduced in Illustrator 11.

There are three types of text frames; point text, in-path text, and on-path text.

Point text is defined by an anchor point for the position of the first character.
In-path and on-path text have an associated path object that defines the area the text flows into or along. respectively.

In-path and on-path text frames can be linked together. Linked text frames need not be the same type. They can be in different groups, and can be on different layers. The text content linked frames is called a story. Use the Adobe Text Engine (ATE) functions to access and manipulate the story and its visual attributes. Related suites include:
AIATECurrentTextFeaturesSuite
AIATEPaintSuite
AIATETextUtilSuite
AITextFrameHitSuite

Acquire this suite using SPBasicSuite::AcquireSuite() with the constants kAITextFrameSuite and kAITextFrameVersion.

Member Data Documentation

AIAPI AIErr(* AITextFrameSuite::CreateATEV2Text)(ai::int16 paintOrder, AIArtHandle prep, void *data, size_t size, ai::int32 index, AIArtHandle *newTextFrame)

Creates a new Illustrator text frame object based on ATE version 2 blob data.

Parameters:

	paintOrder	The paint order position, relative to the `prep` object, an `AITypes::AIPaintOrder` value.
	prep	The prepositional art object for the paint order.
	data	A pointer to a binary blob.
	size	The number of bytes in the data block.
	index	The 0-based position index of the new text object in the SLO TextObject list.

AIAPI AIErr(* AITextFrameSuite::CreateOutline)(AIArtHandle textFrame, AIArtHandle *outline)

Converts the text in a text frame object to outlines in a new art object.

If the text frame has an active style, that style is applied to the outlines. Other attributes, including the opacity mask. are not copied. If the text frame is set to clip, a single clipping compound path is created to contain the outlines. The style and opacity mask are not applied to this compound path.

Parameters:

	textFrame	The text frame object. This object is not deleted.
	outline	[out] A buffer in which to return the new outline text.

AIAPI AIErr(* AITextFrameSuite::DoTextFrameHit)(const AIHitRef hitRef, TextRangeRef *textRange)

Retrieves the ATE text range object for the insertion point that corresponds to a hit on a text frame object, as obtained with the AIHitTestSuite.

Parameters:

	hitRef	The hit object.
	textRange	[out] A buffer in which to return the text range object. This object is reference counted. You must release it when it is no longer needed, using the `ATE::ITextRange` class

AIAPI AIErr(* AITextFrameSuite::GetAITextFrame)(TextFrameRef ATE_textFrame, AIArtHandle *textFrame)

Retrieves the Illustrator text frame object corresponding to an ATE text frame object.

Parameters:

	ATE_textFrame	The ATE text frame object.
	textFrame	[out] A buffer in which to return the Illustrator text frame object.

AIAPI AIErr(* AITextFrameSuite::GetATETextFrame)(AIArtHandle textFrame, TextFrameRef *ATE_textFrame)

Retrieves the ATE text frame object corresponding to an Illustrator text frame object.

Parameters:

	textFrame	The text frame object.
	ATE_textFrame	[out] A buffer in which to return the ATE text frame object. This object is reference counted. You must release it when it is no longer needed, using the `ATE::ITextFrame` class

AIAPI AIErr(* AITextFrameSuite::GetATETextRange)(AIArtHandle textFrame, TextRangeRef *textRange)

Retrieves the ATE text range object for the text contained in an Illustrator text frame.

Parameters:

	textFrame	The text frame object.
	textRange	[out] A buffer in which to return the text range object. This object is reference counted. You must release it when it is no longer needed, using the `ATE::ITextRange` class

Note:: If this frame is the last one in the chain AND it has overflow text, ITextRange(textRange).getEnd() includes the hidden text.

AIAPI AIErr(* AITextFrameSuite::GetATETextSelection)(AIArtHandle textFrame, TextRangesRef *Selection)

Retrieves the ATE text range object for the selected text contained in an Illustrator text frame.

Selections can be discontiguous.

Parameters:

	textFrame	The text frame object.
	textRange	[out] A buffer in which to return the text range object. This object is reference counted. You must release it when it is no longer needed, using the `ATE::ITextRange` class

AIAPI AIErr(* AITextFrameSuite::GetATEV2Data)(void **data, size_t *size)

Retrieves the ATE version 2 blob data for the current artwork.

Parameters:

	data	[out] A buffer in which to return the binary blob. You must free this data using `SPBlocksSuite::SPFreeBlock()`.
	size	[out]] A buffer in which to return the number of bytes in the data block.

AIAPI AIErr(* AITextFrameSuite::GetFrameIndex)(AIArtHandle frame, ai::int32 *index)

Retrieves the frame index of a linked text frame in its story.

Parameters:

	frame	The text frame object.
	index	The 0-based index, or -1 if the frame does not belong to the current artwork or is part of the result art of a plug-in group or styled art.

AIAPI AIErr(* AITextFrameSuite::GetOnPathTextTRange)(AIArtHandle textFrame, AIReal *startT, AIReal *endT)

Retrieves the starting and ending path segments of an on-path text range.

Parameters:

	textFrame	The text frame object.
	startT	[out] A buffer in which to return the 0-based index of the starting segment.
	endT	[out] A buffer in which to return the 0-based index of the ending segment. It is always greater than or equal to the starting segment's index.

AIAPI AIErr(* AITextFrameSuite::GetOrientation)(AIArtHandle textFrame, AITextOrientation *orient)

Retrieves the orientation of a text frame.

Parameters:

	textFrame	The text frame object.
	orient	[out] A buffer in which to return the orientation value.

AIAPI AIErr(* AITextFrameSuite::GetPathObject)(AIArtHandle textFrame, AIArtHandle *pathObject)

Retrieves the path associated with an in-path or on-path text range.

Use the AIPathSuite to access and manipulate the path.

Parameters:

	textFrame	The text frame object.
	pathObject	[out] A buffer in which to return the path object, or `NULL` if the text frame is a point-text type.

Note:: You can use AIArtSuite::DuplicateArt() copy the path object, but you cannot specify the target location in terms of the returned path object. For example, you cannot place the duplicate path above or below the source path.

AIAPI AIErr(* AITextFrameSuite::GetPointTextAnchor)(AIArtHandle textFrame, AIRealPoint *anchor)

Retrieves the anchor point of a point-text text frame.

Use the AITransformArtSuite to change the anchor point.

Parameters:

	textFrame	The text frame object.
	anchor	[out] A buffer in which to return the anchor point.

Returns:: The error kBadParameterErr if the text frame is not a point-text type.

AIAPI AIErr(* AITextFrameSuite::GetStoryIndex)(AIArtHandle frame, ai::int32 *index)

Retrieves the story index of a text frame.

Parameters:

	frame	The text frame object.
	index	The 0-based index, or -1 if the frame does not belong to the current artwork or is part of the result art of a plug-in group or styled art.

AIAPI AIErr(* AITextFrameSuite::GetTextAntialias)(AIArtHandle textFrame, TextAntialiasingAvailableTypes *tAntialias)

Retrieves the Antialiasing option of a text frame.

Parameters:

	textFrame	The text frame object.
	tAntialias	[out] A buffer in which to return the Antialiasing options.

AIAPI AIErr(* AITextFrameSuite::GetType)(AIArtHandle textFrame, AITextFrameType *type)

Retrieves the type of a text frame.

Parameters:

	textFrame	The text frame object.
	type	[out] A buffer in which to return the type.

AIAPI AIErr(* AITextFrameSuite::Link)(AIArtHandle baseFrame, AIArtHandle nextFrame)

Links two in-path text frame objects.

Upon return, they share the same story.

Parameters:

	baseFrame	The first in-path text frame object.
	nextFrame	The second in-path text frame object.

AIAPI AIErr(* AITextFrameSuite::NewInPathText)(ai::int16 paintOrder, AIArtHandle prep, AITextOrientation orient, AIArtHandle path, AIArtHandle baseFrame, AIBool8 append, AIArtHandle *newTextFrame)

Creates a new in-path text object at a given position in the paint order.

Parameters:

	paintOrder	The paint order position, relative to the `prep` object, an `AITypes::AIPaintOrder` value.
	prep	The prepositional art object for the paint order.
	orient	The text orientation value.
	path	The associated path object (an art object of type `kPathArt`).
	baseFrame	Optional. Another text frame with which to link the new text frame.
	append	When true, append the new frame to the base frame, when false, prepend it. Ignored if `baseFrame` is `NULL`.
	newTextFrame	[out] A buffer in which to return the new art object.

AIAPI AIErr(* AITextFrameSuite::NewOnPathText)(ai::int16 paintOrder, AIArtHandle prep, AITextOrientation orient, AIArtHandle path, AIReal startT, AIReal endT, AIArtHandle baseFrame, AIBool8 append, AIArtHandle *newTextFrame)

Creates a new on-path text object at a given position in the paint order, placing the text with a starting and ending path segment.

Parameters:

	paintOrder	The paint order position, relative to the `prep` object, an `AITypes::AIPaintOrder` value.
	prep	The prepositional art object for the paint order.
	orient	The text orientation value.
	path	The associated path object (an art object of type `kPathArt`).
	startT	The 0-based index of the segment of the path at which the text starts.
	endT	The 0-based index of the segment of the path at which the text ends. If less than the start value, defaults to the number of segments (the end of the path).
	baseFrame	Optional. Another text frame with which to link the new text frame.
	append	When true, append the new frame to the base frame, when false, prepend it. Ignored if `baseFrame` is `NULL`.
	newTextFrame	[out] A buffer in which to return the new art object.

AIAPI AIErr(* AITextFrameSuite::NewOnPathText2)(ai::int16 paintOrder, AIArtHandle prep, AITextOrientation orient, AIArtHandle path, AIRealPoint anchor, AIArtHandle baseFrame, AIBool8 append, AIArtHandle *newTextFrame)

Creates a new on-path text object at a given position in the paint order, placing the text with an anchor point.

Parameters:

	paintOrder	The paint order position, relative to the `prep` object, an `AITypes::AIPaintOrder` value.
	prep	The prepositional art object for the paint order.
	orient	The text orientation value.
	path	The associated path object (an art object of type `kPathArt`).
	anchor	The start point of the baseline of the first character.
	baseFrame	Optional. Another text frame with which to link the new text frame.
	append	When true, append the new frame to the base frame, when false, prepend it. Ignored if `baseFrame` is `NULL`.
	newTextFrame	[out] A buffer in which to return the new art object.

AIAPI AIErr(* AITextFrameSuite::NewPointText)(ai::int16 paintOrder, AIArtHandle prep, AITextOrientation orient, AIRealPoint anchor, AIArtHandle *newTextFrame)

Creates a new point text object at a given position in the paint order.

Parameters:

	paintOrder	The paint order position, relative to the `prep` object, an `AITypes::AIPaintOrder` value.
	prep	The prepositional art object for the paint order.
	orient	The text orientation value.
	anchor	The start point of the baseline of the first character.
	newTextFrame	[out] A buffer in which to return the new art object.

AIAPI AIErr(* AITextFrameSuite::PartOfLinkedText)(AIArtHandle frame, AIBool8 *linked)

Reports whether a text frame is part of a linked text story.

Parameters:

	frame	The text frame object.
	linked	[out] A buffer in which to return true if the text frame is linked.

AIAPI AIErr(* AITextFrameSuite::SetOnPathTextTRange)(AIArtHandle textFrame, AIReal startT, AIReal endT)

Sets the starting and ending path segments of an on-path text range.

Parameters:

	textFrame	The text frame object.
	startT	The 0-based index of the starting segment.
	endT	The 0-based index of the ending segment. Must be greater than or equal to the starting segment's index.

AIAPI AIErr(* AITextFrameSuite::SetOrientation)(AIArtHandle textFrame, AITextOrientation orient)

Sets the orientation of a text frame.

Parameters:

	textFrame	The text frame object.
	orient	The new orientation value.

AIAPI AIErr(* AITextFrameSuite::SetTextAntialias)(AIArtHandle textFrame, TextAntialiasingAvailableTypes tAntialias)

Sets the Antialiasing option of a text frame.

Parameters:

	textFrame	The text frame object.
	tAntialias	The new Antialiasing option.

AIAPI AIErr(* AITextFrameSuite::Unlink)(AIArtHandle frame, AIBool8 before, AIBool8 after)

Unlinks a text frame object from its current story, or breaks the story into two parts before or after a given frame.

Parameters:

	frame	The text frame object.
	before	When true, if `after` is false, break the story into two groups before this frame, so that the second part starts with this frame.
	after	When true, if `before` is false, break the story into two groups after this frame, so that the first part ends with this frame.

If both before and after are true, the frame is removed from the story.
If both before and after are false, nothing happens.

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

AITextFrame.h

AITextFrameSuite Struct Reference [API Suite List]

Public Attributes

Detailed Description

Member Data Documentation

AITextFrameSuite Struct Reference
[API Suite List]