AISymbolSuite Struct Reference
[API Suite List]

This suite is always available. More...

#include <AISymbol.h>

Public Attributes
AIAPI AIErr(*	CountSymbolPatterns )(ai::int32 *count, ASBoolean includeUnlisted)
	Counts the number of symbol definitions in the global list for the current document.
AIAPI AIErr(*	GetNthSymbolPattern )(ai::int32 n, AIPatternHandle *symbolPattern, ASBoolean includeUnlisted)
	Retrieves a symbol pattern from the global list for the current document.Use with `CountSymbolPatterns()` to iterate through listed or through listed and unlisted symbols.
AIAPI AIErr(*	GetSymbolPatternByName )(const ai::UnicodeString &name, AIPatternHandle *symbolPattern)
	Retrieves a symbol pattern by name from the current document.
AIAPI AIErr(*	GetSymbolByNameFromDocument )(const ai::UnicodeString &name, AIPatternHandle *symbolPattern, AIDocumentHandle document)
	Retrieves a symbol pattern by name from a specified document.
AIAPI AIErr(*	CountSymbolPatternsFromDocument )(ai::int32 *count, AIDocumentHandle document)
	Counts the number of symbol definitions in the global list of a specified document.
AIAPI AIErr(*	GetNthSymbolPatternFromDocument )(ai::int32 n, AIPatternHandle *symbolPattern, AIDocumentHandle document)
	Retrieves a symbol pattern from the global list for a specified document.
AIAPI AIErr(*	NewSymbolPattern )(AIPatternHandle *newSymbolPattern, AIArtHandle definitionArt, AISymbolRegistrationPoint registrationPoint, ASBoolean transformDefinitionArt, ASBoolean unlisted)
	Creates a new symbol definition from specified source art, which is copied as the defining art for the new symbol.
AIAPI AIErr(*	NewSymbolPatternFromSel )(AIPatternHandle *symbolPattern, AISymbolRegistrationPoint registrationPoint)
	Creates a new listed symbol definition from selected art, which is copied as the defining art for the new symbol.
AIAPI AIErr(*	NewSymbolPatternFromSelGetBounds )(AIPatternHandle symbolPattern, AIRealRect selectionBounds, AISymbolRegistrationPoint registrationPoint)
	Creates a new listed symbol definition from selected art, which is copied as the defining art for the new symbol, and reports the bounds of the selected art.
AIAPI AIErr(*	DeleteSymbolPattern )(AIPatternHandle symbolPattern)
	Deletes a symbol definition.
AIAPI AIBoolean(*	ValidateSymbolPattern )(AIPatternHandle symbolPattern)
	Reports whether a symbol is still known to the system.
AIAPI AIErr(*	GetSymbolPatternArt )(AIPatternHandle pattern, AIArtHandle *art)
	Retrieves a read-only handle to the definition art of a symbol.
AIAPI AIErr(*	PasteSymbolPatternArt )(AIPatternHandle symbolPattern)
	Creates a copy of a symbol pattern's definition artwork and places it into the current document at the center of the current view, at the current layer and using the current insertion mode.
AIAPI AIErr(*	CopySymbolPatternArt )(AIPatternHandle symbolPattern, ai::int16 paintOrder, AIArtHandle prep, AIArtHandle *newArt)
	Creates a copy of a symbol pattern's definition artwork and places it into the current document at a specified place in the paint order.
AIAPI AIErr(*	SetSymbolPatternArt )(AIPatternHandle symbolPattern, AIArtHandle definitionArt, ASBoolean transformDefinationArt)
	Creates a copy of source art and makes it the defining art for a symbol.
AIAPI AIErr(*	SetSymbolPatternFromSel )(AIPatternHandle symbolPattern)
	Copies selected art and makes it the defining art for a symbol.
AIAPI AIErr(*	GetSymbolPatternName )(AIPatternHandle symbolPattern, ai::UnicodeString &name)
	Retrieves the name of a symbol.
AIAPI AIErr(*	SetSymbolPatternName )(AIPatternHandle symbolPattern, const ai::UnicodeString &name)
	Sets the name of a symbol.
AIAPI AIErr(*	GetSymbolPatternDisplayName )(ai::UnicodeString &name)
	Strips any hidden characters from the end of a symbol name to create a displayable string.
AIAPI AIErr(*	SetSymbolPatternBaseName )(AIPatternHandle symbolPattern, ai::UnicodeString &name)
	Sets the name of a symbol, appending numbers to a name string that is already in use to make it unique.
AIAPI AIErr(*	NewInstanceCenteredInView )(AIPatternHandle symbolPattern, ai::int16 paintOrder, AIArtHandle prep, AIArtHandle *newArt)
	Creates a new symbol instance in the center of the current document view.
AIAPI AIErr(*	NewInstanceAtLocation )(AIPatternHandle symbolPattern, AIRealPoint center, ai::int16 paintOrder, AIArtHandle prep, AIArtHandle *newArt)
	Creates a new symbol instance with its center at a specified location.
AIAPI AIErr(*	NewInstanceWithTransform )(AIPatternHandle symbolPattern, AIRealMatrix transform, ai::int16 paintOrder, AIArtHandle prep, AIArtHandle newArt)
	Creates a new symbol instance with a specified transformation matrix.
AIAPI AIErr(*	GetSymbolPatternOfSymbolArt )(AIArtHandle symbolArt, AIPatternHandle *symbolPattern)
	Retrieves the symbol pattern definition of a symbol instance.
AIAPI AIErr(*	SetSymbolPatternOfSymbolArt )(AIArtHandle symbolArt, AIPatternHandle symbolPattern)
	Sets the symbol pattern definition of a symbol instance.
AIAPI AIErr(*	GetHardTransformOfSymbolArt )(AIArtHandle symbolArt, AIRealMatrix *transform)
	Retrieves the transformation matrix that Illustrator uses to transform specified symbol art into a symbol instance.
AIAPI AIErr(*	SetHardTransformOfSymbolArt )(AIArtHandle symbolArt, AIRealMatrix *transform)
	Sets the application transformation matrix for a symbol instance.
AIAPI AIErr(*	GetSoftTransformOfSymbolArt )(AIArtHandle symbolArt, AIRealMatrix *transform)
	Retrieves the transformation matrix that a plug-in can use to transform to transform specified symbol art into a symbol instance (using the `AITransformArtSuite`).
