Legacy Document

Inside Macintosh: Macintosh Toolbox Essentials /

Chapter 7 - Finder Interface / Using the Finder Interface

Creating Customized Document Icons

You can create customized icons for your documents. Users can also create customized icons. When an icon list resource is stored with a resource ID of -16455 in the resource fork of a file, the Finder uses the large, small, 4-bit and 8-bit color, and black-and-white icons defined in resources with that resource ID as customized icons in place of the Finder's default icon and in place of any icons listed in the file's bundle resource.

Note

Although an application can assign icons to it all of its documents by associating their icons with the documents' file types in a bundle resource (as explained in "Creating File Reference Resources" beginning on page 7-17 and "Creating a Bundle Resource" beginning on page 7-19), a customized icon can represent only one specific file--that file that has an icon list resource with a resource ID of -16455 in its resource fork.

Users of System 7 are able to customize individual icons. By selecting a file and choosing Get Info from the File menu, the user sees the information window for that file. The
user can then select the icon displayed in the upper-left corner of the information window and use the Paste command in the Edit menu to replace it with a picture from the Clipboard. The Finder creates a family of icons based on the user's customized
icon, assigns a resource ID number of -16455 to each resource in the icon family, stores these resources in the resource fork of the file that the icon represents, and sets the hasCustomIcon bit in the file's Finder flags field. (Finder flags are described in detail
in "File Information Record" beginning on page 7-44.)

Your application can use the same strategy to provide customized icons for the documents that it creates. For example, a drawing application might create miniature versions of the illustrations contained within its documents and use those for the documents' icons.

If you are a database developer who creates and distributes query documents that support the Data Access Manager, you can also use this strategy to create icons that identify your database's query documents. Similarly, if instead of producing an application you produce and distribute information (such as database files, stationery pads, clip art libraries, or dictionaries) to be used by other applications, you might want to provide icons that distinguish your documents.

To make the Finder display customized icons for a document, you must create--at least--an icon list resource with resource ID -16455 and store it in the document's resource
fork. (To create this while your application is running, your application can call the AddResource procedure, described in the chapter "Resource Manager" in Inside Macintosh: More Macintosh Toolbox.) You can use the following constant in place of
the ID number:

CONST kCustomIconResource = -16455; {res ID for custom icon}

If you provide only an icon list resource, the Finder uses a black-and-white icon on all screen displays and automatically reduces it when a small version of the icon is required. To create color versions and to define a small version of the icon, create an entire icon family as described in "Creating Icons for the Finder" beginning on page 7-10.

After creating resources for icons using the kCustomIconResource constant as their IDs, you must set the hasCustomIcon bit in the file's Finder flags field. To prevent users from changing these icons, set the nameLocked bit in the file's Finder flags field. (Most development environments provide tools for setting these bits. "Using Finder Information in the Catalog File" beginning on page 7-30 describes how to determine
and set these Finder flags.)