Legacy Document

Inside Macintosh: More Macintosh Toolbox /

Chapter 5 - Icon Utilities / Icon Utilities Reference

Icon Utilities Routines / Determining Whether a Point or Rectangle Is Within an Icon

PtInIconMethod

You can use the PtInIconMethod function to determine whether a specified point is within an icon. (A point is considered to be within an icon if the point is within the icon's mask.) The PtInIconMethod function obtains the icon to test against with the aid of your icon getter function.

FUNCTION PtInIconMethod (testPt: Point; iconRect: Rect;
                         align: IconAlignmentType;
                         theMethod: IconGetter;
                         yourDataPtr: Ptr): Boolean;

testPt

The point to be tested, specified in local coordinates of the current graphics port.

iconRect

The rectangle in which the icon appears, specified in local coordinates of the current graphics port.

align

A value that specifies how the icon against which to hit-test is aligned within the rectangle specified by iconRect. See the description of PlotIconID on page 5-20 for a list of constants you can use in this parameter.

theMethod

A pointer to an icon getter function.

yourDataPtr

A pointer to data that is passed to your icon getter function.

DESCRIPTION

The PtInIconMethod function hit-tests the point specified by testPt against an icon obtained with the aid of an icon getter function, using the destination rectangle and alignment specified by iconRect and align. The parameters iconRect and align should be the same as when the icon was last drawn. The PtInIconMethod function returns TRUE if the point is in the icon mask and FALSE if it is not.

PtInIconMethod passes to your icon getter function the type of icon your function should retrieve (either 'ICN#' or 'ics#') and also passes the value specified in the yourDataPtr parameter. The PtInIconMethod function examines the size of the specified rectangle and requests the appropriate icon from your icon getter function. Your icon getter function should return a handle to the requested icon's data. The PtInIconMethod function extracts the mask from the icon data that your icon getter function returns. If your icon getter function returns data that does not correspond to an icon of type 'ICN#' or type 'ics#', PtInIconMethod attempts to generate a mask from the returned data.

Your icon getter function can get the icon's data using whatever method is appropriate to your application. For example, your application might maintain its own cache of icons (and pass a pointer to it in the yourDataPtr parameter) or use its icon getter function to get an icon from the desktop database.

SEE ALSO

For more information about icon getter functions, see page 5-58.