Legacy Documentclose button

Important: The information in this document is obsolete and should not be used for new development.

Previous Book Contents Book Index Next

Inside Macintosh: More Macintosh Toolbox /
Chapter 5 - Icon Utilities / Icon Utilities Reference
Icon Utilities Routines / Converting an Icon Mask to a Region


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;
IconMethodToRgn returns a handle to the requested region in this parameter. You must allocate memory for the region handle before calling IconMethodToRgn.
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.
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.
A pointer to an icon getter function.
A pointer to data that is passed to your icon getter function.
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.

noErr0No error
noMaskFoundErr-1000No mask found

Previous Book Contents Book Index Next

© Apple Computer, Inc.
6 JUL 1996