AIAPI AIErr(*	SetSoftTransformOfSymbolArt )(AIArtHandle symbolArt, AIRealMatrix *transform)
	Sets the plug-in transformation matrix for a symbol instance.
AIAPI AIErr(*	InsertExpandedSymbolArt )(AIArtHandle symbolArt, ai::int16 paintOrder, AIArtHandle prep, AIArtHandle *expandedArt)
	Expands a symbol instance and places the resulting art into the artwork tree.
AIAPI AIBoolean(*	IsSymbolPatternListed )(AIPatternHandle symbolPattern)
	Reports whether a symbol definition is listed in the current document.
AIAPI AIErr(*	MakeSymbolPatternListed )(AIPatternHandle symbolPattern)
	Makes a symbol definition, which must be in the symbol set of the current document, listed.
AIAPI AIErr(*	UnlistSymbolPattern )(AIPatternHandle symbolPattern)
	Makes a symbol definition unlisted.
AIAPI AIErr(*	SortListedSymbolPatterns )(void)
	Sorts the listed symbols in the global list of symbols, alphabetically by name.
AIAPI AIErr(*	MoveSymbolPatternInList )(AIPatternHandle symbolPattern, int index)
	Moves a listed symbol to a specific index position in the global list of symbols.
AIAPI AIBoolean(*	ArtUsesSymbolPattern )(AIArtHandle art, ai::int16 searchScope, AIPatternHandle targetSymbol, AIPatternHandle oneFoundSymbol, AIPatternHandle *allFoundSymbols, int foundCount, int *globalObjectUsage)
	Reports whether an art object uses a specified symbol in a specified way.
AIAPI AIErr(*	BreakLinkToSymbol )(AIArtHandle symbolArt, ai::int16 paintOrder, AIArtHandle prep, AIArtHandle *expandedArt)
	Creates a copy of a symbol's definition artwork, transforms it using the matrix of a symbol instance, and places it into the current document at a specified place in the paint order.
AIAPI AIErr(*	RetargetForCurrentDocument )(AIPatternHandle srcPattern, AIPatternHandle *dstPattern)
	Retargets a symbol pattern, fill pattern, or brush pattern for the current document.
AIAPI AIErr(*	CopySymbolPatternOutline )(AIPatternHandle symbolPattern, ai::int16 paintOrder, AIArtHandle prep, AIArtHandle *newArt, ai::int32 convertToOutlineOptions)
	Creates a copy of a symbol pattern's definition artwork, converts it to outline using specified options, and places the result into the current document at a specified place in the paint order.
AIAPI AIErr(*	InsertSymbolArtOutline )(AIArtHandle symbolArt, ai::int16 paintOrder, AIArtHandle prep, AIArtHandle *expandedArt, ai::int32 convertToOutlineOptions)
	Expands a symbol definition, outlines the symbol definition, applies the instance transformation to the outlined definition art.
AIAPI AIErr(*	PeekCachedPatternOutline )(AIPatternHandle symbolPattern, AIArtHandle *outlineArt, ai::int32 convertToOutlineOptions)
	Retrieves a cached outline for a symbol pattern, if one has been generated for a given set of conversion options.
AIAPI AIErr(*	SetSymbolPatternFromSelGetBounds )(AIPatternHandle symbolPattern, AIRealRect *selectionBounds)
	Sets a symbol definition from selected art, and reports the bounds of the selected art.
AIAPI AIErr(*	SetSymbolExportType )(AIPatternHandle symbolPattern, AISymbolFlashExportType exportType)
	Sets the symbol export type for a symbol pattern, to use when exporting the symbol to Flash.
AIAPI AIErr(*	GetSymbolExportType )(AIPatternHandle symbolPattern, AISymbolFlashExportType *exportType)
	Retrieves the symbol export type for a symbol pattern, used when exporting the symbol to Flash.
AIAPI AIErr(*	SetSymbolEnableGuides )(AIPatternHandle symbolPattern, AIBoolean enableGuides)
	Sets the symbol "Enable guides for 9-slice scaling" option for a symbol pattern, to use when exporting the symbol to Flash.
AIAPI AIErr(*	GetSymbolEnableGuides )(AIPatternHandle symbolPattern, AIBoolean *enableGuides)
	Retrieves the symbol "Enable guides for 9-slice scaling" option for a symbol pattern, used when exporting the symbol to Flash.
AIAPI AIErr(*	SetSymbol9SliceGrid )(AIPatternHandle symbolPattern, AIRealRect slice9Grid)
	Sets the symbol scaling grid for 9-slice scaling for a symbol pattern, to be used when exporting the symbol to Flash.
AIAPI AIErr(*	GetSymbol9SliceGrid )(AIPatternHandle symbolPattern, AIRealRect *slice9Grid)
	Retrieves the symbol scaling grid for 9-slice scaling for a symbol pattern, used when exporting the symbol to Flash.
AIAPI AIErr(*	SetEditingSymbolDefinition )(AIPatternHandle symbolPattern, AIArtHandle symbolArt)
	Starts an editing session for a symbol pattern.
AIAPI AIErr(*	EndEditingSymbolDefinition )(AIPatternHandle symbolPattern, AIBoolean updateSymbol)
	Ends an editing session for a symbol pattern, allowing you to apply or discard the changes made during the session.
AIAPI AIBoolean(*	GetSymbolEditMode )()
	Reports whether symbol edit mode is active.
AIAPI AIErr(*	ExitSymbolEditMode )()
	Ends all current symbol editing sessions, restoring the original symbol pattern prototypes to the artboard and discarding all changes made while editing.
AIAPI AIBoolean(*	EditingSymbolPattern )(AIPatternHandle symbolPattern)
	Reports whether a symbol pattern is currently being edited.
AIAPI AIBoolean(*	IsSymbolEditingArtType )(AIArtHandle art, AIPatternHandle *symbolPattern)
	Reports whether an art object represents the prototype of a symbol pattern that is currently being edited, and if true, optionally returns the pattern being edited.
AIAPI AIErr(*	ValidateSymbolEditingArt )(AIPatternHandle symbolPattern, AIArtHandle editingArtParent)
	Validates the editing art object that represents the prototype of a symbol pattern that is being edited.
AIAPI AIErr(*	SetSymbolPixelPerfect )(AIPatternHandle symbolPattern, AIBoolean isPixelPerfect)
	Sets the Pixel Perfect status for a symbol and its instances.
