AIPlacedSuite Struct Reference
[API Suite List]

This suite provides functions that allow you to access and manipulate placed art. More...

#include <AIPlaced.h>

Public Attributes
AIAPI AIErr(*	GetPlacedFileSpecification )(AIArtHandle placed, ai::FilePath &file)
	Retrieves the file specification for the linked file of a placed object.
AIAPI AIErr(*	SetPlacedFileSpecification )(AIArtHandle placed, const ai::FilePath &file)
	Associates a placed object with a linked file.
AIAPI AIErr(*	GetPlacedMatrix )(AIArtHandle placed, AIRealMatrix *matrix)
	Retrieves the transformation matrix that positions the content of a placed art object's linked file in the document.
AIAPI AIErr(*	SetPlacedMatrix )(AIArtHandle placed, AIRealMatrix *matrix)
	Sets the transformation matrix of a placed art object.
AIAPI AIErr(*	GetPlacedBoundingBox )(AIArtHandle placed, AIRealRect *bbox)
	Retrieves the boundary dimensions of placed art, regardless of the transformations applied to it.
AIAPI AIErr(*	SetPlacedObject )(AIArtHandle placed, AIArtHandle *group)
	Creates or clears and returns a group art object to hold the parsed content of the linked file for a placed object.
AIAPI AIErr(*	CountPlacedCustomColors )(AIArtHandle art, ai::int32 *count)
	Gets the number of custom colors used by a placed art object for an EPS file.
AIAPI AIErr(*	GetNthPlacedCustomColorName )(AIArtHandle art, ai::int32 num, ai::UnicodeString &name)
	Retrieves the name of custom color used by a placed art object for an EPS file.
AIAPI AIErr(*	MakePlacedObjectNative )(AIArtHandle placed, AIArtHandle *native, AIBoolean askForParam)
	Changes a linked placed-art or raster-art object to an embedded art object.
AIAPI AIErr(*	GetPlacedType )(AIArtHandle placed, ai::int16 *pPlacedType)
	Retrieves the type of a placed object (EPS or other file type).
AIAPI AIErr(*	GetPlacedChild )(AIArtHandle placed, AIArtHandle *group)
	Retrieves the art group representing the parsed content of the non-EPS linked file for a placed object.
AIAPI AIErr(*	ExecPlaceRequest )(AIPlaceRequestData &placeRequestData)
	Executes a request related to a placed object.
AIAPI AIErr(*	GetPlacedFileInfoFromArt )(AIArtHandle placed, SPPlatformFileInfo *spFileInfo)
	Retrieves the file information for a placed object's linked file (such as the creation and modification dates), as stored from the most recent file read operation.
AIAPI AIErr(*	GetPlacedFileInfoFromFile )(AIArtHandle placed, SPPlatformFileInfo *spFileInfo)
	Retrieves the file information for a placed object's linked file (such as the creation and modification dates), from the file itself (as opposed to the file information stored with the object).
AIAPI AIErr(*	GetPlacedFilePathFromArt )(AIArtHandle placed, ai::UnicodeString &path)
	Retrieves the path specification for the file associated with a placed-art object.
AIAPI AIErr(*	ConcatPlacedMatrix )(AIArtHandle placed, AIRealMatrix *concat)
	Concatenates a new transformation onto the existing transformation matrix for a placed object.
AIAPI AIErr(*	SetPlaceOptions )(AIArtHandle placed, enum PlaceMethod method, enum PlaceAlignment alignment, AIBoolean clip)
	Sets the placement options for a placed object, used to scale and place the linked image relative to the bounds of the placed object.
AIAPI AIErr(*	GetPlaceOptions )(AIArtHandle placed, enum PlaceMethod method, enum PlaceAlignment alignment, AIBoolean *clip)
	Retrieves the placement options for a placed object.
AIAPI AIErr(*	GetPlacedDimensions )(AIArtHandle placed, AIRealPoint size, AIRealRect viewBounds, AIRealMatrix viewMatrix, AIRealRect imageBounds, AIRealMatrix *imageMatrix)
	Retrieves the size, placement, and transformation of a placed object itself, and of its linked image.The matrices are those used to transform the object and image from the original bounds to their current locations on the screen.
