AIArt.h File Reference

#include "AITypes.h"
#include "AILayer.h"
#include "AIHeaderBegin.h"
#include "AIHeaderEnd.h"

Go to the source code of this file.

Classes
struct	AIArtSuite
	This suite allows you to access and modify the artwork in Illustrator documents. More...
Defines
#define	kAIArtSuite   "AI Art Suite"
#define	kAIArtSuiteVersion19   AIAPI_VERSION(19)
#define	kAIArtSuiteVersion   kAIArtSuiteVersion19
#define	kAIArtVersion   kAIArtSuiteVersion
#define	kAIArtSelectionChangedNotifier   "AI Art Selection Changed Notifier"
	Sent when either a change in the selected art objects occurs or an artwork modification such as moving a point on a path occurs.
#define	kAIDrawingModeChangedNotifier   "AI Drawing Mode Changed Notifier"
	Sent when drawing mode of a document changes.
#define	kAIArtPropertiesChangedNotifier   "AI Art Properties Changed Notifier"
	Sent when an object attribute such as the fill or stroke of an object changes.
#define	kAIAlignmentKeyArtChangedNotifier   "AI Alignment Key Art Changed Notifier"
	Sent when the key object or the key anchor point to be aligned to changes.
#define	kUnknownArtTypeErr   'ART?'
	See AIArtSuite.
#define	kUnknownPaintOrderTypeErr   'ORD?'
	See AIArtSuite.
#define	kUntouchableArtObjectErr   'ELIO'
	See AIArtSuite.
#define	kTooDeepNestingErr   'NEST'
	See AIArtSuite.
#define	kUntouchableLayerErr   'NESS'
	See AIArtSuite.
#define	kInvalidArtTypeForDestErr   '~VAT'
	Attempt to insert an object type not allowed in the insertion location.
Typedefs
typedef struct _t_AICopyScopeOpaque *	AICopyScopeHandle
	Opaque handle to a copy scope.
Enumerations
enum	AIDrawingMode { kAIDrawNormalMode = 0, kAIDrawBehindMode, kAIDrawInsideMode }
	Type constants for drawing modes. More...
enum	AIArtType {   kAnyArt = -1, kUnknownArt = 0, kGroupArt, kPathArt,   kCompoundPathArt, kTextArtUnsupported, kTextPathArtUnsupported, kTextRunArtUnsupported,   kPlacedArt, kMysteryPathArt, kRasterArt, kPluginArt,   kMeshArt, kTextFrameArt, kSymbolArt, kForeignArt,   kLegacyTextArt, kChartArt }
	Type constants for art objects. More...
enum	AIArtOrder {   kUnknownOrder = 0, kFirstBeforeSecond = 1, kSecondAfterFirst = kFirstBeforeSecond, kFirstAfterSecond,   kSecondBeforeFirst = kFirstAfterSecond, kFirstInsideSecond, kSecondInsideFirst }
	Return values from AIArtSuite::GetArtOrder(). More...
enum	AIArtUserAttr {   kArtSelected = 0x00000001, kArtLocked = 0x00000002, kArtHidden = 0x00000004, kArtFullySelected = 0x00000008,   kArtExpanded = 0x00000010, kArtTargeted = 0x00000020, kArtIsClipMask = 0x00001000, kArtIsTextWrap = 0x00010000,   kArtSelectedTopLevelGroups = 0x00000040, kArtSelectedLeaves = 0x00000080, kArtSelectedTopLevelWithPaint = 0x00000100, kArtHasSimpleStyle = 0x00000200,   kArtHasActiveStyle = 0x00000400, kArtPartOfCompound = 0x00000800, kMatchDictionaryArt = 0x00002000, kMatchArtInGraphs = 0x00004000,   kMatchArtInResultGroups = 0x00008000, kMatchTextPaths = 0x00020000, kArtStyleIsDirty = 0x00040000, kMatchArtNotIntoPluginGroups = 0x00080000,   kMatchArtInCharts = 0x00100000 }
	State selectors for AIArtSuite::GetArtUserAttr() and AIArtSuite::SetArtUserAttr(), and AIMatchingArtSuite functions such as AIMatchingArtSuite::GetMatchingArt(). More...
