AIArtSuite Struct Reference
[API Suite List]

This suite allows you to access and modify the artwork in Illustrator documents. More...

#include <AIArt.h>

Public Attributes
AIAPI AIErr(*	NewArt )(ai::int16 type, ai::int16 paintOrder, AIArtHandle prep, AIArtHandle *newArt)
	Creates a new art object.
AIAPI AIErr(*	DisposeArt )(AIArtHandle art)
	Removes an art object from the document.
AIAPI AIErr(*	ReorderArt )(AIArtHandle thisArt, ai::int16 paintOrder, AIArtHandle prep)
	Changes the paint order of an art object, or moves a path in or out of a compound path or group.
AIAPI AIErr(*	DuplicateArt )(AIArtHandle thisArt, ai::int16 paintOrder, AIArtHandle prep, AIArtHandle *newArt)
	Duplicates an art object with a deep copy (children of groups and compound paths are also duplicated).
AIAPI AIErr(*	GetFirstArtOfLayer )(AILayerHandle layer, AIArtHandle *art)
	Retrieves the first art object in a layer, which is the group that contains all of the art in that layer.
AIAPI AIErr(*	GetLayerOfArt )(AIArtHandle art, AILayerHandle *layer)
	Retrieves an art object's parent layer, if any.
AIAPI AIErr(*	GetArtType )(AIArtHandle art, short *type)
	Retrieves the type of an art object.
AIAPI AIErr(*	GetArtUserAttr )(AIArtHandle art, ai::int32 whichAttr, ai::int32 *attr)
	Retrieves user attributes of an art object; that is, flags that show whether it is selected, hidden, or locked.
AIAPI AIErr(*	SetArtUserAttr )(AIArtHandle art, ai::int32 whichAttr, ai::int32 attr)
	Sets user attributes of an object; that is, flags that show whether it is selected, hidden, or locked.
AIAPI AIErr(*	GetArtParent )(AIArtHandle art, AIArtHandle *parent)
	Retrieves the parent group of an art object.
AIAPI AIErr(*	GetArtFirstChild )(AIArtHandle art, AIArtHandle *child)
	Retrieves the first child of a group object.
AIAPI AIErr(*	GetArtSibling )(AIArtHandle art, AIArtHandle *sibling)
	Retrieves the next object in the same group.
AIAPI AIErr(*	GetArtPriorSibling )(AIArtHandle art, AIArtHandle *sibling)
	Retrieves the previous object in the same group.
AIAPI AIErr(*	GetArtBounds )(AIArtHandle art, AIRealRect *bounds)
	Retrieves the enclosing rectangle of an art object.
AIAPI AIErr(*	SetArtBounds )(AIArtHandle art)
	Updates cached information for the enclosing rectangle (bounding box) of an art object.
AIAPI AIErr(*	GetArtCenterPointVisible )(AIArtHandle art, AIBoolean *visible)
	Checks whether the center point of an art object is visible.
AIAPI AIErr(*	SetArtCenterPointVisible )(AIArtHandle art, AIBoolean visible)
	Makes the center point of an art object visible or invisible when the object is selected.
AIAPI AIErr(*	GetArtTransformBounds )(AIArtHandle art, AIRealMatrix transform, ai::int32 flags, AIRealRect bounds)
	Retrieves the geometric bounds of an art object after applying a transformation matrix.
AIAPI AIErr(*	UpdateArtworkLink )(AIArtHandle art, AIBoolean force, AIBoolean *updated)
	Checks whether any linked objects (linked images or placed objects) contained in the subtree of a given container need updating, and updates them if needed.
AIAPI AIBoolean(*	ValidArt )(AIArtHandle art, AIBoolean searchAllLayerLists)
	Returns true if an art object reference is valid.
AIAPI AIErr(*	GetArtOrder )(AIArtHandle art1, AIArtHandle art2, short *order)
	Get the paint order or containment relation of two art objects.
AIAPI AIErr(*	SelectNamedArtOfLayer )(AILayerHandle layer, const ai::UnicodeString &name, AIBoolean matchWholeWord, AIBoolean caseSensitive)
	Selects specified artwork of a layer by matching a string to the contents of art object notes.
AIAPI AIErr(*	GetArtRotatedBounds )(AIArtHandle art, AIReal angle, ai::int32 flags, AIRealRect *bounds)
	Retrieves the enclosing rectangle of an art object after rotation.
AIAPI AIBoolean(*	ArtHasFill )(AIArtHandle art)
	Returns true if an art object or a descendent object draws something that should be considered a fill.
AIAPI AIBoolean(*	ArtHasStroke )(AIArtHandle art)
	Returns true if an art object or a descendent object draws something that should be considered a stroke.
AIAPI AIBoolean(*	ArtsHaveEqualPaths )(AIArtHandle art1, AIArtHandle art2)
	Returns true if two art objects contain nothing other than groups, paths and compound paths and they have identical geometry (control points).
AIAPI AIErr(*	ArtCopyFillStyleIfEqualPaths )(AIArtHandle dstArt, AIArtHandle srcArt)
	Not implemented in AI11 and later; returns `kNotImplementedErr`.
AIAPI AIErr(*	ArtCopyStrokeStyleIfEqualPaths )(AIArtHandle dstArt, AIArtHandle srcArt)
	Not implemented in AI11 and later; returns `kNotImplementedErr`.
AIAPI AIErr(*	GetInsertionPoint )(AIArtHandle art, short paintorder, AIBoolean *editable)
	Retrieves the insertion point for a document.
AIAPI AIErr(*	SetInsertionPoint )(AIArtHandle art)
	Sets the insertion point in a document.
AIAPI AIErr(*	GetKeyArt )(AIArtHandle *art)
	Retrieves the key object for object alignment.
AIAPI AIErr(*	CancelKeyArt )(void)
	Clears the key object for object alignment.
AIAPI AIErr(*	GetDictionary )(AIArtHandle art, struct _AIDictionary **dictionary)
	Retrieves the dictionary associated with an art object.
AIAPI AIBoolean(*	HasDictionary )(AIArtHandle art)
	Reports whether a dictionary is associated with an art object.
AIAPI AIBoolean(*	IsDictionaryEmpty )(AIArtHandle art)
	Reports whether the dictionary associated with an art object is empty or does not exist.
