Volume Number: 15 (1999)
Issue Number: 5
Column Tag: ToolBox Techniques

Tune-up your Application with Icon Services

by Craig Hockenberry, Chief Typist, The Iconfactory

Techniques for adding 32-bit icons to your application

Many new, exciting technologies were introduced in Mac OS 8.5. One of the most overlooked is the Icon Services API. With the introduction of Icon Services, many common tasks, such as showing icons for the desktop, have become much simpler.

The architecture of the Icon Services API is based on a data abstraction for icons. Instead of using handles to icon data (as was the case with Icon Utilities), Icon Services relies on an icon reference. The icon reference is a truly opaque data type used in many useful API functions for managing and displaying the iconic data.

In this article, I'll focus on how to implement the new icons within an existing application framework which is based on handles to icon suites, not icon references. These techniques were used when the Iconfactory upgraded its popular IconDropper software to support 32-bit icons (see Figure 1). I'll also show some techniques for making sure that your icons are Appearance-compliant.

With a small amount of work, you can update your application and make it look much better with Mac OS 8.5 and beyond.

Icon Services provides the developer with a host of new features. The following are some of the highlights:

The icons look better! 32-bits rock!

The most obvious benefit to using Icon Services is its capability to display 32-bit icons. The full RGB color space makes smooth gradients and realistic looking shadows a snap to design. The new icon format also allows an 8-bit mask for varying levels of transparency.

That's the technical explanation. It's also OK to just say that the new icons look cool and are much easier on the eye, as shown in Figure 2.

Consistency of icons throughout all applications

A less obvious benefit of Icon Services is its ability to deal with the icon as an opaque data type. This allows Icon Services to cache the icon data across all applications (including the Finder.)

In previous incarnations of the Mac OS, the Finder maintained its own cache of icons from the desktop database. Other applications did not have access to this cache, so many developers had to implement their own schemes for keeping track of desktop icons.

The cache managed by Icon Services is completely accessible by your application. And, best of all, the cache is automatically updated when the user switches to a different theme or scheme. You don't have to do anything to be Appearance-compliant.

One thing you need to be careful of when dealing with the cache, is managing the reference counts. I'll cover this in more detail when we get to the example code.

Easier to code, especially with file and folder icons

One of the most tedious tasks in previous versions of the Mac OS was getting the icon for an item on the desktop. This seemingly simple task involved reading Finder info, the desktop database and custom icon resources.

With Icon Services, getting the icon is as simple as supplying a type/creator code or a FSSpec. Hundreds of lines of code are replaced with a few simple calls to the API.

A single icon resource type

Anyone who's dealt with icon suites knows the joy of dealing with the multitude of handles for each of the icon sizes and depths. Icon Services encapsulates all these icon types into a single resource, the 'icns' resource. Icon Services uses the term icon family when referring to this resource.

Dealing with one handle is obviously simpler than dealing with a dozen or more handles.

Having all the icon data in one resource also has a less obvious benefit: it decreases network traffic when you are reading the icon resources off a volume that is not local. A dozen file accesses over a network takes much longer than just one.

There are a couple of things to be wary of when dealing with the new icon resources:

BNDL resources are still 256 colors

The bundle resource has not been changed in Mac OS 8.5. Changing the BNDL would cause previous versions of the Finder to crash when mounting a volume with the new icons.

So what does this have to do with Icon Services? It means that your application and document icons will still be restricted to 256 colors and 1 bit masks. The new 32-bit icon format is not supported in the desktop database.

Copy and paste compatibility problems

As developers, we sometimes use custom icon resources to "pretty up" Read Me files and other files in a distribution. Be aware that copying and pasting an icon in Mac OS 8.5 will only copy the new icon resource ('icns') and not the older resources. The result is that a user on an older version of the OS will not see the custom icon.

Appearance Manager can only handle icon suites

The new Appearance Manager only allows icon suites in the new control resource parameters. Unfortunately, there is no way to specify an icon family for your beveled buttons or icon panes, so some resource conversions are required.

I'll present solutions to these problems later on in this article.

Now that we've gotten the boring bits out of the way, let's get down to the interesting stuff: code to do icons.

Useful header files and libraries

Before getting started with Icon Services, there are a few things that you should setup in your development environment.