AIAPI AIErr(*	GetSymbolEnablePixelPerfect )(AIPatternHandle symbolPattern, AIBoolean *isPixelPerfect)
	Retrieves a symbol's Pixel Perfect status.
AIAPI AIErr(*	IsSymbolArt9SliceScaled )(AIArtHandle symbolArt, AIBoolean *is9SliceScaled)
	Reports whether symbol art is scaled with 9-slice scaling.
AIAPI AIErr(*	RetargetForCurrentDocumentAsUnlisted )(AIPatternHandle srcPattern, AIPatternHandle *dstPattern)
	Retargets a symbol pattern, fill pattern, or brush pattern for the current document.

Detailed Description

This suite is always available.

The functions allow you to query and manipulate the symbol patterns and symbol instances in a document. Symbol instances are art objects of type kSymbolArt, and are associated with a transformation matrix.

These notifiers are related to symbols:
kAIArtSymbolSetChangedNotifier
kAIArtSymbolSetDetailedChangeNotifier

These dictionary keys are related to symbols:
kAISymbolToSelectDictKey

Acquire this suite using SPBasicSuite::AcquireSuite() with the constants kAISymbolSuite and kAISymbolVersion.

Listed and Unlisted Symbols

Listed symbols appear in the Symbols palette, and are saved when a document is closed, even if there are no instances of them in the document. They can be considered public, shared between documents.

Unlisted symbols do not appear in the Symbols palette. When the document is saved, they are not written out unless there is at least one instance of the symbol used in the document. Unlisted symbols can be considered private to a specific document.

Ordering of the global symbol list affects only listed symbols. When you retrieve unlisted symbols, their order is usually, but not always, that of creation. The position index is not guaranteed to remain constant between calls.

Unlisted symbols are intended for instances that are automatically generated in a context where they are not directly selectable, such as the result group of a plug-in art object (for instance, the intermediate steps of a blend or the particles of a particle system), or the styled art of an object with a complex appearance. They are systematically derived by the plug-in group or a Live Effect from one or more listed symbols.

Symbol instances that appear in ordinary selectable contexts should always be based on listed symbols, but they do not become listed automatically. Any command that expands objects like plug-in groups or appearances should call MakeSymbolPatternListed() on any symbols used by instances in the expanded art. It is not necessary to first call IsSymbolPatternListed(); if the symbol is already listed, the call does nothing.

Unlike art styles, for which being unlisted is tied to having an anonymous name (see AIArtStyleSuite), an unlisted symbol can have any name. When you create unlisted symbols, you should give names that will make sense if they later become listed, so that Expand commands do not need to rename them without sufficient context. To avoid name conflicts, use names that are unlikely to be chosen by a user.

For example, if a particle system or brush generates unlisted symbols by tinting listed symbols, it can use names like 'Snowflake autotinted 10Y' and 'Snowflake autotinted 8C 5M', where Snowflake is the name of the listed symbol, and the word 'autotinted' is in a string resource that can be localized. Using 'autotinted' instead of simply 'tinted' decreases the likelihood that a user would coincidentally assign that name to a listed symbol.

Member Data Documentation

AIAPI AIBoolean(* AISymbolSuite::ArtUsesSymbolPattern)(AIArtHandle art, ai::int16 searchScope, AIPatternHandle targetSymbol, AIPatternHandle *oneFoundSymbol, AIPatternHandle ***allFoundSymbols, int *foundCount, int *globalObjectUsage)

Reports whether an art object uses a specified symbol in a specified way.

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

Parameters:

	art	The art object, or `NULL` to search the entire artwork tree. In this case, the search includes descendants regardless of the value of the `kSearchDescendants` flag.
	searchScope	The scope of the search, a logical OR of `AISymbolSearchScope` bit flags.
	targetSymbol	The symbol reference, or `NULL` to search for any symbol.
	oneFoundSymbol	[out] Optional. When `targetSymbol` is `NULL`, a buffer in which to return a single matching symbol found within the search scope, or `NULL` if more than one matching symbol is found.

Note:: oneFoundSymbol is used by the Symbols palette to decide which symbol to select. If an object uses multiple symbols, nothing is selected. The scope for this type of usage should not include kSearchNestedSymbolPatterns. For example, if symbol A's definition includes symbol B, and the user selects an instance of symbol A, symbol A should be selected in the palette. If the user selects a particle set containing instances of both symbol A and symbol B, neither symbol should be selected in the palette.

Parameters:

allFoundSymbols [out] Optional. When targetSymbol is NULL, a buffer in which to return the handle of an array of matching symbols, of size foundCount. This memory is allocated by the function, and you must free it using AIMdMemorySuite::MdMemoryDisposeHandle().

If no art object is specified, you can still specify the output array. This is how the "Select All Unused" command in the Symbols palette is implemented.

If an art object is specified, use this array to examine patterns that are referenced by a plug-in group that puts multiple symbols in its dictionary, such as a particle set.

Parameters:

	foundCount	[out] When `targetSymbol` is `NULL`, a buffer in which to return the size of the `allFoundSymbols` array.
	globalObjectUsage	Not implemented.

Returns:: True if any matching symbols are found.

AIAPI AIErr(* AISymbolSuite::BreakLinkToSymbol)(AIArtHandle symbolArt, ai::int16 paintOrder, AIArtHandle prep, AIArtHandle *expandedArt)

Creates a copy of a symbol's definition artwork, transforms it using the matrix of a symbol instance, and places it into the current document at a specified place in the paint order.

Transfers attributes from the symbol instance to the transformed art.

Does not do any internal expansion of strokes, active styles or plug-in groups inside the symbol definition, even when a rotational or shear transform is applied. Preserves the full structure and editability of the symbol definition, at the cost of sometimes not preserving the appearance of the instance.

This is the equivalent of calling CopySymbolPatternArt() and then performing the transformation using the AITransformArtSuite, but is more efficient. If the instance matrix is a simple placement matrix, this is equivalent to InsertExpandedSymbolArt().

Parameters:

	symbolArt	The symbol instance, an art object of type `kSymbolArt`. This object is not deleted.
	paintOrder	The paint order position, relative to the `prep` object, an `AITypes::AIPaintOrder` value.
	prep	The prepositional art object for the paint order.
	expandedArt	[out] Optional. A buffer in which to return the new art object.

