Inside Macintosh: More Macintosh Toolbox /

Chapter 5 - Icon Utilities

About the Icon Utilities

The Icon Utilities allow your application (and system software) to manipulate and draw icons of any standard resource type in windows and if necessary in menus or dialog boxes. You need to use these routines only if you wish to draw icons in your application's windows or to draw icons whose resource types are not recognized by the Menu Manager and Dialog Manager in menus and dialog boxes.

To display an icon most effectively at a variety of sizes and bit depths, you should provide an icon family. You can then draw the appropriate member of the family for a given size and bit depth either by passing the family's resource ID to an Icon Utilities routine or by reading the family's icon resources into memory as an icon suite and passing the suite's handle to Icon Utilities routines.

The next section, "Using the Icon Utilities," begins by describing how to draw icons in an icon family. After a brief overview of icon families, icon suites, icon caches, and related Icon Utilities routines, it describes in detail how to

• draw the most appropriate icon for a given destination rectangle and bit depth directly from an icon family member's resource
• get an icon suite and draw the most appropriate icon from that suite for a given destination rectangle and bit depth
• draw specific icons from an icon family or suite
• get a handle to an icon suite member's icon data so you can manipulate it
• draw icons that are not part of an icon family

You can use also Icon Utilities routines to

• perform operations on icons in an icon suite
• manipulate labels associated with specific icon suites
• dispose of icon suites and color icon records
• convert an icon mask to a region and perform hit-testing for an icon
• create an icon cache by associating an icon suite with an icon getter function and a pointer to data that you can use as a reference constant

For detailed descriptions of all Icon Utilities routines, including those used to perform these tasks, see "Icon Utilities Reference" beginning on page 5-17.

In addition to the resource types described earlier in this chapter, some Icon Utilities routines operate on icons of resource types 'icm#', 'icm4', and 'icm8'. These mini icons are 12-by-16 pixel icons. Like the icons in an icon family, the three resource types for mini icons identify the icon list, 4-bit color icons, and 8-bit color icons, respectively.