enum	AIArtBoundsOptions {   kVisibleBounds = 0x0000, kControlBounds = 0x0001, kNoStrokeBounds = 0x0002, kNoExtendedBounds = 0x0004,   kWStrokeDependsOnPreference = 0x0008, kExcludeHiddenObjectBounds = 0x0010, kExcludeUnpaintedObjectBounds = 0x0020, kExcludeGuideBounds = 0x0040 }
	Flags for AIArtSuite::GetArtTransformBounds() and AIArtSuite::GetArtRotatedBounds(). More...
enum	AIArtTargettingAction {   kReplaceAction = 0x0001, kAppendAction = 0x0002, kRemoveAction = 0x0003, kUpAction = 0x0004,   kDownAction = 0x0005, kDownToLeafAction = 0x0006, kUpToLayersAction = 0x0007 }
	The values for the action parameter of AIArtSuite::ModifyTargetedArtSet(). More...
enum	AIArtTransferAttrsOptions {   kTransferID = 1 << 0, kTransferStyle = 1 << 1, kTransferOpacityMask = 1 << 2, kTransferTextWrapProperties = 1 << 3,   kTransferCompoundShapeMode = 1 << 4, kTransferSavedSelections = 1 << 5, kTransferSlicingAttributes = 1 << 6, kTransferArtLocked = 1 << 7,   kTransferArtHidden = 1 << 8, kTransferSVGProperties = 1 << 9, kTransferLivePaintPathTags = 1 << 10, kTransferPixelPerfectAttribute = 1 << 11,   kTransferLiveShapeProperties = 1 << 12, kTransferAll = 0xFFFFFFFF }
	Flags that specify which attributes are transferred by AIArtSuite::TransferAttributes(). More...
enum	AICopyScopeKind { kAICopyScopeForDuplicate = 0, kAICopyScopeForRetarget, kDummyScopeKind = 0xffffffff }
	The type of scope to create using AIArtSuite::CreateCopyScope(). More...
enum	AIPathPolarity { kAIPolarPath, kAINonPolarPath }
enum	AIArtTimeStampOptions { kAITimeStampOfArt = 1, kAITimeStampOfChildren = kAITimeStampOfArt << 1, kAITimeStampMaxFromArtAndChildren = kAITimeStampOfChildren << 1 }

---

Detailed Description

---

Define Documentation

#define kAIArtSuite   "AI Art Suite"

#define kAIArtSuiteVersion   kAIArtSuiteVersion19

#define kAIArtSuiteVersion19   AIAPI_VERSION(19)

#define kAIArtVersion   kAIArtSuiteVersion

---

Typedef Documentation

typedef struct _t_AICopyScopeOpaque* AICopyScopeHandle

Opaque handle to a copy scope.

---

Enumeration Type Documentation

enum AIArtBoundsOptions

Flags for AIArtSuite::GetArtTransformBounds() and AIArtSuite::GetArtRotatedBounds().

Note:

AIArtSuite::GetArtBounds() takes no flags, and has the same behavior as AIArtSuite::GetArtTransformBounds() with a null transform and kVisibleBounds|kExcludeGuideBounds. Call AIArtSuite::GetArtTransformBounds() with a null transform to specify non-default flags.

Enumerator:

kVisibleBounds	Default. Includes hidden and unpainted objects if they are not guides. Ignores direction handles.
kControlBounds	When off, kNoStrokeBounds, kNoExtendedBounds and kExcludeUnpaintedObjectBounds can be combined to ignore certain aspects of the visual bounds.
kNoStrokeBounds	Strokes, effects, and other appearance attributes that may make an object extend past the bezier outlines are ignored.
kNoExtendedBounds	Implies kNoStrokeBounds, but additionally excludes text characters for text on a path or area text, measuring only the path.
kWStrokeDependsOnPreference	Use the setting of the "Use Preview Bounds" user preference to control whether the strokes and other appearance attributes are included. Cannot be used together with kNoStrokeBounds (setting both results in kBadParameterErr).
kExcludeHiddenObjectBounds	Exclude hidden object. Can be set with kControlBounds or kVisibleBounds.
kExcludeUnpaintedObjectBounds	Excludes objects with no fill and no stroke.
kExcludeGuideBounds	Excludes guides. Can be set with kControlBounds or kVisibleBounds.

enum AIArtOrder

Return values from AIArtSuite::GetArtOrder().

The order in which art objects are encountered in a AIArtSuite::GetArtSibling() tree traversal. "Before" means above or in front in the paint order, and "After" means behind or below in the paint order.

Enumerator:

kUnknownOrder	null value
kFirstBeforeSecond	art1 is before art2
kSecondAfterFirst	art2 is after art1 (an alias for kFirstBeforeSecond).
kFirstAfterSecond	art1 is after art2
kSecondBeforeFirst	art2 is before art1 (an alias for kFirstAfterSecond).
kFirstInsideSecond	art1 is contained in art2
kSecondInsideFirst	art2 is contained in art1

enum AIArtTargettingAction

The values for the action parameter of AIArtSuite::ModifyTargetedArtSet().

Determines what action is taken to modify the current object set.

Enumerator:

kReplaceAction	Replaces current set with the set specified in list.
kAppendAction	Appends the set specified in list to current set.
kRemoveAction	Removes the set specified in list from the current set.
kUpAction	Moves targeting up one level (ignores list and count).
kDownAction	Moves targeting down one level (ignores list and count).
kDownToLeafAction	Moves targeting down to leaf level (ignores list and count).
kUpToLayersAction	Moves targeting up to layer level (ignores list and count).

enum AIArtTimeStampOptions

Enumerator:

kAITimeStampOfArt
kAITimeStampOfChildren
kAITimeStampMaxFromArtAndChildren

enum AIArtTransferAttrsOptions

Flags that specify which attributes are transferred by AIArtSuite::TransferAttributes().

These are the attributes that are common to all art objects.

Enumerator:

kTransferID	Transfer the unique ID, which is the name.
kTransferStyle	Transfer the style of the object.
kTransferOpacityMask	Transfer the opacity mask of the object. AIArtSuite::TransferAttributes(), when called with this option, will not remove the destination art's opacity mask if the source art does not have opacity mask.
kTransferTextWrapProperties	Transfer the text wrap properties--whether or not the object is a text wrap object together with the wrap offset and invert properties.
kTransferCompoundShapeMode	Transfer the compound shape mode used to combine the object geometry with others when it is a part of a compound shape.
kTransferSavedSelections	Transfer saved selections. This is information that describes the selection state for the object when a named selection is chosen from the "Select" menu. The information is a map from selection IDs to the corresponding selection state for the object. The selection state information can include information about specific parts of the object that are selected. This is not meaningful if the target object is not an identical copy of the original, but the function does not attempt to determine or deal with that case.
kTransferSlicingAttributes	Transfer slicing attributes, which define properties for exporting the object as a slice forming part of an HTML file; see the AISlicingSuite.
kTransferArtLocked	Transfer the locked attribute; see AIArtUserAttr.
kTransferArtHidden	Transfer the hidden attribute; see AIArtUserAttr.
kTransferSVGProperties	Transfer information imported from and exported to SVG files, which includes the SVG interactivity attributes.
kTransferLivePaintPathTags	Transfer tags that Live Paint uses to identify paths as being the "same". Use if one path or set of paths should replace an existing path (to distort it or scissor it, for example). Ignored if the destination art is not the same object type as the source art; for example, when the destination art is a group that expands the styled art of a path.
kTransferPixelPerfectAttribute	Transfers the Pixel Perfect property that makes an object align to pixel boundary. Use when you want to retain the pixel perfect property of the source art object in the destination art object.
kTransferLiveShapeProperties	Transfers live shape related information. Transferring these attributes does not guarantee that the destination object will be a live shape, it must fulfill shape-specific geometric constraints also.
kTransferAll	Transfer all object attributes. This causes all properties associated with the object in the current Illustrator version to be transferred, regardless of the API version a plug-in is built against.