AIAPI AIErr(* AISymbolSuite::CopySymbolPatternArt)(AIPatternHandle symbolPattern, ai::int16 paintOrder, AIArtHandle prep, AIArtHandle *newArt)

Creates a copy of a symbol pattern's definition artwork and places it into the current document at a specified place in the paint order.

Parameters:

	symbolPattern	The symbol pattern reference.
	paintOrder	The paint order position, relative to the `prep` object, an `AITypes::AIPaintOrder` value.
	prep	The prepositional art object for the paint order.
	newArt	[out] Optional. A buffer in which to return the new art object.

AIAPI AIErr(* AISymbolSuite::CopySymbolPatternOutline)(AIPatternHandle symbolPattern, ai::int16 paintOrder, AIArtHandle prep, AIArtHandle *newArt, ai::int32 convertToOutlineOptions)

Creates a copy of a symbol pattern's definition artwork, converts it to outline using specified options, and places the result into the current document at a specified place in the paint order.

Parameters:

	symbolPattern	The symbol pattern reference.
	paintOrder	The paint order position, relative to the `prep` object, an `AITypes::AIPaintOrder` value.
	prep	The prepositional art object for the paint order.
	newArt	[out] Optional. A buffer in which to return the new art object, or a `NULL` object if no outline can be generated.
	convertToOutlineOptions	Option flags for conversion, a logical OR of these values: `kOutlineExpandAppearance` `kOutlineEliminateUnpainted` `kOutlineAddStrokes` `kOutlineSubtractStrokes` `kOutlineAlwaysIncludeFillArea` `kOutlineAlwaysStrokeStraightLines`

AIAPI AIErr(* AISymbolSuite::CountSymbolPatterns)(ai::int32 *count, ASBoolean includeUnlisted)

Counts the number of symbol definitions in the global list for the current document.

Use with GetNthSymbolPattern() to iterate through listed or through listed and unlisted symbols.

Parameters:

	count	[out] A buffer in which to return the number of symbols.
	includeUnlisted	When true, include unlisted symbols in the count. When false, count only listed symbols. See Listed and Unlisted Symbols.

AIAPI AIErr(* AISymbolSuite::CountSymbolPatternsFromDocument)(ai::int32 *count, AIDocumentHandle document)

Counts the number of symbol definitions in the global list of a specified document.

Use with GetNthSymbolPatternFromDocument() to iterate through listed (public) symbols.

Parameters:

	count	[out] A buffer in which to return the number of symbols.
	document	The document. Use the `AIDocumentListSuite` or `AIPathStyleSuite::ImportStyles()` to obtain a document handle.

AIAPI AIErr(* AISymbolSuite::DeleteSymbolPattern)(AIPatternHandle symbolPattern)

Deletes a symbol definition.

Parameters:

symbolPattern

The symbol reference.

Returns:: The error kCantDeleteSymbolUsedInLiveEffectsErr if the symbol pattern is used in a Live Effect. The error kBadParameterErr if NULL is passed.

AIAPI AIBoolean(* AISymbolSuite::EditingSymbolPattern)(AIPatternHandle symbolPattern)

Reports whether a symbol pattern is currently being edited.

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

Parameters:

symbolPattern

The symbol pattern reference.

Returns:: True if at the symbol pattern is being edited, false otherwise.

AIAPI AIErr(* AISymbolSuite::EndEditingSymbolDefinition)(AIPatternHandle symbolPattern, AIBoolean updateSymbol)

Ends an editing session for a symbol pattern, allowing you to apply or discard the changes made during the session.

The corresponding symbol instance that was hidden when setting the symbol in edit mode is made visible.

Parameters:

	symbolPattern	The symbol pattern reference.
	updateSymbol	True to apply the edits to the pattern, false to discard the editing changes and restore the original symbol pattern.

Precondition:: SetEditingSymbolDefinition()

AIAPI AIErr(* AISymbolSuite::ExitSymbolEditMode)()

Ends all current symbol editing sessions, restoring the original symbol pattern prototypes to the artboard and discarding all changes made while editing.

To save any changes, and to restore the per-symbol editing state information, use EndEditingSymbolDefinition() for each symbol being edited.

Precondition:: SetEditingSymbolDefinition()

AIAPI AIErr(* AISymbolSuite::GetHardTransformOfSymbolArt)(AIArtHandle symbolArt, AIRealMatrix *transform)

Retrieves the transformation matrix that Illustrator uses to transform specified symbol art into a symbol instance.

Parameters:

	symbolArt	The symbol instance, an art object of type `kSymbolArt`.
	transform	[out] A buffer in which to return the transformation matrix.

See also:: AIHardSoftSuite for a discussion of coordinate systems.

Note:: Use AIHardSoftSuite::AIRealMatrixRealSoft() and AIHardSoftSuite::AIRealMatrixRealHard() to translate between the hard and soft forms of the matrix (not AIHardSoftSuite::AIRealMatrixHarden() and AIHardSoftSuite::AIRealMatrixSoften(), which affect only the tx ty components).

AIAPI AIErr(* AISymbolSuite::GetNthSymbolPattern)(ai::int32 n, AIPatternHandle *symbolPattern, ASBoolean includeUnlisted)

Retrieves a symbol pattern from the global list for the current document.Use with CountSymbolPatterns() to iterate through listed or through listed and unlisted symbols.

Parameters:

	n	The 0-based position index.
	symbolPattern	[out] A buffer in which to return the symbol reference.
	includeUnlisted	When true, get both listed and unlisted symbols. When false, get only listed symbols. See Listed and Unlisted Symbols.

AIAPI AIErr(* AISymbolSuite::GetNthSymbolPatternFromDocument)(ai::int32 n, AIPatternHandle *symbolPattern, AIDocumentHandle document)

Retrieves a symbol pattern from the global list for a specified document.

Use with CountSymbolPatternsFromDocument() to iterate through listed (public) symbols.

Parameters:

	n	The 0-based position index.
	symbolPattern	[out] A buffer in which to return the symbol reference.
	document	The document. Use the `AIDocumentListSuite` or `AIPathStyleSuite::ImportStyles()` to obtain a document handle.

AIAPI AIErr(* AISymbolSuite::GetSoftTransformOfSymbolArt)(AIArtHandle symbolArt, AIRealMatrix *transform)

