AIHitTestSuite Struct Reference
[API Suite List]

These function allow you to query a document or art subtree for objects based on positional information. More...

#include <AIHitTest.h>

Public Attributes
AIAPI AIErr(*	HitTest )(AIArtHandle art, const AIRealPoint point, ai::int32 option, AIHitRef hit)
	Finds an object in a given art tree at a given point.
AIAPI AIErr(*	HitTestEx )(AIArtHandle art, const AIRealPoint point, AIReal tolerance, ai::int32 option, AIHitRef hit)
	Finds an object in a given art tree at or near a given point.
AIAPI ai::int32(*	AddRef )(AIHitRef hit)
	Increments the reference count of a hit object.
AIAPI ai::int32(*	Release )(AIHitRef hit)
	Decrements the reference count of a hit object and frees the memory if the count has reached 0.
AIAPI AIErr(*	GetHitData )(AIHitRef hit, AIToolHitData *toolHit)
	Retrieves hit data from a hit object.
AIAPI AIBoolean(*	IsHit )(AIHitRef hit)
	Reports whether a search found a matching object.
AIAPI ai::int32(*	GetType )(AIHitRef hit)
	Retrieves the type of object found by a successful hit test.
AIAPI ai::int32(*	GetSubType )(AIHitRef hit)
	Retrieves the sub-type for an object of type `kFillHitType` that was found by a successful hit test.
AIAPI AIArtHandle(*	GetArt )(AIHitRef hit)
	Retrieves the leaf object that was found by a successful hit test.
AIAPI AIArtHandle(*	GetGroup )(AIHitRef hit)
	Retrieves the group containing the leaf object that was found by a successful hit test.
AIAPI AIRealPoint(*	GetPoint )(AIHitRef hit)
	Retrieves the exact location of the hit.
AIAPI ai::int16(*	GetPathSegment )(AIHitRef hit)
	If the hit is on an anchor point or segment of a path, retrieves the path segment containing the target point.
AIAPI AIReal(*	GetPathParameter )(AIHitRef hit)
	If the hit was on a segment of a path, retrieves the parametric value of the nearest location on the segment to the hit.
AIAPI AIErr(*	CustomHitTest )(AIArtHandle art, const AIRealPoint point, AIReal tolerance, ai::int32 option, AIPluginGroupHandle pluginGroup, void extData, AIHitRef *hit)
	Finds an object at a given point, performing custom hit testing for plug-in objects, as defined by the plug-in group.
AIAPI AIErr(*	GetCustomHitData )(AIHitRef hit, void *userdata, AIArtHandle pluginObject)
	Retrieves the result of custom hit testing performed by a plug-in group.
AIAPI AIReal(*	GetSignedHitDistance )(AIHitRef hit)
	Finds the distance from the actual mouse-down point to the closest point on the path.

Detailed Description

These function allow you to query a document or art subtree for objects based on positional information.

Acquire this suite using SPBasicSuite::AcquireSuite() with the constants kAIHitTestSuite and kAIHitTestVersion.

Member Data Documentation

AIAPI ai::int32(* AIHitTestSuite::AddRef)(AIHitRef hit)

Increments the reference count of a hit object.

Use this function if you intend to hold onto the hit object for longer than a single event or notification, for example if you want to compare the hit at mouse down to the hit during drag or at mouse up. (Note that this function returns a numeric value, not an error code.)

Parameters:

hit The hit object. The function has no effect if this is NULL.

Returns:: The current reference count, after the increment.

AIAPI AIErr(* AIHitTestSuite::CustomHitTest)(AIArtHandle art, const AIRealPoint *point, AIReal tolerance, ai::int32 option, AIPluginGroupHandle pluginGroup, void *extData, AIHitRef *hit)

Finds an object at a given point, performing custom hit testing for plug-in objects, as defined by the plug-in group.

Parameters:

	art	The root object of an art tree, or `NULL` to search the entire current document.
	point	A pointer to the location of interest, in artwork coordinates.
	tolerance	The size of the window around `point` in which to test. A number of pixels at the current zoom factor. The default value is 2. The algorithm is not guaranteed to produce correct results for large values.
	option	The type of search to perform, an `AIHitRequest` constant.
	pluginGroup	The plug-in group whose members perform custom hit testing in addition to the regular hit tests specified by `options`, using the additional data passed in `extData`.
	extData	A pointer to a developer-defined data structure to pass to the custom test. When there is a hit on a member of the plug-in group, that object's custom hit test fills this structure and passes it back in the hit object, in the `AIPluginGroupCustomHitTestData::inData` field.
	hit	[out] A buffer in which to return the hit object, which includes information passed in the `AIPluginGroupCustomHitTestData::outData` field. This object is reference counted. The initial count is 1. Use `Release()` to decrement the count and free the memory when the count is 0.

See also:: GetCustomHitData() to retrieve custom hit data returned by the plug-in group.
GetHitData() to retrieve other hit data.

AIAPI AIArtHandle(* AIHitTestSuite::GetArt)(AIHitRef hit)

Retrieves the leaf object that was found by a successful hit test.

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

Parameters:

hit The hit object. Only valid if IsHit() returns true for this hit.

Returns:: The leaf art object that matched the test criteria.

AIAPI AIErr(* AIHitTestSuite::GetCustomHitData)(AIHitRef hit, void **userdata, AIArtHandle *pluginObject)

Retrieves the result of custom hit testing performed by a plug-in group.

