AIForeignObjectSuite Struct Reference
[API Suite List]

This suite allows you to work with foreign objects, that is, art objects that encapsulate imaging constructs which are supported by PDF and the Adobe Imaging Model, but are not native to Illustrator. More...

#include <AIForeignObject.h>

List of all members.

Public Attributes
AIAPI AIErr(*	New )(ai::int16 paintOrder, AIArtHandle prep, AIBoolean copyObjects, AIArtHandle *newArt)
	Creates a new, empty foreign object.
AIAPI AIBoolean(*	Is )(AIArtHandle art)
	Reports whether an art object is a foreign object.
AIAPI AIErr(*	GetBounds )(AIArtHandle art, AIRealRect *bounds)
	Retrieves the bounds of a foreign object (that is, the bounds of the display list contents before application of a transformation matrix,.
AIAPI AIErr(*	SetBounds )(AIArtHandle art, AIRealRect *bounds)
	Sets the bounds of the foreign object (that is, the bounds of the display list contents before application of a transformation matrix,.
AIAPI AIErr(*	GetMatrix )(AIArtHandle art, AIRealMatrix *matrix)
	Retrieves the transformation matrix of a foreign object, which transforms display list coordinates to artboard coordinates.
AIAPI AIErr(*	SetMatrix )(AIArtHandle art, AIRealMatrix *matrix)
	Sets the transformation matrix of a foreign object, which transforms display list coordinates to artboard coordinates.
AIAPI AIErr(*	GetDisplayPort )(AIArtHandle art, AIDisplayPortHandle *port)
	Retrieves the AGM display port of a foreign object, Pass a new, empty foreign object, and draw into the port.
AIAPI AIErr(*	InstallResources )(AIArtHandle art)
	Not implemented.
AIAPI AIErr(*	DuplicateForConversion )(AIArtHandle art, ai::int16 paintOrder, AIArtHandle prep, AIArtHandle *newArt)
	Duplicates a foreign object, stripping off any attributes that affect the rendering of the contents of the object, other than the transformation matrix.

---

Detailed Description

This suite allows you to work with foreign objects, that is, art objects that encapsulate imaging constructs which are supported by PDF and the Adobe Imaging Model, but are not native to Illustrator.

Foreign objects behave like placed objects in that they can be positioned on the page, saved, displayed on the screen, and printed. They do not, however, respond to other Illustrator editing commands. A foreign object can use global resources that are used by other artwork elements, such as fonts or spot colors.

Illustrator requires that all spot colors used in a document be installed into the swatch list. Each spot color must have a unique definition and spot colors used by foreign objects are locked against having their definition edited. The installation and locking of spot colors needs to be done once the foreign object has been created and is known to be a permanent result of an operation on the document, as opposed to a temporary object created during an operation. For this reason installation of spot colors is done when an editing operation is committed. When spot colors are installed, their definitions can conflict with existing spot colors. in which case the user is prompted to resolve the conflict.

See also:

AIFOConversionSuite for functions that expand foreign objects to native Illustrator artwork.

• Acquire this suite using SPBasicSuite::AcquireSuite() with the constants kAIForeignObjectSuite and kAIForeignObjectVersion.

---

Member Data Documentation

AIAPI AIErr(* AIForeignObjectSuite::DuplicateForConversion)(AIArtHandle art, ai::int16 paintOrder, AIArtHandle prep, AIArtHandle *newArt)

Duplicates a foreign object, stripping off any attributes that affect the rendering of the contents of the object, other than the transformation matrix.

Used with the kAIFOConversionSuppressAttributes flag in the AIFOConversionSuite.

Parameters:

	art	The foreign object.
	paintOrder	The paint order position of the new art, relative to the prep object. See AITypes::AIPaintOrder.
	prep	The prepositional art object.See AIArtSuite::NewArt().
	newArt	[out] A buffer in which to return the new artwork.

AIAPI AIErr(* AIForeignObjectSuite::GetBounds)(AIArtHandle art, AIRealRect *bounds)

Retrieves the bounds of a foreign object (that is, the bounds of the display list contents before application of a transformation matrix,.

Parameters:

	art	The foreign object
	bounds	[out] A buffer in which to return the bounding box.

AIAPI AIErr(* AIForeignObjectSuite::GetDisplayPort)(AIArtHandle art, AIDisplayPortHandle *port)

Retrieves the AGM display port of a foreign object, Pass a new, empty foreign object, and draw into the port.

The drawing commands are recorded by the display port and are played back whenever the foreign object is rendered.

One way to draw into the display port is to set it as the portV6 member of the AIDrawArtData structure and use AIDrawArtSuite::DrawArt(). If you have access to the AGM interface, you can draw directly into the display list or play its contents to another AGM port.

Parameters:

	art	The foreign object, as returned by New().
	port	[out] A buffer in which to return the display port.

AIAPI AIErr(* AIForeignObjectSuite::GetMatrix)(AIArtHandle art, AIRealMatrix *matrix)

Retrieves the transformation matrix of a foreign object, which transforms display list coordinates to artboard coordinates.

Parameters:

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

AIAPI AIErr(* AIForeignObjectSuite::InstallResources)(AIArtHandle art)

Not implemented.

a no-op.

AIAPI AIBoolean(* AIForeignObjectSuite::Is)(AIArtHandle art)

Reports whether an art object is a foreign object.

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

Parameters:

art

The art object.

Returns:

True if the art is a foreign object.

AIAPI AIErr(* AIForeignObjectSuite::New)(ai::int16 paintOrder, AIArtHandle prep, AIBoolean copyObjects, AIArtHandle *newArt)

Creates a new, empty foreign object.

Pass this object to GetDisplayPort(), and draw into that port to fill the object.

Parameters:

	paintOrder	The paint order position of the new art, relative to the prep object. See AITypes::AIPaintOrder.
	prep	The prepositional art object.See AIArtSuite::NewArt().
	copyObjects	When true, all objects drawn into the display list are deep copied. Set to false for maximum efficiency, but must be true if the objects depend on resources that will go away after the display list has been created.
	newArt	[out] A buffer in which to return the new artwork.

AIAPI AIErr(* AIForeignObjectSuite::SetBounds)(AIArtHandle art, AIRealRect *bounds)

Sets the bounds of the foreign object (that is, the bounds of the display list contents before application of a transformation matrix,.

Parameters:

	art	The foreign object
	bounds	The bounding box.

AIAPI AIErr(* AIForeignObjectSuite::SetMatrix)(AIArtHandle art, AIRealMatrix *matrix)

Sets the transformation matrix of a foreign object, which transforms display list coordinates to artboard coordinates.

Parameters:

	art	The foreign object
	matrix	The transformation matrix.

---

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

• AIForeignObject.h