Cocoa Dev Central

by Brock Brandeberg

Every good application should have an "about box" that displays the application version number, gives credit to the company and individual(s) that authored the software, and provides contact information so that the user may get in touch with the author if the need arises. Many times, especially in shareware, the application may change hands without being accompanied by any readme files or documentation, so the about box becomes a useful bit of information for both the end user and for the author who gains recognition from each impression.

In Apple's history, numerous terms have been used for what most users have come to know as an "about box." Throughout Apple's docs, you'll find references to "about boxes," "about windows" and "about panels," and it's good for a programmer to be familiar with them all so that it's possible to find documentation when needed. The term "about box" comes from the pre-Carbon days of the old dialog manager when the "About" command in the Apple Menu would bring up a dialog box. The term "about window" is a more recent term that is used in the Human Interface Guidelines. And the newest term, "about panel," is used in Cocoa because the window is implemented as a panel and instantiated with the NSApplication method orderFrontStandardAboutPanel: which we will talk about shortly.

In Cocoa, a standard about panel is very easy to implement and is more than sufficient for most applications' needs. And best of all, Cocoa does nearly all of the work for you.

// How The About Panel Works

In a Cocoa application, the "About MyApp" menu item is pre-wired to send the message orderFrontStandardAboutPanel: up the responder chain to NSApplication. When NSApplication receives the message, it goes about constructing an about panel with various sources of information that it gathers from the Info.plist file and from the Resources folder in the application bundle. You need only to make sure that you include the required pieces of information in your application, and you'll have a nice, custom about panel with no additional effort required.

Alternately, you can create and display the about box yourself programmatically with values determined at runtime using the orderFrontStandardAboutPanelWithOptions: message. This is more difficult and not the focus of our discussion here, but it's possible. What really happens when you use the pre-wired orderFrontStandardAboutPanel: method is that NSApplication receives the orderFrontStandardAboutPanel: message, then turns around and calls orderFrontStandardAboutPanelWithOptions: with a nil argument, which causes it to go looking for the pieces of information in the locations that we discuss below.

// Providing The Information

The standard about panel has places for the following pieces of information (current as of OS X 10.1.4):

Figure 1. A standard about panel

• Application Icon
  Uses the string value of the "CFBundleIconFile" key from the Info.plist file. You don't have to include the filename extension in this string value, but you can if you want. If you don't, Mac OS X is smart enough to search for a file of this name that ends with the ".icns" extension. If not available, uses the generic application icon.
• Application Name
  Uses the string value of the "CFBundleName" key from the Info.plist file (which is localizable). If not found, uses [[NSProcessInfo processInfo] processName]. This string is what is displayed in the menu bar when your application is active.
• Application Version String
  Uses the value of the "CFBundleShortVersionString" key from the Info.plist file. If not found, the build version, if available, is printed alone as "Version x.x.x". This string is useful for actual version identification, but can be thought of as the "marketing" version. As a result, it is typically a more general version number, such as 1.0, and can contain alpha characters with no ill side effects. This value is displayed in the Finder preview too.
• Build Version String
  Uses the value of the "CFBundleVersion" key from the Info.plist file. Displays the build version number of the application displayed as "(v1.0.0)". If not found, the version area is left blank (the "(v)" is not displayed). If version strings are used that conform to the traditional MacOS versioning format (ie 1.2.3d6), you can use the CFBundleGetVersionNumber() function to get this version number. This version is the more specific version number and reflects incremental builds.
• Credits
  Looks for a file named "Credits.html" in the bundle returned by the NSBundle class method mainBundle. If not found, looks for "Credits.rtf". If not found, looks for "Credits.rtfd". If not found, the credits area is left blank. "Credits.rtf" is only option available in OS X 10.0, so if you choose to use a RTFD or HTML format, you should also include a "Credits.rtf" file so that OS X 10.0 has a credits file to fall back on. Note that the capitalization of the file name is important. By using the HTML format, you can include links.
• Copyright
  Uses the string value of the "NSHumanReadableCopyright" key from the Info.plist file. If not found, the copyright area is left blank.

You set the key/value pairs of the Info.plist file in the target settings of your project in Project Builder. You create the application icon file and credits file(s) in external editors, then add them to the resources of your project in Project Builder.

To set the keys in the Info.plist file for the default localization in Project Builder, you will need to use the "Expert" option in the "Application Settings" tab of the target settings because the "Simple" option lacks text entry fields for some of the necessary keys. If a key does not yet exist, simply add one using the "New Sibling" button, type in the new key name, then double-click on its value to enter the new value or string. To become familiar with the difference between the "Simple" settings and the "Expert" settings, enter the values in the expert mode, then switch to the simple mode and try to locate the text entry fields that correspond to the Info.plist keys that you've entered. Of course, you can also edit the Info.plist file by hand.

Figure 2. Editing the Info.plist key/value pairs

To add the credits file(s) and icon file to your application, simply choose the "Resources" folder in the "Files" tab, then choose "Add Files..." from the "Project" menu. Select the credits file (or files if you are including multiple formats) and add it to the project, then do the same for the icon file. When adding files, you can choose the option to copy the files into the project folder if you wish to do so. By doing so, the files will travel with your project instead of being left in a location external to the project folder. However, if you're not attentive, you will end up with duplicate copies of files on your system - your originals and the ones you just copied into the project folder. For more information about the "Add Files..." options, check out the Project Builder documentation.

Figure 3. Credits and icon files added to the project

If you got the information in the right places, everything should just work. Build your application, run it and choose the "About MyApp" command in the application menu. If the about panel is missing something, go back and check the key/value pairs and your files very closely and make sure that the capitalization and spelling is correct. You can also view the package contents of your compiled application and make sure that the icon and credits files are being put in the right folders of the bundle. If not, you may have added the files to the wrong group in the Project Builder "Files" tab.

If you need more information about "bundles" and the way that they are structured, look at Inside Mac OS X: System Overview: Anatomy of a Bundle and at Core Foundation: Bundle Services in the Apple documentation. For more information and descriptions for most of the Info.plist key/value pairs, look at Mac OS X Developer Release Notes: Information Property List, but beware. The Apple docs have a number of inconsistencies regarding Info.plist keys. It seems that errors have crept in as changes have been made evolving away from the old NextStep naming conventions, so what's documented and what works may not always be the same. You'll likely find the right information somewhere, but it may be spread throughout several versions of release notes.

// Conclusion

So when we said that Cocoa does nearly all of the work for you, we weren't kidding. Simply put the information in the right spots and it all works. And as Cocoa evolves, Apple might add new features or options to the about panel, so you should keep an eye on the documentation for the NSApplication object since it's the object that's responsible for the about panel.