AIAPI AIErr(*	SetPlacedBoundingBox )(AIArtHandle art, AIRealRect *bbox)
	Sets the preliminary bounding box information for a placed object.
AIAPI AIErr(*	GetRasterInfo )(AIArtHandle art, AIRasterRecord info, AIBoolean israster)
	Retrieves the raster record describing the image for a placed object that represents a placed, linked image.
AIAPI AIErr(*	GetProcessPlatesInfo )(AIArtHandle art, AIPlacedPlateInfo *plateInfo)
	Gets the process colors plates used by a placed art object for an EPS file or a placed, linked image.
AIAPI AIBoolean(*	IsPlacedFileDamaged )(AIArtHandle art)

Detailed Description

This suite provides functions that allow you to access and manipulate placed art.

Illustrator uses placed art to link artwork contained in external files into an Illustrator document. For a file to be linked, there must be an installed file-format plug-in that supports linking the format.

A placed object is defined by its file specification and a matrix positioning the file content in the document.

After creating an empty placed object, use SetPlacedBoundingBox() to set initial bounds, then call AIArtSuite::UpdateArtworkLink() to read the content of the referenced file. If the file is read successfully, the initial bounds are replaced by the true bounds from the file. If the read fails, the bounds are not changed, and, if this function were not used to set them, the result would be a placed object without width or height.

All file types except EPS also have a group of art objects that represents the parsed contents of the file.When a file-format plug-in is requested to link a file other than an EPS, it does the following:

Creates a placed object for the linked file, setting its file specification to reference the file.
Calls SetPlacedObject() to create a group to contain the artwork representing the content of the linked file.
Reads the content of the linked file, creating the artwork to represent the content.
Sets the matrix of the placed object as needed to position the content in the document.

The transformation matrix of a placed image is the concatenation of all of the transforms applied to the image after it has been placed. The matrix begins as a simple translate which positions the image on the page. You can also rotate, scale and shear the image.

Placement options control how a linked image is positioned and scaled relative to the bounds of the placed object. Placement is adjusted whenever the image size changes; that is, when the file changes on disk, or when it is explicitly relinked with SetPlacedFileSpecification(). The replacement image can be placed into the bounds of the original object, or the bounds of the original object can be scaled, and the replacement placed into the resulting bounds.

Acquire this suite using SPBasicSuite::AcquireSuite() with the constants kAIPlacedSuite and kAIPlacedVersion.

Member Data Documentation

AIAPI AIErr(* AIPlacedSuite::ConcatPlacedMatrix)(AIArtHandle placed, AIRealMatrix *concat)

Concatenates a new transformation onto the existing transformation matrix for a placed object.

Parameters:

	placed	The placed object.
	concat	The new transformation matrix.

AIAPI AIErr(* AIPlacedSuite::CountPlacedCustomColors)(AIArtHandle art, ai::int32 *count)

Gets the number of custom colors used by a placed art object for an EPS file.

Use with GetNthPlacedCustomColorName() to iterate through the colors and get their names.

Parameters:

	art	The placed object.
	count	[out] A buffer in which to return the number of spot colors.

Returns:: The error kBadParameterErr if the linked file is not an EPS.

See also:: AICustomColorSuite.

AIAPI AIErr(* AIPlacedSuite::ExecPlaceRequest)(AIPlaceRequestData &placeRequestData)

Executes a request related to a placed object.

The request can place or replace the art, either explicitly or in relation to the current selection.

Parameters:

placeRequestData An AIPlaceRequestData structure in which to specify the request and return results.

AIAPI AIErr(* AIPlacedSuite::GetNthPlacedCustomColorName)(AIArtHandle art, ai::int32 num, ai::UnicodeString &name)

Retrieves the name of custom color used by a placed art object for an EPS file.

Use with CountPlacedCustomColors to iterate through the custom colors.

Parameters:

	art	The placed art object.
	num	The 0-based position index of the color.
	name	[out] A buffer in which to return the color name.

Returns:: The error kBadParameterErr if the linked file is not an EPS.

