AIHardSoftSuite Struct Reference
[API Suite List]

This suite provides functions for converting between different coordinate systems used at different levels of Illustrator. More...

#include <AIHardSoft.h>

List of all members.

Public Attributes
AIAPI AIErr(*	AIRealPointHarden )(AIRealPoint *srcpoint, AIRealPoint *dstpoint)
	Converts a point in public page coordinates to a point in internal artboard coordinates.
AIAPI AIErr(*	AIRealPointSoften )(AIRealPoint *srcpoint, AIRealPoint *dstpoint)
	Converts a point in internal artboard coordinates to a point in public page coordinates.
AIAPI AIErr(*	AIRealMatrixHarden )(AIRealMatrix *matrix)
	Applies AIRealPointHarden() to the translation component of a matrix.
AIAPI AIErr(*	AIRealMatrixSoften )(AIRealMatrix *matrix)
	Applies AIRealPointSoften() to the translation component of a matrix.
AIAPI AIErr(*	AIRealMatrixRealHard )(AIRealMatrix *matrix)
	Applies AIRealPointHarden() to the translation component of a matrix, then negates the b and c components.
AIAPI AIErr(*	AIRealMatrixRealSoft )(AIRealMatrix *matrix)
	Applies AIRealPointSoften() to the translation component of a matrix, then negates the b and c components.
AIAPI AIErr(*	GetCoordinateSystem )(ai::int32 &coordinateSystem)
	Retrieves the coordinate system used by API functions in the current context.
AIAPI AIErr(*	SetCoordinateSystem )(ai::int32 coordinateSystem)
	Changes the coordinate system used by API functions in the current context.
AIAPI AIErr(*	ConvertCoordinates )(AIRealPoint &point, ai::int32 src, ai::int32 dest, AIBoolean convertForDisplay)
	Converts the coordinate system of a single point from one system to another.

---

Detailed Description

This suite provides functions for converting between different coordinate systems used at different levels of Illustrator.

The geometry of an object is described by coordinates that are relative to a pair of imaginary axes imposed on the artboard. Illustrator uses two ways of placing these axes; one for storing coordinate information internally, and another for passing coordinate information across the SDK functions.

• In the internal coordinate system, the origin is the top left corner of the artboard--that is, of the white area that can be seen when zoomed out as far as possible. The X axis is horizontal, with the values increasing to the right. The Y axis is vertical, with values increasing downward. Values in this system are called hard, or artboard coordinates.

• In the public coordinate system, the origin is the ruler origin--that is, the point that corresponds to the 0 marks on the ruler when it is visible. By default, it is the bottom left corner of the page, but it can be changed by the user. The X axis is horizontal, with the values increasing to the right. The Y axis is vertical, with values increasing upward. Values in this system are called soft, or page coordinates.

Most functions in the SDK use the public system of page coordinates, but some use the internal artboard coordinates. This suite provides functions for mapping between the coordinate systems. For example, if you pass the origin point, [0,0], to AIRealPointHarden(), the function returns the vector from the artboard origin (the top left of the canvas) to the page origin (the bottom left of the visible page).

Note:

These matrix conversion functions do not convert all components of translation matrices. To do this, you must understand the details of the two coordinate systems involved and use linear algebra. You must analyzed each case. For example, the matrix stored in an AIPatternStyle maps coordinates from pattern space to internal artboard space, whereas the matrix for an image maps from image space to public page space.

• Acquire this suite using SPBasicSuite::AcquireSuite() with the constants kAIHardSoftSuite and kAIHardSoftVersion.

---

Member Data Documentation

AIAPI AIErr(* AIHardSoftSuite::AIRealMatrixHarden)(AIRealMatrix *matrix)

Applies AIRealPointHarden() to the translation component of a matrix.

This can be used to re-harden a returned matrix that has been incorrectly softened.

Parameters:

matrix

[in, out] The translation matrix, which is modified in place.