enum AIArtType

Type constants for art objects.

Some values are only for use in matching and are never returned from AIArtSuite::GetArtType().

Enumerator:

kAnyArt	Special type never returned as an art object type, but used as a parameter to the Matching Art suite function AIMatchingArtSuite::GetMatchingArt().
kUnknownArt	Reserved for objects that are not supported in the plug-in interface. You should anticipate unknown art objects and ignore them gracefully. If a plug-in written for an earlier version of the plug-in API calls AIArtSuite::GetArtType() with an art object of a type unknown in its version, the function maps the type to either an appropriate type or to kUnknownArt.
kGroupArt	Art group.
kPathArt	Path art.
kCompoundPathArt	Compound path art.
kTextArtUnsupported	Pre-AI11 text art type; no longer supported but remains as a place holder so that the values for other art types remain the same.
kTextPathArtUnsupported	Pre-AI11 text art type; no longer supported but remains as a place holder so that the values for other art types remain the same.
kTextRunArtUnsupported	Pre-AI11 text art type; no longer supported but remains as a place holder so that the values for other art types remain the same.
kPlacedArt	Placed art.
kMysteryPathArt	Never returned as an art object type, it is an obsolete parameter to AIMatchingArtSuite::GetMatchingArt(). It was used to match paths inside text objects without matching the text objects themselves. In AI11 and later, use the kMatchTextPaths flag to return text paths.
kRasterArt	Raster art.
kPluginArt	Plug-in art.
kMeshArt	Mesh art.
kTextFrameArt	Text Frame art.
kSymbolArt	Symbol art.
kForeignArt	A foreign object, which is a "black box" containing drawing commands, constructed with AIForeignObjectSuite::New() rather than AIArtSuite::NewArt().
kLegacyTextArt	A text object read from a legacy file (AI10 or earlier).
kChartArt	Chart Art (Deprecated).

enum AIArtUserAttr

State selectors for AIArtSuite::GetArtUserAttr() and AIArtSuite::SetArtUserAttr(), and AIMatchingArtSuite functions such as AIMatchingArtSuite::GetMatchingArt().

Use for both whichAttr and attr parameters; for example, GetArtUserAttr(object, kArtHidden, kArtHidden), NOT GetArtUserAttr(object, kArtHidden, true).

Selection notes: Pass either kArtSelected or kArtFullySelected to AIArtSuite::SetArtUserAttr() to fully select an object, even if it is a container. To partially select a container, select individual descendants. To synchronize the container state before your plug-in returns, call AIDocumentSuite::RedrawDocument. Otherwise the container state is justified by Illustrator after the plug-in returns.

The selection attributes differ only for Get and Match operations, not for Set operations.

• kArtSelected is true for (and matches) partially selected containers, such as groups with some selected components, as well as partially selected paths.
• kArtFullySelected is true for paths only if all segments are selected, and for container objects (groups, compound paths, text objects, and so on) only if all descendants are selected.

The functions AIMatchingArtSuite::GetSelectedArt() and AIArtSetSuite::SelectedArtSet() are equivalent to using kArtSelected as the attribute selector.

Selection while matching: kArtSelectedTopLevelGroups, kArtSelectedLeaves, and kArtSelectedTopLevelWithPaint are used only with AIMatchingArtSuite::GetMatchingArt. These values cause an error in AIArtSuite::SetArtUserAttr(). They are mutually exclusive; you can specify only one, and they cannot be combined with other flags.