Retrieves the transformation matrix that a plug-in can use to transform to transform specified symbol art into a symbol instance (using the AITransformArtSuite).

Parameters:

	symbolArt	The symbol instance, an art object of type `kSymbolArt`.
	transform	[out] A buffer in which to return the transformation matrix.

See also:: AIHardSoftSuite for a discussion of coordinate systems.

AIAPI AIErr(* AISymbolSuite::GetSymbol9SliceGrid)(AIPatternHandle symbolPattern, AIRealRect *slice9Grid)

Retrieves the symbol scaling grid for 9-slice scaling for a symbol pattern, used when exporting the symbol to Flash.

Parameters:

	symbolPattern	The symbol pattern reference.
	slice9Grid	[out] A buffer in which to return the rectangular area of the center slice.

AIAPI AIErr(* AISymbolSuite::GetSymbolByNameFromDocument)(const ai::UnicodeString &name, AIPatternHandle *symbolPattern, AIDocumentHandle document)

Retrieves a symbol pattern by name from a specified document.

Parameters:

	name	The name string.
	symbolPattern	[out] A buffer in which to return the symbol reference, or a `NULL` object if no such symbol is found.
	document	The document. Use the `AIDocumentListSuite` or `AIPathStyleSuite::ImportStyles()` to obtain a document handle.

AIAPI AIBoolean(* AISymbolSuite::GetSymbolEditMode)()

Reports whether symbol edit mode is active.

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

Returns:: True if at least one symbol pattern is being edited, false otherwise.

AIAPI AIErr(* AISymbolSuite::GetSymbolEnableGuides)(AIPatternHandle symbolPattern, AIBoolean *enableGuides)

Retrieves the symbol "Enable guides for 9-slice scaling" option for a symbol pattern, used when exporting the symbol to Flash.

Parameters:

	symbolPattern	The symbol pattern reference.
	enableGuides	[out] A buffer in which to return true if 9-slice scaling is on, false if it is off.

AIAPI AIErr(* AISymbolSuite::GetSymbolEnablePixelPerfect)(AIPatternHandle symbolPattern, AIBoolean *isPixelPerfect)

Retrieves a symbol's Pixel Perfect status.

Parameters:

	symbolPattern	The symbol pattern reference.
	isPixelPerfect	[out] A buffer in which to return true if the symbol is Pixel Perfect, false otherwise.

AIAPI AIErr(* AISymbolSuite::GetSymbolExportType)(AIPatternHandle symbolPattern, AISymbolFlashExportType *exportType)

Retrieves the symbol export type for a symbol pattern, used when exporting the symbol to Flash.

Parameters:

	symbolPattern	The symbol pattern reference.
	exportType	[out] The Flash export type.

AIAPI AIErr(* AISymbolSuite::GetSymbolPatternArt)(AIPatternHandle pattern, AIArtHandle *art)

Retrieves a read-only handle to the definition art of a symbol.

You can examine or duplicate the returned art, but cannot edit it.

Parameters:

	pattern	The symbol pattern reference.
	art	[out] A buffer in which to return the definition art.

AIAPI AIErr(* AISymbolSuite::GetSymbolPatternByName)(const ai::UnicodeString &name, AIPatternHandle *symbolPattern)

Retrieves a symbol pattern by name from the current document.

Parameters:

	name	The name string.
	symbolPattern	[out] A buffer in which to return the symbol reference, or a `NULL` object if no such symbol is found.

AIAPI AIErr(* AISymbolSuite::GetSymbolPatternDisplayName)(ai::UnicodeString &name)

Strips any hidden characters from the end of a symbol name to create a displayable string.

Parameters:

name

[in, out] The symbol name string, which is modified in place.

AIAPI AIErr(* AISymbolSuite::GetSymbolPatternName)(AIPatternHandle symbolPattern, ai::UnicodeString &name)

Retrieves the name of a symbol.

Parameters:

	symbolPattern	The symbol pattern reference.
	name	[out] A buffer in which to return the name string. Truncates a name that is too long to fit in the buffer.

Returns:: kNameTooLongErr error if the name was truncated.

AIAPI AIErr(* AISymbolSuite::GetSymbolPatternOfSymbolArt)(AIArtHandle symbolArt, AIPatternHandle *symbolPattern)

Retrieves the symbol pattern definition of a symbol instance.

Parameters:

	symbolArt	The symbol instance, an art object of type `kSymbolArt`.
	symbolPattern	[out] A buffer in which to return the symbol pattern reference.

AIAPI AIErr(* AISymbolSuite::InsertExpandedSymbolArt)(AIArtHandle symbolArt, ai::int16 paintOrder, AIArtHandle prep, AIArtHandle *expandedArt)

Expands a symbol instance and places the resulting art into the artwork tree.

The function preserves the appearance, not the editability, of the symbol definition.

If the instance transformation matrix is a simple placement matrix, this is equivalent to BreakLinkToSymbol().
If the matrix includes a scale, rotation, shear, or reflection, the function expands any appearances or plug-in groups inside the symbol definition, then applies the matrix.

If the matrix includes a shear or a non-uniform scale, the function expands strokes before applying the matrix.

Parameters:

	symbolArt	The symbol instance, an art object of type `kSymbolArt`. This object is not deleted.
	paintOrder	The paint order position, relative to the `prep` object, an `AITypes::AIPaintOrder` value.
	prep	The prepositional art object for the paint order.
	expandedArt	[out] Optional. A buffer in which to return the new art object.

AIAPI AIErr(* AISymbolSuite::InsertSymbolArtOutline)(AIArtHandle symbolArt, ai::int16 paintOrder, AIArtHandle prep, AIArtHandle *expandedArt, ai::int32 convertToOutlineOptions)

Expands a symbol definition, outlines the symbol definition, applies the instance transformation to the outlined definition art.

and finally places the transformed outline art into the artwork tree.

Parameters:

	symbolArt	The symbol instance, an art object of type `kSymbolArt`. This object is not deleted.
	paintOrder	The paint order position, relative to the `prep` object, an `AITypes::AIPaintOrder` value.
	prep	The prepositional art object for the paint order.
	expandedArt	[out] Optional. A buffer in which to return result art.
	convertToOutlineOptions	Option flags for conversion, a logical OR of these values: `kOutlineExpandAppearance` `kOutlineEliminateUnpainted` `kOutlineAddStrokes` `kOutlineSubtractStrokes` `kOutlineAlwaysIncludeFillArea` `kOutlineAlwaysStrokeStraightLines`