AIAPI AIErr(* AIHardSoftSuite::AIRealMatrixRealHard)(AIRealMatrix *matrix)

Applies AIRealPointHarden() to the translation component of a matrix, then negates the b and c components.

Parameters:

matrix

[in, out] The translation matrix, which is modified in place.

AIAPI AIErr(* AIHardSoftSuite::AIRealMatrixRealSoft)(AIRealMatrix *matrix)

Applies AIRealPointSoften() to the translation component of a matrix, then negates the b and c components.

Parameters:

matrix

[in, out] The translation matrix, which is modified in place.

AIAPI AIErr(* AIHardSoftSuite::AIRealMatrixSoften)(AIRealMatrix *matrix)

Applies AIRealPointSoften() to the translation component of a matrix.

This can be used to pre-soften a matrix being passed into a function that will apply incorrect hardening.

Parameters:

matrix

[in, out] The translation matrix, which is modified in place.

AIAPI AIErr(* AIHardSoftSuite::AIRealPointHarden)(AIRealPoint *srcpoint, AIRealPoint *dstpoint)

Converts a point in public page coordinates to a point in internal artboard coordinates.

Parameters:

	srcpoint	A pointer to the point in public page coordinates.
	dstpoint	[out] A buffer in which to return the point in internal artboard coordinates.

AIAPI AIErr(* AIHardSoftSuite::AIRealPointSoften)(AIRealPoint *srcpoint, AIRealPoint *dstpoint)

Converts a point in internal artboard coordinates to a point in public page coordinates.

Parameters:

	srcpoint	A pointer to the point in internal artboard coordinates.
	dstpoint	[out] A buffer in which to return the point in public page coordinates.

AIAPI AIErr(* AIHardSoftSuite::ConvertCoordinates)(AIRealPoint &point, ai::int32 src, ai::int32 dest, AIBoolean convertForDisplay)

Converts the coordinate system of a single point from one system to another.

Parameters:

	point[in,out]	The current coordinate of the point, modified in place.
	src	[in] The source coordinate system, an AICoordinateSystem value.
	dest	[in] The destination coordinate system, an AICoordinateSystem value.
	convertForDisplay	[in] True to convert Y values if the artboard's ruler origin is set to bottom left (which was the default in CS4). In CS5, the default ruler origin is top left, and Y values increase downward. Set to true for values to be used in the UI.

AIAPI AIErr(* AIHardSoftSuite::GetCoordinateSystem)(ai::int32 &coordinateSystem)

Retrieves the coordinate system used by API functions in the current context.

Valid only for the current message call received by a plug-in. The value is reset to kAIDocumentCoordinateSystem each time the app context is popped; see AIAppContextSuite::PushAppContext() and AIAppContextSuite::PopAppContext().

Parameters:

coordinateSystem

[out] A buffer in which to return the current coordinate system constant, an AICoordinateSystem value.

Note:

It is recommended that you use ai::AutoCoordinateSystem, rather than explicitly calling these get and set functions.

Referenced by ai::AutoCoordinateSystem::AutoCoordinateSystem().

AIAPI AIErr(* AIHardSoftSuite::SetCoordinateSystem)(ai::int32 coordinateSystem)

Changes the coordinate system used by API functions in the current context.

Must be set for every message a plug-in receives. The value is reset to kAIDocumentCoordinateSystem each time the app context is popped; see AIAppContextSuite::PushAppContext() and AIAppContextSuite::PopAppContext().

Parameters:

coordinateSystem

[in] The new coordinate system constant, an AICoordinateSystem value.

Note:

It is recommended that you use ai::AutoCoordinateSystem, rather than explicitly calling these get and set functions.

Referenced by ai::AutoCoordinateSystem::AutoCoordinateSystem(), and ai::AutoCoordinateSystem::~AutoCoordinateSystem().

---

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

• AIHardSoft.h