TidBit #1 TidBit #1

Making OS 9 and X icons work in your single-binary, CFM, non-bundled app.
Last updated: 3/12/01

(Disclaimer: this worked for us, it might not work for you)

Doing these new icons are a real pain in the butt, when it shouldn't be. Finally, I got all the pieces I needed to make my application icons show up the way I wanted. Here's what I did:

(0) I am assuming you are a classic Macintosh developer, porting your app to Apple's new CarbonLib so it runs on X. But, you can't figure out how to make those snazzy big icons show up, and you don't want to "bundle" your app, you just want it to work.

(1) First, you need a nice icon into an 'icns' resource. To get this, there are two sources: (1) IconBuilder, but it's a Photoshop plug-in. It's pretty lame but does the job in a pinch; (2) Iconographer, a decent piece of shareware, and the best solution out there as far as I could tell. Search the net to find either one.

(2) Using sharp rocks, Photoshop and other tools, make your pretty 128x128 icon. Make sure to generate a mask as well.

(3) Paste these into a new untitled document in Iconographer, and set up all the icons as you wish, generating the 128x128 icons, all the way down to the 16x16 icons. I tried to wrangle a nicer icon into the smaller sizes, but it looked like crap and decided it wasn't worth it. So, we use our old application icons at the smaller sizes, and only use the new fancy icon in the 128x128 size.

(4) Save the stuff into a separate file, or if you prefer, directly into your app's resource file. Iconographer does both. If you choose the separate file approach, use your favorite resource editor to paste the 'icns' resource into your main resource file.One thing you need to do for sure: in your resource editor, change the 'icns' resource with the icons to be resource ID of -1000. This will be the ID that is checked by X for your icon, because we tell it that's where it's at (more on this later). Just do it.

(5) OK, you've got your icons prepped. How to get them to load on X? What you need is a plist. A waaa? Exactly. A plist is an XML-formatted hoochie-bangy that X will read and determine some characteristics about your app. It needs to be in a resource of type 'plst' and it MUST be resource ID 0 (zero). So, what I did is fire up my favorite text editor and typed this:

<plist version="0.9">
<dict>
<key>CFBundleInfoDictionaryVersion</key>
<string>6.0</string>
<key>CFBundleIdentifier</key>
<string>com.ChaoticSoftware.MP3Rage</string>
<key>CFBundleVersion</key>
<string>1.0</string>
<key>CFBundleDevelopmentRegion</key>
<string>English</string>
<key>CFBundleName</key>
<string>MP3 Rage</string>
<key>CFBundlePackageType</key>
<string>APPL</string>
<key>CFBundleSignature</key>
<string>????</string>
<key>NSAppleScriptEnabled</key>
<string>True</string>
<key>LSPrefersCarbon</key>
<string>True</string>
<key>CFBundleIconFile</key>
<string>-1000</string>
</dict>
</plist>

This is the plist for MP3 Rage. Change your CFBundleIdentifier and CFBundleName to be appropriate for your own application, of course. The only other thing you need to change CFBundleIconFile entry, making sure that the value is -1000. THIS MUST MATCH THE RESOURCE ID OF THE 'icns' RESOURCE THAT CONTAINS YOUR ICON, which you generated in step 4. I'm not going into the details of the other keys, I'll leave that up to an excercise for the reader. In fact, the "True" entries might not even be correct. I know they are optional, and I'm not certain that the format for them is exactly correct. Consult Mac OS X documention for the real scoop on the other entries. Also, you should change the "????" in CFBundle Signature to be the same as your application signature.

(6) To get this data into my app, I used Resorcerer. I created a new 'plst' resource, opened it, and simply cut and pasted this text into the data window. This was easy and effective, I suggest you try it. ResEdit might also work this way, but I didn't try it. You MUST make sure the resource ID for the 'plst' is also 0 (zero), or this will not work. Getting all the plist info was the biggest challenge in all this... covet the information.

(7) That's pretty much it. To reiterate, the following things must be present:

a. An 'icns' resource, at some resource ID XXX.
b. A 'plst' resource that is at resource ID 0 (zero).
c. The 'plst' resource must have a CFBundleIconFile entry that refers to your res ID of XXX.
d. Don't forget to have all the other crap for this to work, such as a 'carb' resource,at ID 0 and eight bytes of 0s.

One last thing: all of these icons and crap are cached away, so the finder is reluctant to show them to you. This was true on 9 a lot of the time, it's worse on X. Usually what I did was create a new admin user, to make sure everything was fresh, and then copy over the finished goods. That way I was pretty much guaranteed I was getting the latest stuff. I got bit by this a few times, so if you make changes and expect them to show up, don't be surprised when they don't. Logging in and out would not solve the problem for me either. Making a new account worked every time, so try that if you get desperate.

And one more bit of info I've seen: information in the 'plst' 0 resource apparently supersedes information in the corresponding (vers, open, FREF, BNDL, kind) resources. Make sure that you put all the information into your 'plst' resource, just to be safe.

Good luck!