See also:: InsertExpandedSymbolArt()

AIAPI AIErr(* AISymbolSuite::IsSymbolArt9SliceScaled)(AIArtHandle symbolArt, AIBoolean *is9SliceScaled)

Reports whether symbol art is scaled with 9-slice scaling.

Not all instances of a symbol pattern that has 9-slice scaling guides actually use 9-slice scaling. For example, an instance can have no scaling.

Parameters:

	symbolArt	[in] The symbol instance, an art object of type `kSymbolArt`.
	is9SliceScaled	[out] A buffer in which to return true if the symbol art is scaled with 9-slice scaling.

AIAPI AIBoolean(* AISymbolSuite::IsSymbolEditingArtType)(AIArtHandle art, AIPatternHandle *symbolPattern)

Reports whether an art object represents the prototype of a symbol pattern that is currently being edited, and if true, optionally returns the pattern being edited.

Parameters:

	art	The art object reference.
	symbolPattern	[out] Optional. A buffer in which to return the symbol pattern.

Returns:: True if the art object does represent the prototype of a symbol pattern that is currently being edited, false otherwise.

AIAPI AIBoolean(* AISymbolSuite::IsSymbolPatternListed)(AIPatternHandle symbolPattern)

Reports whether a symbol definition is listed in the current document.

If the symbol belongs to a different document, it will return false even if the symbol is listed in the document to which it belongs. See Listed and Unlisted Symbols for the definition of listed and unlisted symbols. (Note that this function returns a Boolean value, not an error code.)

Parameters:

symbolPattern

The symbol pattern reference.

Returns:: True if the symbol pattern is listed in the current document.

AIAPI AIErr(* AISymbolSuite::MakeSymbolPatternListed)(AIPatternHandle symbolPattern)

Makes a symbol definition, which must be in the symbol set of the current document, listed.

See Listed and Unlisted Symbols.

Parameters:

symbolPattern

The symbol pattern reference.

AIAPI AIErr(* AISymbolSuite::MoveSymbolPatternInList)(AIPatternHandle symbolPattern, int index)

Moves a listed symbol to a specific index position in the global list of symbols.

Increments the position of the symbol previously at that index, and of all subsequent listed symbols. See Listed and Unlisted Symbols.

Parameters:

	symbolPattern	The symbol pattern reference.
	index	The new 0-based index position, or -1 to move to the end of the list.

AIAPI AIErr(* AISymbolSuite::NewInstanceAtLocation)(AIPatternHandle symbolPattern, AIRealPoint center, ai::int16 paintOrder, AIArtHandle prep, AIArtHandle *newArt)

Creates a new symbol instance with its center at a specified location.

Parameters:

	symbolPattern	The symbol pattern reference.
	center	The location, in page coordinates.
	paintOrder	The paint order position, relative to the `prep` object, an `AITypes::AIPaintOrder` value.
	prep	The prepositional art object for the paint order.
	newArt	[out] A buffer in which to return the new instance, an art object of type `kSymbolArt`.

Returns:: kBadParameterErr error if there are no symbols defined in the current document.

AIAPI AIErr(* AISymbolSuite::NewInstanceCenteredInView)(AIPatternHandle symbolPattern, ai::int16 paintOrder, AIArtHandle prep, AIArtHandle *newArt)

Creates a new symbol instance in the center of the current document view.

Parameters:

	symbolPattern	The symbol pattern reference.
	paintOrder	The paint order position, relative to the `prep` object, an `AITypes::AIPaintOrder` value.
	prep	The prepositional art object for the paint order.
	newArt	[out] A buffer in which to return the new instance, an art object of type `kSymbolArt`.

Returns:: kBadParameterErr error if there are no symbols defined in the current document.

AIAPI AIErr(* AISymbolSuite::NewInstanceWithTransform)(AIPatternHandle symbolPattern, AIRealMatrix *transform, ai::int16 paintOrder, AIArtHandle prep, AIArtHandle *newArt)

Creates a new symbol instance with a specified transformation matrix.

Parameters:

	symbolPattern	The symbol pattern reference.
	transform	The transformation matrix.
	paintOrder	The paint order position, relative to the `prep` object, an `AITypes::AIPaintOrder` value.
	prep	The prepositional art object for the paint order.
	newArt	[out] A buffer in which to return the new instance, an art object of type `kSymbolArt`.

Returns:: kBadParameterErr error if there are no symbols defined in the current document.

AIAPI AIErr(* AISymbolSuite::NewSymbolPattern)(AIPatternHandle *newSymbolPattern, AIArtHandle definitionArt, AISymbolRegistrationPoint registrationPoint, ASBoolean transformDefinitionArt, ASBoolean unlisted)

Creates a new symbol definition from specified source art, which is copied as the defining art for the new symbol.

Parameters:

	newSymbolPattern	[out] A buffer in which to return the new symbol reference.
	definitionArt	The source art, or `NULL` to create a symbol whose definition is an empty group.
	registrationPoint	The registration point of the new symbol pattern.
	transformDefinitionArt	True to move the registration point of the new symbol pattern to the canvas origin.
	unlisted	When true, make the new symbol unlisted. Use `SetSymbolPatternName()` to name unlisted symbols. See Listed and Unlisted Symbols.

AIAPI AIErr(* AISymbolSuite::NewSymbolPatternFromSel)(AIPatternHandle *symbolPattern, AISymbolRegistrationPoint registrationPoint)

Creates a new listed symbol definition from selected art, which is copied as the defining art for the new symbol.

If no art is selected, creates a symbol whose definition is an empty group.

Parameters:

	symbolPattern	[out] A buffer in which to return the new symbol reference.
	registrationPoint	The registration point of the new symbol pattern.

AIAPI AIErr(* AISymbolSuite::NewSymbolPatternFromSelGetBounds)(AIPatternHandle *symbolPattern, AIRealRect *selectionBounds, AISymbolRegistrationPoint registrationPoint)

Creates a new listed symbol definition from selected art, which is copied as the defining art for the new symbol, and reports the bounds of the selected art.

(You cannot call AIArtSuite::GetArtBounds() for the symbol pattern art after defining it, because the definition art is copied and moved.) Use to insert an instance of the new symbol in place of the selection.

