AICursorSnapSuite Struct Reference
[API Suite List]

Tools that use the Smart Guides snapping facility use these functions in the cursor-tracking code. More...

#include <AICursorSnap.h>

Public Attributes
AIAPI AIBoolean(*	UseSmartGuides )(AIDocumentViewHandle view)
	Reports whether Smart Guides should be used to snap the cursor in a given view.
AIAPI AIErr(*	Reset )(void)
	Resets the Smart Guides snapping engine.
AIAPI AIErr(*	ClearCustom )(void)
	Clears all custom constraints without clearing automatically generated constraint lines.
AIAPI AIErr(*	SetCustom )(const ai::AutoBuffer< AICursorConstraint > &constraints)
	Replaces the current set of custom constraints with the specified set.
AIAPI AIErr(*	Track )(AIDocumentViewHandle view, const AIRealPoint &srcpoint, const AIEvent event, const char control, AIRealPoint *dstpoint)
	Snaps the cursor to a specified constraint, using a specified technique, using the "Snap To Point" application preference.
AIAPI AIErr(*	HitTrack )(AIDocumentViewHandle view, const AIRealPoint &srcpoint, const AIEvent event, const char control, AIRealPoint *dstpoint, AIBoolean magnifyAnchorPoint)
	Snaps the cursor to a specified constraint, using a specified technique.
AIAPI AIErr(*	TrackInRect )(AIDocumentViewHandle view, const AIRealPoint &srcpoint, const AIEvent event, const char control, AIRealPoint dstpoint, const AIRealRect srcrect, AIRealRect *dstrect)
	Snaps the rectangle supplied to a specified constraint, using a specified technique and the "Snap To Point" application preference.

Detailed Description

Tools that use the Smart Guides snapping facility use these functions in the cursor-tracking code.

The suite provides functions for snapping the cursor to various things, called constraints. Constraints include art objects, page boundaries, and automatically generated guide lines. You can also define your own constraints, using SetCustom(), although most tools do not do so.

Note:: Turning on the grid turns smart guides off, so you never use this facility to snap to the grid.

Acquire this suite using SPBasicSuite::AcquireSuite() with the constants kAICursorSnapSuite and kAICursorSnapVersion.

Snap the cursor using the Track() function, which takes a current cursor location and returns the snapped location. A control string contains a series of Smart Guide commands that control how the snap is performed; that is, what kind of object is snapped to and what kind of location to look for in each kind of object.

You can find out what object is under the snapped location:

AIHitRef hit;
long option = <<whatever options>>
result = sAIHitTest->HitTest(NULL, &p, option, &hit);
if (result)
        throw ai::Error(result);

These are the control strings used by various tools built into Illustrator, as saved in the preferences file. The first entry in each line is the key used in preferences. The second is the control string for the time when the mouse is up. The third is the control string for the time when the mouse is down.

"Blend", "A v", "A v",
"Select", "A v o f", "ATFGPLM v i o f",
"RangeSelect", "", "",
"Zoom", "", "",
"Page", "ATFGP v i o", "ATFGP v i o",
"Ruler", "ATFGPX v i o", "ATFGPMX v i o",
"Guide", "ATFGPX v i o", "ATFGPX v i o",
"Scissor", "ATFL v i o", "ATFGPL v i o",
"SquareCircle", "ATFGP v i o", "ATFGP v i o",
"Pen", "ATFGPLMSU v i o", "ATF v i o",
"Translate", "ATFGP v i o", "ATFGPBLM v i o",
"Scale", "ATFGPXY v i o", "ATFGPBLMXY v i o",
"Rotate", "ATFGPXY v i o", "ATFGPLMXY v i o",
"Reflect", "ATFGPXY v i o", "ATFGPLMXY v i o",
"Shear", "ATFGP v i o", "ATFGPLM v i o",
"Eyebucket", "A v o f", "A v o f",

Member Data Documentation

AIAPI AIErr(* AICursorSnapSuite::ClearCustom)(void)

Clears all custom constraints without clearing automatically generated constraint lines.

AIAPI AIErr(* AICursorSnapSuite::HitTrack)(AIDocumentViewHandle view, const AIRealPoint &srcpoint, const AIEvent *event, const char *control, AIRealPoint *dstpoint, AIBoolean magnifyAnchorPoint)

Snaps the cursor to a specified constraint, using a specified technique.

Does not consider the "Snap To Point" application preference, and uses the Selection tolerance to identify hits on art objects. This function is used for direct selection of anchor points.

Parameters:

	view	The document view in which to snap the cursor.
	srcpoint	The actual cursor location in view coordinates. Typically passed in the `AIToolMessage` member `cursor`.
	event	The state of modifier keys.
	control	How snapping is performed, a string containing a sequence of uppercase and lowercase characters, and spaces. Each character in the string is a command to the snapping engine. They are processed sequentially from left to right. An uppercase character enables a constraint: A: Enable snapping to art objects (without regard to the "Snap To Point" application preference). Uses the Selection tolerance preference (rather than the Snapping tolerance). T: Enable snapping to custom constraints defined by the current tool. F: Enable snapping to automatically generated guidelines. P: Enable snapping to the page boundaries. X: Enable snapping to pixel grid (if "snap to pixel" document preference is set) Y: Enable snapping to sub-pixel grid (if "snap to pixel" document preference is set) Z: Enable snapping to pixel/sub-pixel grid in a stroke-aware fashion (if "snap to pixel" document preference is set) A lower case character is an instruction to look for the best snap location of a particular type among the currently enabled constraints. i: Look for intersections of two or more constraints. o: Try to snap onto a constraint line. v: Try to snap to a point (vertex). f: Look for filled objects. A space character is an instruction to return the best snap location found so far. If no snap location has been found, the search continues.
	dstpoint	[out] A buffer in which to return the snapped cursor position.
	magnifyAnchorPoint	[in] True to magnify an anchor point whose hotspot is under the mouse cursor, as the direct selection tool does.