AIAPI AIErr(*	SetArtName )(AIArtHandle art, const ai::UnicodeString &name)
	Sets the name of an art object.
AIAPI AIErr(*	GetArtName )(AIArtHandle art, ai::UnicodeString &name, ASBoolean *isDefaultName)
	Retrieves the name of an art object.
AIAPI AIErr(*	IsArtLayerGroup )(AIArtHandle art, ASBoolean *isLayerGroup)
	Reports whether an art object is a group that corresponds to a layer or a sublayer.
AIAPI AIErr(*	ReleaseToLayers )(const AIArtHandle art, ASBoolean build)
	Releases elements of a layer, group, or plug-in group to separate layers.
AIAPI AIErr(*	ModifyTargetedArtSet )(AIArtHandle *list, ai::int32 count, ai::int32 action)
	Modifies the set of targeted objects in the document using a specified action.
AIAPI AIBoolean(*	IsArtStyledArt )(AIArtHandle art)
	Returns true if art is part of the styled art of another object.
AIAPI AIBoolean(*	IsArtClipping )(AIArtHandle art)
	Returns true if `art` adds to clipping.
AIAPI AIErr(*	TransferAttributes )(AIArtHandle srcart, AIArtHandle dstart, ai::uint32 which)
	Transfers attributes from a source art object to a destination art object.
AIAPI AIErr(*	GetArtLastChild )(AIArtHandle art, AIArtHandle *child)
	Retrieves the last child of a container art object.
AIAPI AIErr(*	SetArtTextWrapProperty )(AIArtHandle art, AIReal offset, AIBoolean invert)
	Sets the properties that affect how text wraps around a text wrap object; that is, one in which the `kArtIsTextWrap` attribute is set.
AIAPI AIErr(*	GetArtTextWrapProperty )(AIArtHandle art, AIReal offset, AIBoolean invert)
	Retrieves the properties that affect how text wraps around a text wrap object; that is, one in which the `kArtIsTextWrap` attribute is set.
AIAPI AIErr(*	CreateCopyScope )(enum AICopyScopeKind kind, AICopyScopeHandle *scope)
	Creates and instates a copy scope.
AIAPI AIErr(*	DestroyCopyScope )(AICopyScopeHandle scope)
	Uninstates and destroys a copy scope.
AIAPI AIErr(*	InsertionPointBadForArtType )(ai::int16 paintOrder, AIArtHandle prep, ai::int16 artType)
	Checks to see if it is OK to create or insert an art object of a given type at a given insertion point.
AIAPI AIErr(*	PreinsertionFlightCheck )(AIArtHandle candidateArt, ai::int16 paintOrder, AIArtHandle prep)
	Check to see if it is OK to insert an art object or a duplicate copy of it at the indicated insertion point, based on attributes of the insertion context and the candidate art, without actually attempting the insertion.
AIAPI AIErr(*	SetNote )(AIArtHandle art, const ai::UnicodeString &inNote)
	Sets the note attribute for an art object, which typically contains text entered by the user.
AIAPI AIErr(*	GetNote )(AIArtHandle art, ai::UnicodeString &outNote)
	Retrieves the note attribute text for an art object, which typically contains text entered by the user.
AIAPI AIBoolean(*	HasNote )(AIArtHandle art)
	Checks whether an art object has a note attached.
AIAPI void(*	DeleteNote )(AIArtHandle art)
	Deletes the note attached to an art object, if there is one.
AIAPI AIErr(*	GetArtXMPSize )(AIArtHandle art, size_t *size)
	Gets the size of the XMP metadata associated with an art object.
AIAPI AIErr(*	GetArtXMP )(AIArtHandle art, char *xmp, size_t size)
	Retrieves the XML packet associated with an art object's XMP metadata.
AIAPI AIErr(*	SetArtXMP )(AIArtHandle art, const char *xmp)
	Sets XMP metadata for an art object, replacing any existing data.
AIAPI AIErr(*	GetPreciseArtTransformBounds )(AIArtHandle art, AIRealMatrix transform, ai::int32 flags, AIDoubleRect bounds)
	Retrieves the geometric bounds of an art object after applying a transformation matrix.
AIAPI AIErr(*	UncheckedDisposeArt )(AIArtHandle art)
	Removes an art object from the art tree, performing minimal checks for validity of the input in order to maximize performance.
AIAPI AIErr(*	ArtIsGraph )(AIArtHandle art, AIBoolean *artisgraph)
	Reports whether an art object is a graph object type.
AIAPI AIErr(*	SetKeyArt )(AIArtHandle art)
	Sets the art as KeyArt for object alignment.
AIAPI AIErr(*	GetDrawingMode )(ai::int32 *mode)
	Retrieves the drawing mode for current document.
AIAPI AIErr(*	SetDrawingMode )(ai::int32 mode)
	Sets the drawing mode for current document.
AIAPI AIErr(*	GetInsertionPointForDrawingMode )(ai::int32 mode, AIArtHandle art, short paintorder, AIBoolean *editable)
	Retrieves the insertion point for current document based on the drawing mode.
AIAPI AIErr(*	GetInsertionPointForCurrentDrawingMode )(AIArtHandle art, short paintorder, AIBoolean *editable)
	Retrieves the insertion point for current document based on the current drawing mode.
AIAPI AIErr(*	GetPathPolarity )(AIArtHandle art, ai::int32 *polarity)
	Retrieves the path polarity of an art object.
AIAPI AIBoolean(*	IsPixelPerfect )(AIArtHandle art)
	Reports whether an art object is in pixel-perfect mode.
AIAPI AIErr(*	SetPixelPerfect )(AIArtHandle art, AIBoolean isPixelPerfect)
	Turns the pixel-perfect mode on or off for an art object.
AIAPI AIBoolean(*	ObjectsAreEquivalent )(AIArtHandle art1, AIArtHandle art2)
	Compare two art objects to determine if they are equivalent in geometry, appearance attributes, and dictionary contents.
AIAPI AIErr(*	IsArtALayerInSymbol )(AIArtHandle art, AIBoolean *isLayerInSymbol)
	Reports whether an art object acts as a layer within a symbol pattern.
AIAPI AIErr(*	GetArtTimeStamp )(AIArtHandle art, enum AIArtTimeStampOptions option, size_t *timeStamp)
	Retrieves the modification time stamp for an art object.