Parameters:

	symbolPattern	[out] A buffer in which to return the new symbol reference.
	selectionBounds	[out] A buffer in which to return the bounding box of the selected art.
	registrationPoint	The registration point of the new symbol pattern.

AIAPI AIErr(* AISymbolSuite::PasteSymbolPatternArt)(AIPatternHandle symbolPattern)

Creates a copy of a symbol pattern's definition artwork and places it into the current document at the center of the current view, at the current layer and using the current insertion mode.

It is the equivalent of using a simple Paste command.

Parameters:

symbolPattern

The symbol pattern reference.

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

See also:: AIPatternSuite::GetPattern()

Note:: To get an editable copy of a symbol, it is better to use AIDictionarySuite::NewArtEntry() to create a group that is not in the artwork tree, insert the definition copy into that using CopySymbolPatternArt(), and then delete the dictionary entry. This avoids modifying the art tree and triggering unneeded synchronization and change notifications. This technique is often used by export filters to make systematic adjustments to Illustrator art before converting it to an easy-to-export form.

AIAPI AIErr(* AISymbolSuite::PeekCachedPatternOutline)(AIPatternHandle symbolPattern, AIArtHandle *outlineArt, ai::int32 convertToOutlineOptions)

Retrieves a cached outline for a symbol pattern, if one has been generated for a given set of conversion options.

You can examine or duplicate the returned outline art, but cannot edit it.

Parameters:

	symbolPattern	The symbol pattern reference.
	outlineArt	[out] A buffer in which to return the cached outline art, or `NULL` if no cached outline has been generated for the given options.
	convertToOutlineOptions	Option flags for conversion, a logical OR of these values: `kOutlineExpandAppearance` `kOutlineEliminateUnpainted` `kOutlineAddStrokes` `kOutlineSubtractStrokes` `kOutlineAlwaysIncludeFillArea` `kOutlineAlwaysStrokeStraightLines`

AIAPI AIErr(* AISymbolSuite::RetargetForCurrentDocument)(AIPatternHandle srcPattern, AIPatternHandle *dstPattern)

Retargets a symbol pattern, fill pattern, or brush pattern for the current document.

Creates a new pattern if needed, with the same definition art and a unique name based on the source pattern's name. All other global objects (colors, patterns, brushes, styles, and so on) used indirectly in the definition are similarly retargeted, using an existing object if one matches and creating a new one otherwise.

The new pattern is made listed in the current document if it was listed in the source document, and made unlisted in the current document if it was unlisted in the source document. In this context, a listed symbol never matches an unlisted one, even if it has the same name and definition.

Use for drag-and-drop between library palettes and the main document palette.

Parameters:

	srcPattern	A symbol pattern, fill pattern, or brush pattern reference.
	dstPattern	[out] A buffer in which to return the new pattern, or an existing pattern in the current document with the same name and definition, or the source pattern if it was already in the current document.

Note:: Fill patterns are usually retargeted indirectly using the AIPathStyleSuite, and brush patterns using the AIObjectSetSuite.

See also:: AIPatternSuite, AIObjectSetSuite::RetargetForCurrentDocument(), AIPathStyleSuite::RetargetForCurrentDoc(), RetargetForCurrentDocumentAsUnlisted()

AIAPI AIErr(* AISymbolSuite::RetargetForCurrentDocumentAsUnlisted)(AIPatternHandle srcPattern, AIPatternHandle *dstPattern)

Retargets a symbol pattern, fill pattern, or brush pattern for the current document.

Creates a new pattern if needed, with the same definition art and a unique name based on the source pattern's name. All other global objects (colors, patterns, brushes, styles, and so on) used indirectly in the definition are similarly retargeted, using an existing object if one matches and creating a new one otherwise.

The new pattern is NOT made listed in the current document, even if it was listed in the source document.

Use this function when the source symbol is in a document that is being used as a content resource to support an effect, such as 3D Bevels or Arrowheads, where you might want the symbols to be visible in the Symbols panel of the resource document, but not in the Symbols panel of the documents where the effect is in use.

This differs from first calling RetargetForCurrentDocument() and then UnlistSymbolPattern() in that RetargetForCurrentDocument() causes a kAIArtSymbolListChangedNotifier to be sent, and this function does not, thereby circumventing any notification to clients who care only about changes to listed symbols.

Parameters:

	srcPattern	A symbol pattern, fill pattern, or brush pattern reference.
	dstPattern	[out] A buffer in which to return the new pattern, or an existing pattern in the current document with the same name and definition, or the source pattern if it was already in the current document.

Note:: Fill patterns are usually retargeted indirectly using the AIPathStyleSuite, and brush patterns using the AIObjectSetSuite.

See also:: AIPatternSuite, AIObjectSetSuite::RetargetForCurrentDocument(), AIPathStyleSuite::RetargetForCurrentDoc()

AIAPI AIErr(* AISymbolSuite::SetEditingSymbolDefinition)(AIPatternHandle symbolPattern, AIArtHandle symbolArt)

Starts an editing session for a symbol pattern.

Invokes isolation mode on a copy of the prototype of the pattern, and places the copy on the artboard. If a symbol art is specified, the copy is placed in the same location as the symbol instance, hiding the original. Otherwise, the copy is placed in the center of the artboard.

You can start nested editing sessions for nested symbols.

Editing changes are signaled with AILayerList::kAIIsolationModeChangedNotifier and AILayerList::kAIBeforeIsolationModeChangedNotifier. Use ValidateSymbolEditingArt() to validate the art being edited.

Postcondition:: Use EndEditingSymbolDefinition() to end the editing session, optionally updating the symbol pattern's prototype with the changes in the copy before returning it to the artboard.; Use ExitSymbolEditMode() to force all symbol editing sessions to end without saving any changes.

Parameters:

	symbolPattern	The symbol pattern reference.
	symbolArt	Optional. A symbol art object whose definition needs to be edited.

Returns:: May return AIIsolationMode::kCantIsolateFromCurrentModeErr

AIAPI AIErr(* AISymbolSuite::SetHardTransformOfSymbolArt)(AIArtHandle symbolArt, AIRealMatrix *transform)

Sets the application transformation matrix for a symbol instance.

Parameters:

	symbolArt	The symbol instance, an art object of type `kSymbolArt`.
	transform	The new transformation matrix.

See also:: GetHardTransformOfSymbolArt()