AIAPI AIErr(* AICursorSnapSuite::Reset)(void)

Resets the Smart Guides snapping engine.

This clears all custom constraints and all automatically generated constraint lines.

AIAPI AIErr(* AICursorSnapSuite::SetCustom)(const ai::AutoBuffer< AICursorConstraint > &constraints)

Replaces the current set of custom constraints with the specified set.

Parameters:

	count	The number of constraints being defined.
	constraints	An array of custom constraints. The function makes a copy, so the caller can free this memory after making the call.

AIAPI AIErr(* AICursorSnapSuite::Track)(AIDocumentViewHandle view, const AIRealPoint &srcpoint, const AIEvent *event, const char *control, AIRealPoint *dstpoint)

Snaps the cursor to a specified constraint, using a specified technique, using the "Snap To Point" application preference.

Parameters:

	view	The document view in which to snap the cursor.
	srcpoint	The actual cursor location in view coordinates. Typically passed in the `AIToolMessage` member `cursor`.
	event	The state of modifier keys.
	control	How snapping is performed, a string containing a sequence of uppercase and lowercase characters, and spaces. Each character in the string is a command to the snapping engine. They are processed sequentially from left to right. An uppercase character enables a constraint: A: Enable snapping to art objects (if the "Snap To Point" application preference is set). Uses the Snapping tolerance preference (rather than the Selection tolerance). T: Enable snapping to custom constraints defined by the current tool. F: Enable snapping to automatically generated guidelines. P: Enable snapping to the page boundaries. L: Enable snapping to automatically generated guidelines along the center and the edges of geometric box of all visible art objects in view. M: Enable snapping to automatically generated guidelines along the center and the edges of all artboards in the view. S: Enable snapping to automatically generated Perspective guidelines. U: Enable snapping to Perspective Grid visible in the current document. X: Enable snapping to pixel grid (if "snap to pixel" document preference is set) Y: Enable snapping to sub-pixel grid (if "snap to pixel" document preference is set) Z: Enable snapping to pixel/sub-pixel grid in a stroke-aware fashion (if "snap to pixel" document preference is set) A lower case character is an instruction to look for the best snap location. of a particular type among the currently enabled constraints. i: Look for intersections of two or more constraints. o: Try to snap onto a constraint line. v: Try to snap to a point (vertex). f: Look for filled objects. A space character is an instruction to return the best snap location found so far. If no snap location has been found, the search continues.
	dstpoint	[out] A buffer in which to return the snapped cursor position.

AIAPI AIErr(* AICursorSnapSuite::TrackInRect)(AIDocumentViewHandle view, const AIRealPoint &srcpoint, const AIEvent *event, const char *control, AIRealPoint *dstpoint, const AIRealRect *srcrect, AIRealRect *dstrect)

Snaps the rectangle supplied to a specified constraint, using a specified technique and the "Snap To Point" application preference.

This method returns the new snapped rectangle and new mouse location. If no snapping is done, then the returned point and the rectangle would be same as the passed values for source point and rectangle.

Parameters:

	view	The document view in which to snap the cursor.
	srcpoint	The actual cursor location in view coordinates. Typically passed in the `AIToolMessage` member `cursor`.
	event	The state of modifier keys.
	control	How snapping is performed, a string containing a sequence of uppercase and lowercase characters, and spaces. Each character in the string is a command to the snapping engine. They are processed sequentially from left to right. An uppercase character enables a constraint: A: Enable snapping to art objects (if the "Snap To Point" application preference is set). Uses the Snapping tolerance preference (rather than the Selection tolerance). T: Enable snapping to custom constraints defined by the current tool. F: Enable snapping to automatically generated guidelines. P: Enable snapping to the page boundaries. L: Enable snapping to automatically generated guidelines along the center and the edges of geometric box of all visible art objects in view. M: Enable snapping to automatically generated guidelines along the center and the edges of all artboards in the view. S: Enable snapping to automatically generated Perspective guidelines. U: Enable snapping to Perspective Grid visible in the current document. X: Enable snapping to pixel grid (if "snap to pixel" document preference is set) Y: Enable snapping to sub-pixel grid (if "snap to pixel" document preference is set) Z: Enable snapping to pixel/sub-pixel grid in a stroke-aware fashion (if "snap to pixel" document preference is set) A lower case character is an instruction to look for the best snap location. of a particular type among the currently enabled constraints. i: Look for intersections of two or more constraints. o: Try to snap onto a constraint line v: Try to snap to a point (vertex). f: Look for filled objects. A space character is an instruction to return the best snap location found so far. If no snap location has been found, the search continues.
	dstpoint	[out] A buffer in which to return the snapped cursor position.
	srcRect	The rectangle to be snapped.
	dstRect	[out] A buffer in which to return the new snapped rectangle bounds.

AIAPI AIBoolean(* AICursorSnapSuite::UseSmartGuides)(AIDocumentViewHandle view)

Reports whether Smart Guides should be used to snap the cursor in a given view.

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

Parameters:

view

The document view.

Returns:: True if Smart Guides should be used.

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

AICursorSnap.h

AICursorSnapSuite Struct Reference [API Suite List]

Public Attributes

Detailed Description

Member Data Documentation

AICursorSnapSuite Struct Reference
[API Suite List]