AIAPI size_t(*	GetGlobalTimeStamp )()
AIAPI AIErr(*	ConvertPointTypeToAreaType )(AIArtHandle art, AIArtHandle *newArtHandle)
AIAPI AIErr(*	ConvertAreaTypeToPointType )(AIArtHandle art, AIArtHandle *newArtHandle)
AIAPI AIErr(*	MarkDirty )(AIArtHandle art)
	Marks an art object for redraw by incrementing the modification time stamp.

Detailed Description

This suite allows you to access and modify the artwork in Illustrator documents.

It provides functions to create and delete objects, rearrange objects, and get and set information about objects. You use these functions to navigate the tree of art objects, and to retrieve or modify generic information about art objects, such as their bounds or lock status.

The Art suite is fundamental to implementing most plug-ins. An Illustrator document consists of a collection of art objects referenced by an AIArtHandle. This is an opaque pointer to an art object in the document's artwork database. Access the fields through the Art suite's accessor functions.

An art object can represent an individual entity, such as a path, block of text or placed image, or a group of objects, such as a collection of paths. The art type identifier (AIArtType) indicates the type of an art object.

Acquire this suite using SPBasicSuite::AcquireSuite() with the constants kAIArtSuite and kAIArtVersion.

Member Data Documentation

AIAPI AIErr(* AIArtSuite::ArtCopyFillStyleIfEqualPaths)(AIArtHandle dstArt, AIArtHandle srcArt)

Not implemented in AI11 and later; returns kNotImplementedErr.

AIAPI AIErr(* AIArtSuite::ArtCopyStrokeStyleIfEqualPaths)(AIArtHandle dstArt, AIArtHandle srcArt)

Not implemented in AI11 and later; returns kNotImplementedErr.

AIAPI AIBoolean(* AIArtSuite::ArtHasFill)(AIArtHandle art)

Returns true if an art object or a descendent object draws something that should be considered a fill.

The distinguishing property of a fill is that it is drawn behind all other objects when applied to an object that is part of a clipping mask. (Note that the function returns a boolean value, not an error code.)

Parameters:

art

The art object.

Returns:: True if the object or a descendant has fill.

AIAPI AIBoolean(* AIArtSuite::ArtHasStroke)(AIArtHandle art)

Returns true if an art object or a descendent object draws something that should be considered a stroke.

The distinguishing property of a stroke is that it is drawn in front of all other objects when applied to an object that is part of a clipping mask. (Note that the function returns a boolean value, not an error code.)

Parameters:

art

The art object.

Returns:: True if the object or a descendant has stroke.

AIAPI AIErr(* AIArtSuite::ArtIsGraph)(AIArtHandle art, AIBoolean *artisgraph)

Reports whether an art object is a graph object type.

Graphs (for historical reasons) have no specific art type in AIArtType enum, and get the type kUnknownArt.

Parameters:

	art	The art object to query.
	artisgraph	[out] A buffer in which to return the output as true if the object is a graph.

AIAPI AIBoolean(* AIArtSuite::ArtsHaveEqualPaths)(AIArtHandle art1, AIArtHandle art2)

Returns true if two art objects contain nothing other than groups, paths and compound paths and they have identical geometry (control points).

The path styles and other appearance attributes may be different. (Note that the function returns a boolean value, not an error code.)

Parameters:

	art1	The first art object.
	art2	The second art object.

Returns:: True if the objects have equal paths.

See also:: also ObjectsAreEquivalent

AIAPI AIErr(* AIArtSuite::CancelKeyArt)(void)

Clears the key object for object alignment.

The key object is the one to which other objects are aligned. It is usually the object that is most recently clicked using the Selection tool.

Deprecated:

AIAPI AIErr(* AIArtSuite::ConvertAreaTypeToPointType)(AIArtHandle art, AIArtHandle *newArtHandle)

AIAPI AIErr(* AIArtSuite::ConvertPointTypeToAreaType)(AIArtHandle art, AIArtHandle *newArtHandle)

AIAPI AIErr(* AIArtSuite::CreateCopyScope)(enum AICopyScopeKind kind, AICopyScopeHandle *scope)

Creates and instates a copy scope.

Scopes are reference counted. You must use DestroyCopyScope to release the reference when it is no longer needed. It is recommended that you use the C++ wrapper ai::CopyScope, which takes care of memory management.

Parameters:

	kind	The type of scope to create, an `AICopyScopeKind` value.
	scope	[out] A buffer in which to return the new scope reference.

AIAPI void(* AIArtSuite::DeleteNote)(AIArtHandle art)

Deletes the note attached to an art object, if there is one.

No error code is returned.

Parameters:

art

The art object.

AIAPI AIErr(* AIArtSuite::DestroyCopyScope)(AICopyScopeHandle scope)

Uninstates and destroys a copy scope.

It is recommended that you use the C++ wrapper ai::CopyScope, which takes care of memory management.

Parameters:

scope The scope reference, as returned by CreateCopyScope().

AIAPI AIErr(* AIArtSuite::DisposeArt)(AIArtHandle art)

Removes an art object from the document.

If it is a group or compound path, also removes its children.

Parameters:

art

The art object. After the call, this reference is no longer valid.

AIAPI AIErr(* AIArtSuite::DuplicateArt)(AIArtHandle thisArt, ai::int16 paintOrder, AIArtHandle prep, AIArtHandle *newArt)

Duplicates an art object with a deep copy (children of groups and compound paths are also duplicated).

The copied objects have the same coordinates as the original, so you must do a deep move on them.

Parameters:

	art	The art object.
	paintOrder	The paint order, relative to the `prep` object. See `AITypes::AIPaintOrder`.
	prep	The prepositional art object for the paint order.
	newArt	[out] A buffer in which to return the new art object.

AIAPI AIErr(* AIArtSuite::GetArtBounds)(AIArtHandle art, AIRealRect *bounds)

Retrieves the enclosing rectangle of an art object.

Parameters:

	art	The art object.
	bounds	[out] A buffer in which to return the value.

Note:: This function has the same behavior as GetArtTransformBounds() with a null transform and kVisibleBounds|kExcludeGuideBounds. Call GetArtTransformBounds() with a null transform to specify non-default flags.