Parameters:

	hit	The hit object, as returned by `CustomHitTest()`.
	userData	[out] A buffer in which to return a pointer to the developer-defined data structure returned by the plug-in group's hit test, as passed in the `AIPluginGroupCustomHitTestData::outData` field. This memory is owned by the hit object, and remains valid while the hit object is valid. Do not delete it explicitly; instead, provide an implementation of `AICustomHitDataDeleteFunc`, which is used to delete it when the hit object is released.
	pluginObject	[out] A buffer in which to return the plug-in group member object the custom hit testing was performed on.

See also:: AIPluginGroupSuite

AIAPI AIArtHandle(* AIHitTestSuite::GetGroup)(AIHitRef hit)

Retrieves the group containing the leaf object that was found by a successful hit test.

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

Parameters:

hit The hit object. Only valid if IsHit() returns true for this hit.

Returns:: The group containing the leaf art object.

AIAPI AIErr(* AIHitTestSuite::GetHitData)(AIHitRef hit, AIToolHitData *toolHit)

Retrieves hit data from a hit object.

Some object-type-specific information must be retrieved separately, using the appropriate suite, such as AIMeshHitSuite.

Parameters:

	hit	The hit object.
	toolHit	[out] A buffer in which to return the data structure.

AIAPI AIReal(* AIHitTestSuite::GetPathParameter)(AIHitRef hit)

If the hit was on a segment of a path, retrieves the parametric value of the nearest location on the segment to the hit.

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

Parameters:

hit The hit object. Only valid if IsHit() returns true for this hit, and hit type is kSegmentHitType.

Returns:: The parametric value, a position along the curve where 0 is the start and 1 is the end.

AIAPI ai::int16(* AIHitTestSuite::GetPathSegment)(AIHitRef hit)

If the hit is on an anchor point or segment of a path, retrieves the path segment containing the target point.

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

Parameters:

hit The hit object. Only valid if IsHit() returns true for this hit, and hit type is kPHitType, kInHitType, kOutHitType, or kSegmentHitType.

Returns:: The path segment number.

AIAPI AIRealPoint(* AIHitTestSuite::GetPoint)(AIHitRef hit)

Retrieves the exact location of the hit.

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

Parameters:

hit The hit object. Only valid if IsHit() returns true for this hit.

Returns:: The point location. If the hit was on a geometric entity such as a point or segment of a path, this is the nearest point on that entity to the input point.

AIAPI AIReal(* AIHitTestSuite::GetSignedHitDistance)(AIHitRef hit)

Finds the distance from the actual mouse-down point to the closest point on the path.

The result is a signed number; a negative value indicates that the mouse point was on the left side of the path (in the path direction traveling from start to end), while a positive value means that the mouse point was on the right side of the path.

Use with kStrokeHitRequest for help in setting the left or right stroke width. Valid only if IsHit() returns true for this hit, and the hit type is kPHitType or kSegmentHitType.

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

Parameters:

hit

The hit object.

Returns:: The signed distance value, or 0 if the validity conditions are not met.

AIAPI ai::int32(* AIHitTestSuite::GetSubType)(AIHitRef hit)

Retrieves the sub-type for an object of type kFillHitType that was found by a successful hit test.

Sub-types of the Fill hit type can be In, Out, Segment, or Center. Otherwise, returns the primary type. (Note that this function returns a constant value, not an error code.)

Parameters:

hit The hit object. Only valid if IsHit() returns true for this hit.

Returns:: The AIHitType value for the sub-type of the found object, or the primary type if the found object was not of type kFillHitType.

AIAPI ai::int32(* AIHitTestSuite::GetType)(AIHitRef hit)

Retrieves the type of object found by a successful hit test.

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

Parameters:

hit The hit object. Only valid if IsHit() returns true for this hit.

Returns:: The AIHitType value for the found object.

AIAPI AIErr(* AIHitTestSuite::HitTest)(AIArtHandle art, const AIRealPoint *point, ai::int32 option, AIHitRef *hit)

Finds an object in a given art tree at a given point.

Searches from front to back in the paint order, within a small tolerance of the given point. (The tolerance used is dependent upon global user preferences. See HitTestEx for a version which takes the tolerance as a parameter.) Returns the closest object found that matches the criteria specified by option.

Parameters:

	art	The root object of an art tree, or `NULL` to search the entire current document.
	point	A pointer to the location of interest, in artwork coordinates.
	option	The type of search to perform, an `AIHitRequest` constant.
	hit	[out] A buffer in which to return the hit object. This object is reference counted. The initial count is 1. Use `Release()` to decrement the count and free the memory when the count is 0.

See also:: GetHitData() and other access functions to examine the contents of the hit object.

AIAPI AIErr(* AIHitTestSuite::HitTestEx)(AIArtHandle art, const AIRealPoint *point, AIReal tolerance, ai::int32 option, AIHitRef *hit)

Finds an object in a given art tree at or near a given point.

Differs from HitTest() in that it allows you to specify the size of the tolerance window around the point of interest.

Parameters:

	art	The root object of an art tree, or `NULL` to search the entire current document.
	point	A pointer to the location of interest, in artwork coordinates.
	tolerance	The size of the window around `point` in which to test. A number of pixels at the current zoom factor. The default value is 2. The algorithm is not guaranteed to produce correct results for large values.
	option	The type of search to perform, an `AIHitRequest` constant.
	hit	[out] A buffer in which to return the hit object. Use `GetHitData()` and other access function in this suite to examine the contents. This object is reference counted. The initial count is 1. Use `Release()` to decrement the count and free the memory when the count is 0.