Enumerator:

kArtSelected	Object is selected; see also kArtFullySelected.
kArtLocked	Object is locked.
kArtHidden	Object is hidden.
kArtFullySelected	AI7 and later, distinguishes a container, such as a text path, that is fully selected from one where some contained parts are selected, but the container is not - for example, the path is selected but the text is not. In both cases, kArtSelected is on for both the container and the contained object, but if the text is not selected, this flag is off for the container. Pass either flag to AIArtSuite::SetArtUserAttr() to fully select any object, including a container.
kArtExpanded	The contents of the object are expanded in the layers palette; valid only for groups and plug-in groups.
kArtTargeted	Object is part of a targeted set; see AIArtSuite::ModifyTargetedArtSet().
kArtIsClipMask	Object defines a clip mask; this can only be set on paths, compound paths, and text frame objects, and only if the object is already contained within a clip group.
kArtIsTextWrap	Text wraps around the object. Cannot be set on an object that is part of compound group (returns kBadParameterErr). Set for the ancestor compound group instead.
kArtSelectedTopLevelGroups	Matches only fully selected top level objects and not their children; valid only for matching.
kArtSelectedLeaves	Matches only leaf selected objects and not their containers; valid only for matching; see also kArtSelectedTopLevelGroups.
kArtSelectedTopLevelWithPaint	Matches only top level selected objects that have a stroke or fill; valid only for matching; see also kArtSelectedTopLevelGroups.
kArtHasSimpleStyle	Object has a simple style. Valid only for AIArtSuite::GetArtUserAttr() and AIMatchingArtSuite::GetMatchingArt(). Causes an error in AIArtSuite::SetArtUserAttr().
kArtHasActiveStyle	True if the art object has an active style. Valid only for AIArtSuite::GetArtUserAttr() and AIMatchingArtSuite::GetMatchingArt(). Causes an error in AIArtSuite::SetArtUserAttr().
kArtPartOfCompound	Object is a part of a compound path. Valid only for AIArtSuite::GetArtUserAttr() and AIMatchingArtSuite::GetMatchingArt(). Causes an error in AIArtSuite::SetArtUserAttr().
kMatchDictionaryArt	Art object dictionaries are included in the search for matching art; valid only for matching.
kMatchArtInGraphs	Contents of graph objects are included in the search for matching art, valid only for matching.
kMatchArtInResultGroups	Result art of plug-in groups is included in the search for matching art; valid only for matching.
kMatchTextPaths	Defining paths of text frame objects are included in the search for matching art; valid only for matching.
kArtStyleIsDirty	In AIArtSuite::GetArtUserAttr(), reports whether the object has an art style that is pending re-execution. In AIArtSuite::SetArtUserAttr(), marks the art style dirty without making any other changes to the art or to the style.
kMatchArtNotIntoPluginGroups	Neither Edit Art Nor Result art of plug-in groups is included in the search for matching art; valid only for matching.
kMatchArtInCharts	Contents of graph objects are included in the search for matching art, valid only for matching.

enum AICopyScopeKind

The type of scope to create using AIArtSuite::CreateCopyScope().

Enumerator:

kAICopyScopeForDuplicate	Groups together a sequence of copy operations that corresponds to duplication of the copied objects within a single document.
kAICopyScopeForRetarget	Groups together a sequence of calls to AIPathStyleSuite::RetargetForCurrentDoc(). This is needed so that any decisions made about how to handle conflicts between global objects in the source and destination documents can apply to the entire set of objects being retargeted. For example, when there are global color name conflicts and the user chooses to apply their choice for handling one conflict (add or merge) to all future conflicts.
kDummyScopeKind	null value

enum AIDrawingMode

Type constants for drawing modes.

Enumerator:

kAIDrawNormalMode
kAIDrawBehindMode
kAIDrawInsideMode

enum AIPathPolarity

Enumerator:

kAIPolarPath
kAINonPolarPath