AIAPI AIErr(* AISymbolSuite::SetSoftTransformOfSymbolArt)(AIArtHandle symbolArt, AIRealMatrix *transform)

Sets the plug-in transformation matrix for a symbol instance.

Parameters:

	symbolArt	The symbol instance, an art object of type `kSymbolArt`.
	transform	The new transformation matrix.

See also:: GetSoftTransformOfSymbolArt()

AIAPI AIErr(* AISymbolSuite::SetSymbol9SliceGrid)(AIPatternHandle symbolPattern, AIRealRect slice9Grid)

Sets the symbol scaling grid for 9-slice scaling for a symbol pattern, to be used when exporting the symbol to Flash.

Parameters:

	symbolPattern	The symbol pattern reference.
	slice9Grid	The rectangular area of the center slice.

AIAPI AIErr(* AISymbolSuite::SetSymbolEnableGuides)(AIPatternHandle symbolPattern, AIBoolean enableGuides)

Sets the symbol "Enable guides for 9-slice scaling" option for a symbol pattern, to use when exporting the symbol to Flash.

Parameters:

	symbolPattern	The symbol pattern reference.
	enableGuides	True to turn 9-slice scaling on, false to turn it off.

AIAPI AIErr(* AISymbolSuite::SetSymbolExportType)(AIPatternHandle symbolPattern, AISymbolFlashExportType exportType)

Sets the symbol export type for a symbol pattern, to use when exporting the symbol to Flash.

Parameters:

	symbolPattern	The symbol pattern reference.
	exportType	The Flash export type.

AIAPI AIErr(* AISymbolSuite::SetSymbolPatternArt)(AIPatternHandle symbolPattern, AIArtHandle definitionArt, ASBoolean transformDefinationArt)

Creates a copy of source art and makes it the defining art for a symbol.

Updates any existing instances of the symbol.

Parameters:

	symbolPattern	The symbol pattern reference.
	definitionArt	The source art.
	transformDefinitionArt	True to move the registration point of the symbol pattern to the canvas origin.

AIAPI AIErr(* AISymbolSuite::SetSymbolPatternBaseName)(AIPatternHandle symbolPattern, ai::UnicodeString &name)

Sets the name of a symbol, appending numbers to a name string that is already in use to make it unique.

If the name string is very long, it can be truncated before the numbers are appended.

Parameters:

	symbolPattern	The symbol pattern reference.
	name	The new name string.

AIAPI AIErr(* AISymbolSuite::SetSymbolPatternFromSel)(AIPatternHandle symbolPattern)

Copies selected art and makes it the defining art for a symbol.

Updates any existing instances of the symbol.

Parameters:

symbolPattern

The symbol pattern reference.

See also:: AIPatternSuite::SetPattern()

AIAPI AIErr(* AISymbolSuite::SetSymbolPatternFromSelGetBounds)(AIPatternHandle symbolPattern, AIRealRect *selectionBounds)

Sets a symbol definition from selected art, and reports the bounds of the selected art.

Parameters:

	symbolPattern	The symbol pattern reference.
	selectionBounds	[out] Optional. A buffer in which to return the bounding box of the selected art.

See also:: NewSymbolPatternFromSelGetBounds.

AIAPI AIErr(* AISymbolSuite::SetSymbolPatternName)(AIPatternHandle symbolPattern, const ai::UnicodeString &name)

Sets the name of a symbol.

Parameters:

name

The new name string.

Returns:: kNameTooLongErr error if the name length exceeds kMaxSymbolNameLength.
kInvalidNameErr error if the name contains illegal characters, is of zero length, or consists entirely of spaces.
kNameInUseErr if the name is already used for another symbol.
In any error case, the symbol name remains unchanged.

See also:: SetSymbolPatternBaseName()

AIAPI AIErr(* AISymbolSuite::SetSymbolPatternOfSymbolArt)(AIArtHandle symbolArt, AIPatternHandle symbolPattern)

Sets the symbol pattern definition of a symbol instance.

Parameters:

	symbolArt	The symbol instance, an art object of type `kSymbolArt`.
	symbolPattern	The symbol pattern reference.

AIAPI AIErr(* AISymbolSuite::SetSymbolPixelPerfect)(AIPatternHandle symbolPattern, AIBoolean isPixelPerfect)

Sets the Pixel Perfect status for a symbol and its instances.

Parameters:

	symbolPattern	The symbol pattern reference.
	isPixelPerfect	True to make the symbol and its instances Pixel Perfect, false otherwise.

AIAPI AIErr(* AISymbolSuite::SortListedSymbolPatterns)(void)

Sorts the listed symbols in the global list of symbols, alphabetically by name.

See Listed and Unlisted Symbols.

AIAPI AIErr(* AISymbolSuite::UnlistSymbolPattern)(AIPatternHandle symbolPattern)

Makes a symbol definition unlisted.

See Listed and Unlisted Symbols.

Parameters:

symbolPattern

The symbol pattern reference.

AIAPI AIErr(* AISymbolSuite::ValidateSymbolEditingArt)(AIPatternHandle symbolPattern, AIArtHandle editingArtParent)

Validates the editing art object that represents the prototype of a symbol pattern that is being edited.

The editing art could become invalid due to operations such as duplicate or delete. If the symbol pattern's editing art is not a valid art object, looks under the parent for an art object whose state represents the editing art of the given symbol pattern, and sets it as the valid editing art. If there is no valid art object under the parent, creates an empty group and sets it as the valid editing art.

Use this in response to the AILayerList::kAIBeforeIsolationModeChangedNotifier, with the information received by calling AIIsolationModeSuite::GetIsolatedArtAndParents().

Parameters:

	symbolPattern	The symbol pattern reference.
	editingArtParent	Parent object that contains the editing art.

AIAPI AIBoolean(* AISymbolSuite::ValidateSymbolPattern)(AIPatternHandle symbolPattern)

Reports whether a symbol is still known to the system.

A symbol reference can change if you retain it between message. To ensure a valid reference, get the reference from the kAIArtSymbolSetChangedNotifier. (Note that this function returns a Boolean value, not an error code.)

Parameters:

symbolPatter

The symbol reference.

Returns:: True if the symbol is a valid reference.

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

AISymbol.h

AISymbolSuite Struct Reference [API Suite List]

Public Attributes

Detailed Description

Listed and Unlisted Symbols

Member Data Documentation

AISymbolSuite Struct Reference
[API Suite List]