Legacy Document

Inside Macintosh: More Macintosh Toolbox /

Chapter 5 - Icon Utilities / Icon Utilities Reference

Icon Utilities Routines

This section describes the Icon Utilities routines. You can use these routines to draw icons in windows and, if necessary, in menus and dialog boxes. You can also use Icon Utilities routines to perform operations on icons in an icon suite, get and set labels associated with specific icon suites, dispose of icon suites and color icon records, convert an icon mask to a region, perform hit-testing, and create and manipulate icon caches. Note that you can pass a handle to an icon cache to any of the Icon Utilities routines that accept a handle to an icon suite.

Most of the Icon Utilities routines are available only in System 7 and later. To
determine whether they are available, call the Gestalt function with the gestaltIconUtilitiesAttr selector and check the value of the response parameter. If the bit indicated by the constant gestaltIconUtilitiesPresent is set, then the Icon Utilities are available. The GetIcon, PlotIcon, GetCIcon, PlotCIcon, and DisposeCIcon routines are available in both System 6 and System 7.

Note

The Icon Utilities routines do not place any restrictions on whether icon resources are purgeable or nonpurgeable; however, in general, you should specify your icon resources as purgeable.

This section first describes the routines you can use to draw icons from an icon family and then describes the routines that work with icon suites and icon caches.

IMPORTANT

All of the Icon Utilities routines may move or purge memory blocks in the application heap or for some other reason should not be called from within an interrupt. Your application should not call Icon Utilities routines at interrupt time.

Assembly-Language Note

You can invoke Icon Utilities routines by using the trap _IconDispatch with the appropriate routine selector. The routine selectors are listed in "Assembly-Language Summary" beginning on page 5-71.

---

Subtopics

Drawing Icons From Resources

Getting Icons From Resources That Don't Belong to an Icon Family

Disposing of Icons

Creating an Icon Suite

Getting Icons From an Icon Suite

Drawing Icons From an Icon Suite

Performing Operations on Icons in an Icon Suite

Getting and Setting the Label for an Icon Suite

Getting Label Information

Disposing of Icon Suites

Converting an Icon Mask to a Region

Determining Whether a Point or Rectangle Is Within an Icon

Working With Icon Caches