To use Icon Services, new header files and a stub library are required. You'll find everything you need in the Universal Interfaces 3.2, which can be downloaded from Apple's website (http://developer.apple.com/sdk).

All of the new definitions and declarations for Icon Services are found in "Icons.h". If you're dealing with custom icons or other Finder information, you'll also find "Finder.h" useful.

You also need to link in the IconServicesLib stub library. Again, this is found in the Universal Interfaces 3.2 distribution. Make sure that the library is linked weak or you'll get errors when running on a system before Mac OS 8.5. In CodeWarrior, you set this attribute by setting "Import Weak" in the project inspector.

Note that Icon Services is only supported on Mac OS 8.5, so you should only link the library in your PPC target. I'll discuss some strategies for dealing with older versions of the Mac OS later on in this article.

Checking Gestalt

Before calling any of the entry points in Icon Services, you should make sure that it's supported. This is simple to do with a call to Gestalt:

// check if Icon Services is available
Int32 gestaltResult;
OSErr osErr = Gestalt(gestaltIconUtilitiesAttr,
      gestaltResult);
if (osErr != noErr)
{
   useIconServices = false;
}
else
{
   useIconServices = (gestaltResult &
         (1L << gestaltIconUtilitiesHasIconServices)) != 0;
}

If Icon Services is not available, you can fall back on Icon Utilities for managing and displaying icons.

Plotting a file or folder's icon

Let's start off with a simple example to display an icon for an item using its file specification.

The first thing to do is get the icon reference for the item:

FSSpec theItem;
// set theItem to a file or folder you want to display

IconRef theIconRef;
SInt16 theLabel;
osErr = GetIconRefFromFile(&theItem, &theIconRef, &theLabel);

Now, let's plot the icon reference:

Rect theRect;
// set theRect to the drawing coordinates

IconAlignmentType theAlignment = kAlignNone;
IconTransformType theTransform = theLabel;   

osErr = PlotIconRef(&theRect, theAlignment, theTransform,
      kIconServicesNormalUsage, theIconRef);

That's all you need to plot the icon. But there's one last step that's very important; you need to release the icon reference:

osErr = ReleaseIconRef(theIconRef);

This final step is important because it decrements a usage counter for the Icon Services cache. When this use count reaches zero, the memory for the item in the cache is released.

You don't have to worry about disposing of the icon resources yourself, but if you forget to release the icon reference, the usage count will never reach zero and you'll end up with a memory leak.

One of the challenges I was faced with when upgrading our applications to Icon Services was backward compatibility. Since Icon Services is only supported on Mac OS 8.5, I needed to find a way to handle the icon data with both old and new versions of the OS.

Luckily, there are some simple ways to handle the icon data in both old and new formats.

Resource ids in existing code

In some cases, your application will reference the icon by its resource ID. When this is the case, you only need to change the way in which that resource ID is drawn.

The following code (Listing 1) is a snippet from a modified version of PowerPlant's LIconPane class. The DrawSelf member function has been modified to plot a 32-bit icon if Icon Services is available. If Icon Services is not available, the PlotIconID function from Icon Utilities is used to display the icon.

Listing 1: CIconPane::DrawSelf()

CIconPane::DrawSelf()
Plot 32-bit icon using resource id if Icon Services is available, else
use Icon Utilties.

void
CIconPane::DrawSelf()
{
   OSErr   osErr;
   
   Rect   frame;
   CalcLocalFrameRect(frame);

   // check if Icon Services is available
   bool useIconServices;
   Int32 gestaltResult;
   osErr = Gestalt(gestaltIconUtilitiesAttr, &gestaltResult);
   if (osErr != noErr)
   {
      useIconServices = false;
   }
   else
   {
      useIconServices = (gestaltResult &
            (1L << gestaltIconUtilitiesHasIconServices)) != 0;
   }

   // get the file spec for the current process if necessary
   FSSpec appSpec;
   if (useIconServices)
   {
      ProcessSerialNumber appPSN;
      ProcessInfoRec appPIR;
      
      appPSN.highLongOfPSN = 0;
      appPSN.lowLongOfPSN = kCurrentProcess;
      
      appPIR.processInfoLength = sizeof(ProcessInfoRec);
      appPIR.processName = nil;
      appPIR.processAppSpec = &appSpec;
      
      osErr = ::GetProcessInformation(&appPSN, &appPIR);
      if (osErr != noErr)
      {
         useIconServices = false;
      }
   }
   
   if (useIconServices)
   {
      // plot the icon with Icon Services
      IconRef iconRef;
      ::RegisterIconRefFromResource('Icnp', 'TEMP', &appSpec,
            mIconID, &iconRef);
      ::PlotIconRef(&frame, kAlignNone, kTransformNone,
            kIconServicesNormalUsageFlag, iconRef);
      ::ReleaseIconRef(iconRef);
      ::UnregisterIconRef('Icnp', 'TEMP');
   }
   else
   {
      // plot the icon with Icon Utilities
      ::PlotIconID(&frame, kAlignNone, kTransformNone, 
            mIconID);
   }
}

Note that the behavior of this class is a little different than the original LIconPane. CIconPane will only search the application's resource fork (via the appSpec). PlotIconID, on the other hand, will search through the resource chain as it looks for mIconID.

It's also important to note the first two parameters of RegisterIconRefFromResource(), the creator and type. Typically, these will be derived from your application's creator and types. In the above example, I've used a creator code that matches the PowerPlant class identifier and a type of 'TEMP'. This was done so that the class could be used in any project. Be aware that this method will only work for "temporary" icon references since the type and creator are the primary indexing method for the icon cache.

The full source code for this PowerPlant class is available for download from the MacTech FTP site. The demonstration project also includes other classes which show various features of Icon Services.

Don't forget the resources!

As with all these strategies for backward compatibility, you need to make sure that you include resource data in both old and new formats.

For older systems, you'll be including 'ICN#', 'icl8', etc. For the 32-bit icons, you'll need to add the 'icns' resource type (with the same resource ID as the corresponding ICN# data).

I'll talk a little about creating these new resource types at the end of this article.

Handles to icons suites in existing code

The example above works well for "static" icon data. But an approach based on resource ids will not work for icons that are dynamic (in a Finder-like list view, for example). In this case, you have to maintain a reference to the icon data in the object instance.

For applications that are going to be used only on Mac OS 8.5 or later, the best approach is to keep an IconRef as member data in the list object. This allows you to take advantage of the caching built into the OS and reduces the memory requirements of the object instance.

Unfortunately, most of us have to build applications that work on older versions of the OS.

The solution to this problem is coercing data types based upon the presence or absence of Icon Services. In the case of Icon Services, the IconRef data type is a pointer to an opaque structure. Icon Utilities uses a Handle for an icon suite. Both data types can be represented as a 32-bit data value.

First we need to define the member data. The choice of data type is arbitrary; since my classes which handle icons were previously based on Icon Utilities, it was easiest to leave them defined as Handle:

Handle mIconData;

Getting the icon will vary depending on the needs of the application. The following will load mIconData with the icon for theItem file specification. The icon is a reference to the Finder icon when Icon Services is present and handle containing a generic document or folder icon when it isn't:

FSSpec theItem;
// set theItem to a file or folder you want to display

if (useIconServices)
{
   // get the icon for the item using Icon Services
   IconRef theIconRef;
   SInt16 theLabelColor;
   ::GetIconRefFromFile(&theItem, &theIconRef, 
         &theLabelColor);

   mIconData = (Handle) theIconRef;      
}
else
{
   // get a generic icon for the item

   // note that this is a very basic approach, see the sample source
   // code for more comprehensive solutions

   CInfoPBRec cpb;
   cpb.hFileInfo.ioVRefNum = theItem.vRefNum;
   cpb.hFileInfo.ioDirID = theItem.parID;
   cpb.hFileInfo.ioNamePtr = theItem.name;
   cpb.hFileInfo.ioFDirIndex = 0;
   ::PBGetCatInfoSync(&cpb);

   Sint16 theResId;
   if ((cpb.hFileInfo.ioFlAttrib & ioDirMask) == 0)
   {
      // use generic document icon
      theResId = kGenericDocumentIconResource;
   }
   else
   {
      // use generic folder icon
      theResId = kGenericFolderIconResource;
   }

   ::GetIconSuite(&mIconData, theResId,
         kSelectorAllAvailableData);
}

Note that the code to load the generic icon suite is very simplistic. A more comprehensive solution involves poking around in the desktop database and reading custom icon resources. James W. Walker's Find Icon library contains many useful routines which abstract this arcane procedure. This library is available from Info-Mac.

Once you've loaded the appropriate data into mIconData, you can plot the icon:

Rect iconFrame;
IconAlignmentType iconAlign;
IconTransformType iconTransform;
// set up iconFrame, iconAlign and iconTransform according to your needs

if (useIconServices) {
   ::PlotIconRef(&iconFrame, iconAlign, iconTransform,
         kIconServicesNormalUsageFlag, (IconRef) mIconData);
}
else
{
   // plot the icon with icon utilities
   ::PlotIconSuite(&iconFrame, iconAlign, iconTransform,
         mIconData);
}

When you are done using the icon data, you need to free it:

if (useIconServices)
{
   ::ReleaseIconRef((IconRef) mIconData);
}
else
{
   ::DisposeIconSuite(mIconData, true);
}

Please note that the memory overhead for the two cases above is very different. When you are using Icon Services, your object instance's overhead is a single 32-bit pointer. When using Icon Utilities, you'll have 2-3k of data in the mIconData handle.

Appearance compliance for free

One of the nicest things about the previous example is that it's fully Appearance-compliant on Mac OS 8.5. If theItem is a folder or other system icon, the display of the item will update as the user changes the theme or scheme.

This happens because the icon data is actually in the Icon Services cache. The cache gets updated automatically and the next time you reference the icon, you get the updated icon the next time your interface is redrawn. Very cool.

In the previous discussions, we've been focusing on the get, display and dispose aspects of icon data.

In the following sections, we'll discuss some other uses for Icon Services in your application:

Getting a handle from the reference

There are cases where you may need to manipulate the icon data. Since your application only has a reference to the icon, you don't have any "real" data to manipulate.

If your application requires a handle to manipulate, you can convert the icon reference into an icon family:

IconRef iconRef;
// set iconRef using one of the techniques shown above
IconFamilyHandle iconFamily;
::IconRefToIconFamily(iconRef, kSelectorAllAvailableData,
      &iconFamily);

The iconFamily will contain all versions of the icon available in the iconRef. The handle contains the same data as an 'icns' in a resource file.

If you need to convert the icon family into an icon suite, you can use the following:

IconSuiteRef iconSuite;
::IconFamilyToIconSuite(iconFamily,
      kSelectorAllAvailableData, &iconSuite);

The icon suite which is created can be used with the normal Icon Utilities functions. If you've supplied a selector for all available data, you'll probably get the following resource types in the icon suite:

• il32 - Large 32-bit icon
• l8mk - Large 8-bit mask
• is32 - Small 32-bit icon
• s8mk - Small 8-bit mask

Many of the functions in Icon Utilities will ignore these new resources. However, you will get them as resource types in your callback for a ForEachIconDo() call. This can be useful for extracting individual elements of the icon family.

Creating icon resources from PICT data

I'm now going to cover a cool entry point that is not included in the latest Icon Services documentation (Preliminary Draft of 6/17/98, available from http://developer.apple.com/macos/8.5.html#icon).

The SetIconFamilyData call can be used to create an icon using a PICT. This will be useful if you are developing an application where you want to attach a preview of a graphic as a custom icon for the document.

This is a common technique for giving the user an idea of what's in the document without having to open it. In many cases, this can save the user lots of time, especially when dealing with large graphics files.

In previous versions of the Mac OS, you had to do it all yourself (and get down and dirty with the pixels of GWorlds and icon handles). With Icon Services, it can be done with two lines of code:

PicHandle pictHandle;
// set pictHandle according to the needs of your application
IconFamilyHandle iconFamily =
      (IconFamilyHandle) NewHandle(0);
SetIconFamilyData(iconFamily, 'PICT', (Handle) pictHandle);
// the iconFamily now contains an icon generated from the PICT

Pretty tough, huh?

Once you have created the icon family, you can save the handle as 'icns' with a custom icon resource id (-16455).

If you need compatibility with older versions of the OS, you can create an icon suite using IconFamilyToIconSuite() as described above. The callback function for ForEachIconDo() can write out the individual icon resources for the icon suite ('ICN#', 'icl8', etc.)

After all the custom icon resources are set up in the file's resource fork, make sure to set the Finder flag for custom icons and let the Finder know about the update. The quickest way to update the icon on the desktop is by sending a kAEUpdate AppleEvent to the Finder, although bumping the file modification date will also work.

You should also call FlushIconRefsByVolume() if you change the icon of a file or folder. This allows Icon Services to update the cache on the specified volume (which should match the vRefNum of the custom icon's FSSpec). If the icon is registered with a type and creator, FlushIconRefs() should be called.

The BNDL problem

You might be thinking: "Cool! Now I can have a 32-bit icon for my application and its documents". Sorry to disappoint you, but this isn't easy.

The reason is that the desktop database needs to be compatible across all versions of the Mac OS. If you have a server with Mac OS 8.5, you want older clients to be able to access its desktop database. If that database relies on the new icon resource format, bad things will happen.

There is a simple solution to this problem, at least for the application icon. At the Iconfactory, we have been creating 32-bit icons for our applications and setting the custom icon before shipping the product. The end-user sees a beautiful icon and there are no BNDL incompatibilities.

This trick can also be extended to documents and other data files. You can place a 32-bit custom icon on each file after writing it out to disk. This is a little more work, but can produce very pleasing results.

Another workaround to the BNDL problem is to register 32-bit icons when your application starts up using the RegisterIconRefFromIconFamily() or RegisterIconRefFromResource() entry points. The registered icons will override the desktop database entries. If you use this method, make sure you unregister the icons when your application terminates.

Be careful with cut and paste in Get Info

When you are working with custom icons in Mac OS 8.5, there's something important to keep in mind. Any custom icons that you cut and paste using Get Info will not be readable by older versions of the OS.

The reason is that only the new icon resources ('icns') are copied and pasted. So don't be surprised when you take your new release, open it up on an older OS, and see a bunch of generic icons.

At the Iconfactory, we have been using our IconDropper software to work around this problem. It has the ability to set custom icon resources that are compatible with all versions of the Mac OS. We also find that using IconDropper makes preparing a release much faster since we can update the icons in the distribution in much less time than with Get Info.

Using 32-bit icons with the new Appearance controls

The new 32-bit icon resources can be used with the Appearance Manager. However, the way the icons are accessed is different, so some resource juggling is necessary.

When you specify an icon suite in your CNTL definition, the 'icns' resource is not used. You must extract the individual icon resources out of the 'icns' and treat them as an icon suite (ie. you need to have a 'il32' and 'l8mk' data in your resource file.)

Another problem is that Appearance can't handle 'il32' resources that are compressed. Unfortunately, this is the default way of storing the data in the 'icns' resource so you can't just copy and paste in a resource editor.

To handle these problems, I've written a drag and drop utility that will convert the 'icns' resource automatically. This utility is available to registered users of our IconBuilder software (described next).

So far, I have been talking about 32-bit icons without regard to how they are produced. In the early days of Mac OS 8.5, there weren't any publicly available tools to create them graphically. The only tool available was Resourcerer 2.2 which allowed you to edit the hexidecimal values in the 'icns' resource.

Today, the situation is much better, and there are several tools available to create the necessary resources:

• clip2icns by Mihai Parparita <http://www.mscape.com/products.html> Clip2icns creates 32-bit icons using a graphic from the clipboard. You can use any external bitmap editor and Mac OS 8.5 is not required. The cost to register the software is $10.
• Export Icon by Kinetic Creations <http://www.kineticcreations.com/exporticon/moreInfo.html> Export Icon is a Photoshop export filter that creates icon family resources from a document or layer. Mac OS 8.5 is required. The cost to register is $15.
• Icon Machine by David Catmull <http://www.dathorc.com/iconmachine.html> Icon Machine is a standalone icon editor. Version 2.0, which supports 32-bit icons, is currently in development. Contact the author for further information.
• IconBuilder by The Iconfactory <http://www.iconfactory.com> IconBuilder is a Photoshop plug-in that creates all icon resource types (including 32-bit resources). It relies on Photoshop to edit the icon data. Mac OS 8.5 is required. Cost is $49.

All of the icons that come from the Iconfactory are being built using IconBuilder. We originally created this utility for in-house use only. We released it to the public after many requests from graphic artists looking for a way to create 32-bit icons in their editor of choice. The Iconfactory make a lot of icons, either to give away or for clients, and IconBuilder has made our life much easier.

We are currently working on an update which will allow IconBuilder to create icons for Windows (a necessary evil) and Mac OS X (oh yeah!)

So there you have it. With a little bit of work, you can dramatically improve the look of your user interface with nice-looking icons and Appearance compliance. In addition, many of the previously complex tasks involving icons have become much simpler with Icon Services.

Please be sure to examine the demonstration application available by FTP. The code snippets used in this article are placed in context and can easily be adapted to your own application.

Thanks go to Arno Gourdol for reviewing this article and answering many questions about Icon Services.

Craig Hockenberry is the chief typist at The Iconfactory, the leading source of quality freeware icons for the Mac (they also do custom design work for clients such as Adobe, Apple and the Cartoon Network). When he's not abusing his keyboard, he's probably fixing his bungalow or chatting with his fellow workers.