AIAPI AIErr(* AIPlacedSuite::GetPlacedBoundingBox)(AIArtHandle placed, AIRealRect *bbox)

Retrieves the boundary dimensions of placed art, regardless of the transformations applied to it.

Parameters:

	placed	The placed object.
	bbox	[out] A buffer in which to return the bounding rectangle.

AIAPI AIErr(* AIPlacedSuite::GetPlacedChild)(AIArtHandle placed, AIArtHandle *group)

Retrieves the art group representing the parsed content of the non-EPS linked file for a placed object.

Parameters:

	placed	The placed object.
	group	[out] A buffer in which to return the art group object.

Returns:: The error kBadParameterErr if the linked file is not an EPS.

AIAPI AIErr(* AIPlacedSuite::GetPlacedDimensions)(AIArtHandle placed, AIRealPoint *size, AIRealRect *viewBounds, AIRealMatrix *viewMatrix, AIRealRect *imageBounds, AIRealMatrix *imageMatrix)

Retrieves the size, placement, and transformation of a placed object itself, and of its linked image.The matrices are those used to transform the object and image from the original bounds to their current locations on the screen.

With the kConform placement option, these are the same.

Parameters:

	placed	The placed object.
	size	[out] A buffer in which to return the size (the X and Y dimensions) of the original image.
	viewBounds	[out] A buffer in which to return the bounding box of the placed object.
	viewMatrix	[out] A buffer in which to return the transformation matrix of the placed object.
	imageBounds	[out] A buffer in which to return the bounding box of the linked image.
	imageMatrix	[out] A buffer in which to return the transformation matrix of the linked image.

AIAPI AIErr(* AIPlacedSuite::GetPlacedFileInfoFromArt)(AIArtHandle placed, SPPlatformFileInfo *spFileInfo)

Retrieves the file information for a placed object's linked file (such as the creation and modification dates), as stored from the most recent file read operation.

Parameters:

	placed	The placed object.
	spFileInfo	[out] A buffer in which to return the file information.

Note:: Compare this file information (stored with the placed object) to the current information for the file itself (GetPlacedFileInfoFromFile()) to determine if the file has changed.

AIAPI AIErr(* AIPlacedSuite::GetPlacedFileInfoFromFile)(AIArtHandle placed, SPPlatformFileInfo *spFileInfo)

Retrieves the file information for a placed object's linked file (such as the creation and modification dates), from the file itself (as opposed to the file information stored with the object).

Parameters:

	placed	The placed object.
	spFileInfo	[out] A buffer in which to return the file information.

See also:: GetPlacedFileInfoFromArt()

AIAPI AIErr(* AIPlacedSuite::GetPlacedFilePathFromArt)(AIArtHandle placed, ai::UnicodeString &path)

Retrieves the path specification for the file associated with a placed-art object.

Parameters:

	placed	The placed object.
	path	[out] A buffer in which to return the platform-specific file path string.

AIAPI AIErr(* AIPlacedSuite::GetPlacedFileSpecification)(AIArtHandle placed, ai::FilePath &file)

Retrieves the file specification for the linked file of a placed object.

If the linked file does not exist, the returned file specification supplies only the file name.

Parameters:

	placed	The placed object.
	file	[out] A buffer in which to return the file specification.

AIAPI AIErr(* AIPlacedSuite::GetPlacedMatrix)(AIArtHandle placed, AIRealMatrix *matrix)

Retrieves the transformation matrix that positions the content of a placed art object's linked file in the document.

Use with SetPlacedMatrix() to modify the transformation.

Parameters:

	placed	The placed object.
	matrix	[out] A buffer in which to return the transformation matrix.

See also:: ConcatPlacedMatrix()

AIAPI AIErr(* AIPlacedSuite::GetPlacedType)(AIArtHandle placed, ai::int16 *pPlacedType)

Retrieves the type of a placed object (EPS or other file type).

Parameters:

	placed	The art object, of type `kPlacedArt` or `kRasterArt`.
	pPlacedType	[out] A buffer in which to return the type constant, an `AIPlacedObjectType` value.

