Legacy Document

Inside Macintosh: More Macintosh Toolbox /

Chapter 5 - Icon Utilities / Icon Utilities Reference

Icon Utilities Routines / Converting an Icon Mask to a Region

IconMethodToRgn

You can use the IconMethodToRgn function to convert, to a region, the mask for an icon that IconMethodToRgn obtains with the aid of your icon getter function.

FUNCTION IconMethodToRgn (theRgn: RgnHandle; iconRect: Rect;
                          align: IconAlignmentType;
                          theMethod: IconGetter;
                          yourDataPtr: Ptr): OSErr;

theRgn

IconMethodToRgn returns a handle to the requested region in this parameter. You must allocate memory for the region handle before calling IconMethodToRgn.

iconRect

The rectangle in which to draw the icon, specified in local coordinates of the current graphics port. The IconMethodToRgn function obtains the data for the icon mask from your icon getter function and then converts the icon mask to a region. IconMethodToRgn uses the rectangle specified in this parameter as the bounding box of the region.

align

A value that specifies how IconMethodToRgn should align the region within the rectangle. 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 IconMethodToRgn function modifies the region referred to by the handle in the theRgn parameter. The region corresponds to the icon's mask (as returned by your icon getter function, and according to the rectangle and alignment specified in the iconRect and align parameters).

IconMethodToRgn passes to your icon getter function the type of the icon to get and the value specified in the yourDataPtr parameter. The IconMethodToRgn function examines the size of the rectangle and requests the appropriate icon from your icon getter function--an icon of icon type 'ICN#' or 'ics#'. Your icon getter function should return a handle to the data of the requested icon type. The IconMethodToRgn 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#', IconMethodToRgn attempts to generate a mask from the returned data.

Your icon getter function can get the data for the icon and its mask 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.

RESULT CODES

noErr	0	No error
noMaskFoundErr	-1000	No mask found