AIAPI AIErr(* AIArtSuite::GetArtCenterPointVisible)(AIArtHandle art, AIBoolean *visible)

Checks whether the center point of an art object is visible.

This option can be set by the user using the Attributes dialog.
Example:

error = sArt->GetArtCenterPointVisible (art, &visible);
if (error) return error;
if (!visible) {
    // its not visible so we do something based on that fact
    ...

Parameters:

	art	The art object.
	visible	[out] A buffer in which to return the value, true if the center point is visible.

AIAPI AIErr(* AIArtSuite::GetArtFirstChild)(AIArtHandle art, AIArtHandle *child)

Retrieves the first child of a group object.

For example:

AIArtHandle child;
...
error = sArt->GetArtType(art, &type);
if (error) return error;
switch (type) {
    case kGroupArt:
    error = sArt->GetArtFirstChild(art, &child);
    if (error) return error;
    error = doArtAndSiblings(message, child);
    if (error) return error;
    break;
    ...

Parameters:

	art	The art object.
	child	[out] A buffer in which to return the child object, or a null object if the specified art object is not a container such as a group, a graph, or a text frame, or is an empty container.

AIAPI AIErr(* AIArtSuite::GetArtLastChild)(AIArtHandle art, AIArtHandle *child)

Retrieves the last child of a container art object.

Applies to container objects such as groups, graphs and text frame objects.

Parameters:

	art	The art object.
	child	[out] A buffer in which to return the last child art object, or nil if the specified art object is not a container or is an empty container.

AIAPI AIErr(* AIArtSuite::GetArtName)(AIArtHandle art, ai::UnicodeString &name, ASBoolean *isDefaultName)

Retrieves the name of an art object.

This is the name that appears in the Layers palette.

Parameters:

	art	The art object.
	name	[out] A buffer in which to return the name.
	isDefaultName	[out] A buffer in which to return the output as true if the returned name is a default descriptive name, rather than a user-assigned name. May be null.

AIAPI AIErr(* AIArtSuite::GetArtOrder)(AIArtHandle art1, AIArtHandle art2, short *order)

Get the paint order or containment relation of two art objects.

This function reflects the order in which the objects are encountered in a GetArtSibling() tree traversal. "Before" means above or in front in the paint order, and "After" means behind or below in the paint order.

Parameters:

	art1	The first art object.
	art2	The second art object.
	order	[out] A buffer in which to return the result. See `AIArtOrder` for the possible ordering values.

AIAPI AIErr(* AIArtSuite::GetArtParent)(AIArtHandle art, AIArtHandle *parent)

Retrieves the parent group of an art object.

This example shows a non-recursive tree walk:

...
// see if parent has sibling
error = sArt->GetArtParent(nextart, &nextart);
if (error) return error;
error = sArt->GetArtSibling(nextart, &nextart);
if (error) return error;
if (nextart) {  // parent has sibling
...
}

Parameters:

	art	The art object.
	parent	[out] A buffer in which to return the parent object, or a null object if the specified art object is the topmost group of its layer, or the topmost object in a container such as a dictionary or array.\

AIAPI AIErr(* AIArtSuite::GetArtPriorSibling)(AIArtHandle art, AIArtHandle *sibling)

Retrieves the previous object in the same group.

This is the opposite of GetArtSibling().
Example:

// get the previous art
error = sArt->GetArtPriorSibling(art, &art);
if (error) return error;
if (!art){
        // art was first in group
        // see if parent has previous art
        error = sArt->GetArtParent(art, &art);
        if (error) return error;
        ...

Parameters:

	art	The art object.
	sibling	[out] A buffer in which to return the sibling objector a null object if the specified art object is the first child in its container.

AIAPI AIErr(* AIArtSuite::GetArtRotatedBounds)(AIArtHandle art, AIReal angle, ai::int32 flags, AIRealRect *bounds)

Retrieves the enclosing rectangle of an art object after rotation.

This is the same as GetArtTransformBounds(), except that the transformation is specified by a rotation angle rather than a matrix.

Parameters:

	art	The art object.
	angle	The rotation angle in radians.
	flags	Option flags for which bounds to return. A logical OR of `AIArtBoundsOptions` constant values.
	bounds	[out] A buffer in which to return the value.

AIAPI AIErr(* AIArtSuite::GetArtSibling)(AIArtHandle art, AIArtHandle *sibling)

Retrieves the next object in the same group.

This is the opposite of GetArtPriorSibling(). Use with GetArtFirstChild() and GetArtParent() to look at all of the objects in a container. For example:

...
// see if parent has sibling
error = sArt->GetArtParent(nextart, &nextart);
if (error) return error;
error = sArt->GetArtSibling(nextart, &nextart);
if (error) return error;
if (nextart) {    // parent has sibling
...
}

Parameters:

	art	The art object.
	sibling	[out] A buffer in which to return the sibling object, or a null object if the specified art object is the last child in its container.

AIAPI AIErr(* AIArtSuite::GetArtTextWrapProperty)(AIArtHandle art, AIReal *offset, AIBoolean *invert)

Retrieves the properties that affect how text wraps around a text wrap object; that is, one in which the kArtIsTextWrap attribute is set.

Use GetArtUserAttr() and SetArtUserAttr() to inspect and set the kArtIsTextWrap attribute.

Parameters:

	art	The art object.
	offset	[out] A buffer in which to return the distance in points from the geometric outline of an object that defines an offset for wrapping.
	invert	[out] A buffer in which to return the output as true if text wraps inside the outline of the offset object, or false if text wraps around the outside of the offset object.

Returns:: kBadParameterErr if the object does not have the kArtIsTextWrap attribute set.

AIAPI AIErr(* AIArtSuite::GetArtTimeStamp)(AIArtHandle art, enum AIArtTimeStampOptions option, size_t *timeStamp)

Retrieves the modification time stamp for an art object.

Parameters:

	art	[in] The art object
	option	[in] The type of timeStamp to get, an `AIArtTimeStampOptions` value.
	timeStamp	[out] A buffer in which to return the modification time stamp.

AIAPI AIErr(* AIArtSuite::GetArtTransformBounds)(AIArtHandle art, AIRealMatrix *transform, ai::int32 flags, AIRealRect *bounds)

Retrieves the geometric bounds of an art object after applying a transformation matrix.

Returns single-precision coordinates.

Parameters:

	art	The art object.
	transform	A pointer to a transformation matrix to apply. Can be `NULL` to indicate the identity matrix. You cannot use a non-null matrix if the `kControlBounds` option is set in `flags`.
	flags	Bit flags that specify which bounds to return. A logical OR of `AIArtBoundsOptions` constants. The flags must include either `kVisibleBounds` or `kControlBounds`, and can include additional flags depending on which of these is included.
	bounds	[out] A buffer in which to return the bounds value containing single-precision coordinates.

See also:: GetPreciseArtTransformBounds(), GetArtRotatedBounds()

AIAPI AIErr(* AIArtSuite::GetArtType)(AIArtHandle art, short *type)

Retrieves the type of an art object.

Before you begin manipulating an object's type-specific attributes you need to know what kind of art object it is. For example, you can call path functions if the art is a path, or text functions if it is text.

short type;
error = sArt->GetArtType(art, &type);
if (error)
    return error;
switch (type) {
    case kGroupArt:
    ...
}

Parameters:

	art	The art object.
	type	[out] A buffer in which to return the type, an `AIArtType` constant.

AIAPI AIErr(* AIArtSuite::GetArtUserAttr)(AIArtHandle art, ai::int32 whichAttr, ai::int32 *attr)

Retrieves user attributes of an art object; that is, flags that show whether it is selected, hidden, or locked.

The user attributes of an object do not directly affect the geometry or printing of the artwork. They are temporary and primarily used while the user is editing the document. An art object must be unlocked before making changes to it through the API. Unlocking and locking should therefore be the first and last things done to an object. An object cannot be selected if it is hidden or locked. Because most filters operate on the current selection, it is not usually not necessary to unlock objects.

Example:

long attr;
error = sArt->GetArtUserAttr(art, kArtLocked | kArtHidden, &attributes);
if (error) return error;
if (!(attributes & kArtLocked) || !(attributes & kArtHidden)) {
  error = sArt->SetArtUserAttr(art, kArtSelected, kArtSelected);
  if (error) return error;
}

Parameters:

	art	The art object.
	whichAttr	A mask for the attributes of interest, a logical OR of `AIArtType` constant values.
	attr	[out] A buffer in which to return the type, a logical OR of `AIArtType` constant values, masked by `whichAttr`. (Note that this is NOT boolean).

See also:: GetArtTextWrapProperty(), SetArtTextWrapProperty()

AIAPI AIErr(* AIArtSuite::GetArtXMP)(AIArtHandle art, char *xmp, size_t size)

Retrieves the XML packet associated with an art object's XMP metadata.

The format is UTF-8 Unicode.

Parameters:

	art	The art object.
	xmp	[out] A buffer in which to return the XML packet. Allocate a buffer using `GetArtXMPSize()`.
	size	The number of bytes in the `xmp` buffer.

AIAPI AIErr(* AIArtSuite::GetArtXMPSize)(AIArtHandle art, size_t *size)

Gets the size of the XMP metadata associated with an art object.

Parameters:

	art	The art object.
	size	[out] A buffer in which to return the number of bytes, or 0 if there is no XMP metadata.

AIAPI AIErr(* AIArtSuite::GetDictionary)(AIArtHandle art, struct _AIDictionary **dictionary)

Retrieves the dictionary associated with an art object.

Creates a new, empty dictionary if one is not found.

Arbitrary data can be attached to an art object in its dictionary. See the AIDictionarySuite. The same dictionary is accessed by the AITagSuite for setting and getting string values.

Dictionaries are reference counted. You must call sAIDictionary->Release() when you no longer need the reference. It is recommended that you use the C++ ai::Ref template class, which takes care memory management.

Parameters:

	art	The art object.
	dictionary	[out] A buffer in which to return a pointer to the dictionary reference.

Note:: This call creates an empty dictionary if one is not found. To check for the existence of an item in the art dictionary, first check that the dictionary exists and is not empty.

See also:: IsDictionaryEmpty() and HasDictionary()

AIAPI AIErr(* AIArtSuite::GetDrawingMode)(ai::int32 *mode)

Retrieves the drawing mode for current document.

Parameters:

mode [out] A buffer in which to return the drawing mode, an AIDrawingMode constant.

AIAPI AIErr(* AIArtSuite::GetFirstArtOfLayer)(AILayerHandle layer, AIArtHandle *art)

Retrieves the first art object in a layer, which is the group that contains all of the art in that layer.

You can use this to traverse the art objects contained in the layer.

Parameters:

	layer	The layer. Use `nil` for the current layer. See `AILayerSuite`
	art	[out] A buffer in which to return the new art object.

See also:: GetArtFirstChild(), GetArtParent(), GetArtSibling(), GetArtPriorSibling()

AIAPI size_t(* AIArtSuite::GetGlobalTimeStamp)()

AIAPI AIErr(* AIArtSuite::GetInsertionPoint)(AIArtHandle *art, short *paintorder, AIBoolean *editable)

Retrieves the insertion point for a document.

This is the position in the art tree at which a drawing tool should create new art.

Parameters:

	art	The art object.
	paintorder	The position in the paint order, relative to the specified art object. See `AITypes::AIPaintOrder` for the possible positions.
	editable	[out] A buffer in which to return the output as true if it is possible to create art at the returned position. For example, you cannot create art in a locked layer. Pass null if not needed.

AIAPI AIErr(* AIArtSuite::GetInsertionPointForCurrentDrawingMode)(AIArtHandle *art, short *paintorder, AIBoolean *editable)

Retrieves the insertion point for current document based on the current drawing mode.

This is the position in the art tree at which a drawing tool should create new art.

Parameters:

	art	[out] The art object.
	paintorder	[out] The position in the paint order, relative to the specified art object. See `AITypes::AIPaintOrder` for the possible positions.
	editable	[out] A buffer in which to return the output as true if it is possible to create art at the returned position. For example, you cannot create art in a locked layer. Pass null if not needed.

AIAPI AIErr(* AIArtSuite::GetInsertionPointForDrawingMode)(ai::int32 mode, AIArtHandle *art, short *paintorder, AIBoolean *editable)

Retrieves the insertion point for current document based on the drawing mode.

This is the position in the art tree at which a drawing tool should create new art.

Parameters:

	mode	[in] The drawing mode, an `AIDrawingMode` constant.
	art	[out] The art object.
	paintorder	[out] The position in the paint order, relative to the specified art object. See `AITypes::AIPaintOrder` for the possible positions.
	editable	[out] A buffer in which to return the output as true if it is possible to create art at the returned position. For example, you cannot create art in a locked layer. Pass null if not needed.

AIAPI AIErr(* AIArtSuite::GetKeyArt)(AIArtHandle *art)

Retrieves the key object for object alignment.

The key object is the one to which other objects are aligned. It is usually the object most recently clicked with the Select tool.

Parameters:

art

[out] A buffer in which to return the art object, or a null object if there is no key object.

AIAPI AIErr(* AIArtSuite::GetLayerOfArt)(AIArtHandle art, AILayerHandle *layer)

Retrieves an art object's parent layer, if any.

This function is useful with AIMatchingArtSuite::GetSelectedArt() and AIMatchingArtSuite::GetMatchingArt(), which give you a list of art objects. For example, if your filter gets all of the selected objects and creates a path on top of each layer with objects on it, you would need to know the layer of the objects in order to place the new path on top:

AILayerHandle layer;
AIArtHandle group, new_path;
error = sArt->GetLayerOfArt(art, &layer);
error = sArt->GetFirstArtOfLayer(layer, &group);
error = sArt->NewArt(kPathArt, kPlaceInsideOnTop, group, &new_path);

Parameters:

	art	The art object.
	layer	[out] A buffer in which to return the layer object. See `AILayerSuite`

Note:: Art that is stored in a dictionary or an array is not considered to be on a layer even though the dictionary may belong to an art object that is on a layer.

AIAPI AIErr(* AIArtSuite::GetNote)(AIArtHandle art, ai::UnicodeString &outNote)

Retrieves the note attribute text for an art object, which typically contains text entered by the user.

Parameters:

	art	The art object
	outNote	[out] A buffer in which to return the contents of the note. Returns an empty string if the art object has no note.

See also:: SetNote()

AIAPI AIErr(* AIArtSuite::GetPathPolarity)(AIArtHandle art, ai::int32 *polarity)

Retrieves the path polarity of an art object.

Parameters:

	art	The art object.
	polarity	[out] A buffer in which to return the polarity value. Value of polarity is set to `kAIPolarPath` or `kAINonPolarPath`.

AIAPI AIErr(* AIArtSuite::GetPreciseArtTransformBounds)(AIArtHandle art, AIRealMatrix *transform, ai::int32 flags, AIDoubleRect *bounds)

Retrieves the geometric bounds of an art object after applying a transformation matrix.

Returns double-precision coordinates.

Parameters:

	art	The art object.
	transform	A pointer to a transformation matrix to apply.
	flags	Bit flags that specify which bounds to return. A logical OR of `AIArtBoundsOptions` constants. The flags must include either `kVisibleBounds` or `kControlBounds`, and can include additional flags depending on which of these is included.
	bounds	[out] A buffer in which to return the bounds value, containing double-precision coordinates.

See also:: GetArtTransformBounds()

AIAPI AIBoolean(* AIArtSuite::HasDictionary)(AIArtHandle art)

Reports whether a dictionary is associated with an art object.

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

Parameters:

art

The art object.

Returns:: True if a dictionary is associated with the art object, false otherwise.

Note:: If you need to check for the existence of an item in the art dictionary, first check that the dictionary exists and is not empty. Calling GetDictionary() when no dictionary exists creates an unneeded dictionary object.

See also:: IsDictionaryEmpty() and GetDictionary()

AIAPI AIBoolean(* AIArtSuite::HasNote)(AIArtHandle art)

Checks whether an art object has a note attached.

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

Parameters:

art

The art object.

Returns:: True if there is a note attached.

AIAPI AIErr(* AIArtSuite::InsertionPointBadForArtType)(ai::int16 paintOrder, AIArtHandle prep, ai::int16 artType)

Checks to see if it is OK to create or insert an art object of a given type at a given insertion point.

Parameters:

	paintOrder	The insertion point in the paint order, relative to the `prep` object. See `AITypes::AIPaintOrder`.
	prep	The prepositional art object for the paint order.
	artType	The type of art object, an `AIArtType` value.

Returns:: kNoErr if it is OK, and kInvalidArtTypeForDestErr if it is not.

AIAPI AIErr(* AIArtSuite::IsArtALayerInSymbol)(AIArtHandle art, AIBoolean *isLayerInSymbol)

Reports whether an art object acts as a layer within a symbol pattern.

This is a simulated layer that functions as a group, except when isolated or expanded. It is not a layer object and cannot be manipulated with the AILayerSuite.

Parameters:

	art	[in] The art object
	isLayerInSymbol	[out] A buffer in which to return the output as true if this is a simulated layer in a symbol pattern; false otherwise.

AIAPI AIBoolean(* AIArtSuite::IsArtClipping)(AIArtHandle art)

Returns true if art adds to clipping.

(Note that the function returns a boolean value, not an error code.) Call this function only on descendents of a clip group or a mask object.

Parameters:

art

The art object.

Returns:: True if the specified object is an appropriate art object with the kArtIsClipMask flag set, or if it is a non-clip group with a clipping descendent that is not bounded by another clip group.

AIAPI AIErr(* AIArtSuite::IsArtLayerGroup)(AIArtHandle art, ASBoolean *isLayerGroup)

Reports whether an art object is a group that corresponds to a layer or a sublayer.

Parameters:

	art	The art object.
	name	[out] A buffer in which to return true if the art object is a layer group.

AIAPI AIBoolean(* AIArtSuite::IsArtStyledArt)(AIArtHandle art)

Returns true if art is part of the styled art of another object.

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

Parameters:

art

The art object;

Returns:: True if the object is part of the style art of another object.

AIAPI AIBoolean(* AIArtSuite::IsDictionaryEmpty)(AIArtHandle art)

Reports whether the dictionary associated with an art object is empty or does not exist.

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

Parameters:

art

The art object.

Returns:: True if a dictionary exists and is empty or if no dictionary exists. False if a dictionary associated with the art object contains any entries.

Note:: For best performance, check for existence of a dictionary before calling GetDictionary(). Calling GetDictionary() when no dictionary exists creates an unneeded dictionary object.

See also:: HasDictionary() and GetDictionary()

AIAPI AIBoolean(* AIArtSuite::IsPixelPerfect)(AIArtHandle art)

Reports whether an art object is in pixel-perfect mode.

Parameters:

art

[in]: The art object Note that this API returns a boolean value and not an error.

Returns:: True of the pixel-perfect property is on, false if it is off.

AIAPI AIErr(* AIArtSuite::MarkDirty)(AIArtHandle art)

Marks an art object for redraw by incrementing the modification time stamp.

Parameters:

art

The art object.

AIAPI AIErr(* AIArtSuite::ModifyTargetedArtSet)(AIArtHandle *list, ai::int32 count, ai::int32 action)

Modifies the set of targeted objects in the document using a specified action.

Parameters:

	list	A set of objects to be used as an additional parameter, for actions that need it.
	count	The number of objects in `list`.
	action	The action to take; see `AIArtTargettingAction` for the possible actions.

AIAPI AIErr(* AIArtSuite::NewArt)(ai::int16 type, ai::int16 paintOrder, AIArtHandle prep, AIArtHandle *newArt)

Creates a new art object.

This can fail if the layer is locked or hidden. Otherwise, the object is inserted into the paint order with respect another art object. For example, this creates new_art above old_art in the paint order.

AIArtHandle new_art;
error = sArt->NewArt(kPathArt, kPlaceAbove, old_art, &new_art);

This places new_art in the specified group above all other objects in the group.

error = sArt->NewArt(kPathArt, kPlaceInsideOnTop, group, &new_art);

This places new_art on top of all artwork in the document.

error = sArt->NewArt(kPathArt, kPlaceAboveAll, nil, &new_art);

Parameters:

	type	The art type. See `AIArtType`. If the new object type is a path then it is typically given the path style that would be assigned to a path created by a tool (for example, the pen tool). Tool plug-ins can depend on this. Plug-ins that are not tools should make no assumptions about the style assigned to paths.
	paintOrder	The paint order position, relative to the `prep` object, an `AITypes::AIPaintOrder` value.
	prep	The prepositional art object. This can be an object whose boundaries might overlap this one, or a compound path or group that might contain this path.
	newArt	[out] A buffer in which to return the new art object.

Note:: Change in AI 11.0: If the art is being created during the execution of an effect, and prep is styled art, the new art has a path style with a black fill and no stroke. This prevents effect executions from accidentally using the current path style

AIAPI AIBoolean(* AIArtSuite::ObjectsAreEquivalent)(AIArtHandle art1, AIArtHandle art2)

Compare two art objects to determine if they are equivalent in geometry, appearance attributes, and dictionary contents.

Typically, one object is in the current document and the other is in another document. This function uses the same sense of equivalence in which two patterns or symbol definitions are considered equivalent when retargeting an external symbol or pattern to the current document. In particular, if one object is in a document with a different color mode than the other, then non-global process colors are converted to the color mode of the first object before comparison, and named global objects are considered equivalent if the definitions match and the names are equal except for trailing numerical suffixes. (Note that this function returns a Boolean value, not an error code.)

Parameters:

	art1	The first art object.
	art2The	second art object.

Returns:: True if the objects are equivalent, false otherwise.

See also:: AISymbolSuite::RetargetForCurrentDocument() and AIPathStyleSuite::RetargetForCurrentDoc()

AIAPI AIErr(* AIArtSuite::PreinsertionFlightCheck)(AIArtHandle candidateArt, ai::int16 paintOrder, AIArtHandle prep)

Check to see if it is OK to insert an art object or a duplicate copy of it at the indicated insertion point, based on attributes of the insertion context and the candidate art, without actually attempting the insertion.

This is mainly intended for use during drag-drop mouseover, to give proper cursor feedback, and so that an insertion is not attempted if it will fail.

Parameters:

	candidateArt	The art object to test.
	paintOrder	The position for the insertion point, with respect to `prep`, an `AITypes::AIPaintOrder` value.
	prep	The prepositional object for the `paintOrder` position.

Returns:: kNoErr if it is OK. Possible non-OK returns are kTooDeepNestingErr, kInvalidArtTypeForDestErr, and kUntouchableArtObjectErr.

AIAPI AIErr(* AIArtSuite::ReleaseToLayers)(const AIArtHandle art, ASBoolean build)

Releases elements of a layer, group, or plug-in group to separate layers.

Plug-in groups can be inside styled art. In this case:

If the art style consists of only the plug-in group, the plug-in group is expanded and the original art deleted.
If there is more than one plug-in group or other element in the styled art, the specified art is left in place and the remaining styled art is left intact.

Parameters:

	art	The art object.
	build	When true, new layers are built upon one another such that the topmost released layer contains everything in the original art and the bottommost released layer contains only the highest object in the stacking order. This order is used because the Flash exporter takes the bottommost layer as the first animation frame and the topmost layer as the last frame.

AIAPI AIErr(* AIArtSuite::ReorderArt)(AIArtHandle thisArt, ai::int16 paintOrder, AIArtHandle prep)

Changes the paint order of an art object, or moves a path in or out of a compound path or group.

Parameters:

	art	The art object.
	paintOrder	The paint order, relative to the `prep` object, an `AITypes::AIPaintOrder` value.
	prep	The prepositional art object for the paint order.

AIAPI AIErr(* AIArtSuite::SelectNamedArtOfLayer)(AILayerHandle layer, const ai::UnicodeString &name, AIBoolean matchWholeWord, AIBoolean caseSensitive)

Selects specified artwork of a layer by matching a string to the contents of art object notes.

You can select multiple art objects by specifying a partial string and a matching style.

Parameters:

	layer	The layer object. See `AILayerSuite`.
	name	A string to match to the note contents of art objects in the layer. If the empty string, matches all leaf objects without notes.
	matchWholeWord	When true, an art object is selected if its note contents exactly matches the `name` string. When false, an art object is selected if any part of its note contents matches the `name` string.
	caseSensitive	When true, perform case-sensitive matching. When false, ignore case.

AIAPI AIErr(* AIArtSuite::SetArtBounds)(AIArtHandle art)

Updates cached information for the enclosing rectangle (bounding box) of an art object.

Parameters:

art

The art object.

AIAPI AIErr(* AIArtSuite::SetArtCenterPointVisible)(AIArtHandle art, AIBoolean visible)

Makes the center point of an art object visible or invisible when the object is selected.

Parameters:

	art	The art object.
	visible	True to make the center point visible, false to make it invisible.

AIAPI AIErr(* AIArtSuite::SetArtName)(AIArtHandle art, const ai::UnicodeString &name)

Sets the name of an art object.

This is the name that appears in the Layers palette.

Parameters:

	art	The art object.
	name	The new name. Use the empty string to reset the name to the default for the object type.

AIAPI AIErr(* AIArtSuite::SetArtTextWrapProperty)(AIArtHandle art, AIReal offset, AIBoolean invert)

Sets the properties that affect how text wraps around a text wrap object; that is, one in which the kArtIsTextWrap attribute is set.

Use GetArtUserAttr() and SetArtUserAttr() to inspect and set the kArtIsTextWrap attribute.

Parameters:

	art	The art object.
	offset	The distance in points from the geometric outline of an object that defines an offset for wrapping.
	invert	When true, text wraps inside the outline of the offset object. When false, text wraps around the outside of the offset object.

Returns:: kBadParameterErr if the object does not have the kArtIsTextWrap attribute set.

AIAPI AIErr(* AIArtSuite::SetArtUserAttr)(AIArtHandle art, ai::int32 whichAttr, ai::int32 attr)

Sets user attributes of an object; that is, flags that show whether it is selected, hidden, or locked.

Changing the selection state of an object is considered by the plug-in interface to be a modification to the document; that is, the document is marked dirty and needs to be saved.
Example:

// unlocks the object
error = sArt->SetArtUserAttr(art, kArtLocked, 0);
// locks the object
error = sArt->SetArtUserAttr(art, kArtLocked, kArtLocked);

Parameters:

	art	The art object.
	whichAttr	A mask for the attributes of interest, a logical OR of `AIArtType` constant values.
	attr	The new attribute value, a logical OR of `AIArtType` constant values, masked by `whichAttr`. (Note that this is NOT boolean).

See also:: GetArtTextWrapProperty(), SetArtTextWrapProperty()

AIAPI AIErr(* AIArtSuite::SetArtXMP)(AIArtHandle art, const char *xmp)

Sets XMP metadata for an art object, replacing any existing data.

Format must be UTF-8 Unicode.

Parameters:

	art	The art object.
	xmp	The new XML packet.Use a null XMP pointer or empty one to remove the existing metadata.

AIAPI AIErr(* AIArtSuite::SetDrawingMode)(ai::int32 mode)

Sets the drawing mode for current document.

Parameters:

mode [in] The drawing mode to be set for a document, an AIDrawingMode constant.

AIAPI AIErr(* AIArtSuite::SetInsertionPoint)(AIArtHandle art)

Sets the insertion point in a document.

This is the position in the art tree at which a drawing tool should create new art. The new position is a paint-order position with respect to the given art object. See AITypes::AIPaintOrder for details. If the object is a group, the new position is kPlaceInsideOnTop; otherwise it is kPlaceAbove. If the art object is in a position where an insertion point cannot be set (for example, inside a plug-in group) the position is set relative to the nearest parent defining a valid insertion point. If no valid insertion point can be determined, the function returns an error.

Parameters:

art

The art object.

AIAPI AIErr(* AIArtSuite::SetKeyArt)(AIArtHandle art)

Sets the art as KeyArt for object alignment.

The key object is the one to which other objects are aligned. If art is NULL, it cancels key art. Use this API to Cancel KeyArt instead of CancelKeyArt().

Parameters:

art

[in] The art object to be set as Key Art The art needs to be currently selected.

Returns:: an AIErr. In case of success returns kNoErr else give kBadParameterErr

See also:: GetKeyArt()

AIAPI AIErr(* AIArtSuite::SetNote)(AIArtHandle art, const ai::UnicodeString &inNote)

Sets the note attribute for an art object, which typically contains text entered by the user.

To attach private data to an art object, plug-ins should use the art dictionary interface (see GetDictionary()) rather than using the note.

Parameters:

	art	The art object.
	inNote	The new text for the note.

AIAPI AIErr(* AIArtSuite::SetPixelPerfect)(AIArtHandle art, AIBoolean isPixelPerfect)

Turns the pixel-perfect mode on or off for an art object.

Parameters:

	art	[in] The art object
	isPixelPerfect	[in] True to turn pixel-perfect mode on, false to turn it off.

AIAPI AIErr(* AIArtSuite::TransferAttributes)(AIArtHandle srcart, AIArtHandle dstart, ai::uint32 which)

Transfers attributes from a source art object to a destination art object.

Use, for example, when converting an art object from one type to another.

Parameters:

	srcart	The art object from which to copy attributes.
	dstart	The art object to which to copy attributes.
	which	The attributes to transfer, a logical OR of `AIArtTransferAttrsOptions` values.

AIAPI AIErr(* AIArtSuite::UncheckedDisposeArt)(AIArtHandle art)

Removes an art object from the art tree, performing minimal checks for validity of the input in order to maximize performance.

Disposing of a group or compound path also removes the children.

Parameters:

art

The art object. Upon return, the reference is no longer valid.

AIAPI AIErr(* AIArtSuite::UpdateArtworkLink)(AIArtHandle art, AIBoolean force, AIBoolean *updated)

Checks whether any linked objects (linked images or placed objects) contained in the subtree of a given container need updating, and updates them if needed.

A linked object needs updating if its file has been modified since the contents were last read.

Parameters:

	art	The art object.
	force	When true, objects are updated regardless of whether they have changed.
	updated	[out] Optional, a buffer in which the output as to return true if any objects were updated.

AIAPI AIBoolean(* AIArtSuite::ValidArt)(AIArtHandle art, AIBoolean searchAllLayerLists)

Returns true if an art object reference is valid.

(Note that the function returns a boolean value, not an error code.) A reference can test as invalid and still refer to an object that exists in the document, if that object is not found in the searched layer.

Parameters:

	art	The art object.
	searchAllLayerLists	When true, searches through all layers in all layer lists. Otherwise, searches only the current layer list.

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

AIArt.h

AIArtSuite Struct Reference [API Suite List]

Public Attributes

Detailed Description

Member Data Documentation

AIArtSuite Struct Reference
[API Suite List]