AIAPI AIErr(* AIPlacedSuite::GetPlaceOptions)(AIArtHandle placed, enum PlaceMethod *method, enum PlaceAlignment *alignment, AIBoolean *clip)

Retrieves the placement options for a placed object.

See SetPlaceOptions().

Parameters:

	placed	The placed object.
	method	[out] A buffer in which to return the method used to position and size the linked object.
	alignment	[out] A buffer in which to return the alignment of the linked object.
	clip	[out] A buffer in which to return true if the linked object is clipped.

AIAPI AIErr(* AIPlacedSuite::GetProcessPlatesInfo)(AIArtHandle art, AIPlacedPlateInfo *plateInfo)

Gets the process colors plates used by a placed art object for an EPS file or a placed, linked image.

Parameters:

	art	The placed object.
	plateInfo	[out] A buffer in which to return which plates are used by the placed object

AIAPI AIErr(* AIPlacedSuite::GetRasterInfo)(AIArtHandle art, AIRasterRecord *info, AIBoolean *israster)

Retrieves the raster record describing the image for a placed object that represents a placed, linked image.

Parameters:

	art	The placed object.
	info	[out] A buffer in which to return the information.
	israster	[out] A buffer in which to return if the placed object does represent an image, false if it does not.

AIAPI AIBoolean(* AIPlacedSuite::IsPlacedFileDamaged)(AIArtHandle art)

AIAPI AIErr(* AIPlacedSuite::MakePlacedObjectNative)(AIArtHandle placed, AIArtHandle *native, AIBoolean askForParam)

Changes a linked placed-art or raster-art object to an embedded art object.

Parameters:

	placed	The art object, of type `kPlacedArt` or `kRasterArt`.
	native	[out] A buffer in which to return the new embedded art object.
	askForParam	When true, show dialog for user input if needed.

AIAPI AIErr(* AIPlacedSuite::SetPlacedBoundingBox)(AIArtHandle art, AIRealRect *bbox)

Sets the preliminary bounding box information for a placed object.

Parameters:

	art	The placed object.
	bbox	The bounding rectangle.

AIAPI AIErr(* AIPlacedSuite::SetPlacedFileSpecification)(AIArtHandle placed, const ai::FilePath &file)

Associates a placed object with a linked file.

If the file is an EPS, immediately parses the contents and acquires the PICT preview. Otherwise, defers parsing until you request it with AIArtSuite::UpdateArtworkLink() or AIDocumentSuite::UpdateLinks().

Parameters:

	placed	The placed object.
	file	The file specification. If this identifies an EPS, i

AIAPI AIErr(* AIPlacedSuite::SetPlacedMatrix)(AIArtHandle placed, AIRealMatrix *matrix)

Sets the transformation matrix of a placed art object.

The matrix includes the simple translate that places the image on the page, as well as any rotate, scale, and shear values. Use with GetPlacedMatrix() to modify the transformation.

Parameters:

	placed	The placed object.
	matrix	The new transformation matrix.

See also:: ConcatPlacedMatrix()

AIAPI AIErr(* AIPlacedSuite::SetPlacedObject)(AIArtHandle placed, AIArtHandle *group)

Creates or clears and returns a group art object to hold the parsed content of the linked file for a placed object.

File-format plug-ins call this when reading the content of a linked file.

Parameters:

	placed	The placed object.
	group	[out] A buffer in which to return the group art object.

AIAPI AIErr(* AIPlacedSuite::SetPlaceOptions)(AIArtHandle placed, enum PlaceMethod method, enum PlaceAlignment alignment, AIBoolean clip)

Sets the placement options for a placed object, used to scale and place the linked image relative to the bounds of the placed object.

Placement is adjusted whenever the image size changes; that is, when the file changes on disk, or when it is explicitly relinked with SetPlacedFileSpecification().

Parameters:

	placed	The placed object.
	method	The way to position and size the linked object.
	alignment	The way to align the linked object
	clip	True to clip the linked object.

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

AIPlaced.h

AIPlacedSuite Struct Reference [API Suite List]

Public Attributes

Detailed Description

Member Data Documentation

AIPlacedSuite Struct Reference
[API Suite List]