MacDevCenter.com

Help Yourself Help Others

by James Duncan Davidson
05/25/2001

Among the myriad features in Mac OS X is an integrated "help" system called Apple Help. Apple Help was introduced in Mac OS 8.5 as part of Carbon and has been updated in each system release since then.

The Help Viewer displays help content authored using the industry standard HTML 3.2 specification. This means that you can use your favorite tool, such as Dreamweaver or GoLive, to edit your documentation.

It can display any media supported by QuickTime which means that most of the major image formats are supported, as are videos and Flash content (such as the animation that welcomes you when you first launch Apple Help from the Finder). It uses Sherlock functionality to allow searching of a help book, or even all help books in the system. And, it can serve content from either the local system or over the Internet allowing frequently updated docs to be accessible to users.

As part of OS X, Apple Help comes with these new features:

An API for registering application help books with the system.
An API for calling into the Help Viewer from your application.
The ability to package Help into application bundles.

Recipe to add a help book to your app

To add a help book to your application requires following a simple recipe.

What tips do you have for building "help" functionality in Mac OS X applications?
Post your comments

More Apple Worldwide Developers Conference Coverage:

Jobs to Developers: 'A Problem or an Opportunity?'

Cocoa Vs. Carbon?

Java Plays Prominent Role at WWDC 2001

Mac Technologies Enabled for Java

Related Books:

Learning Cocoa

Learning Carbon

First, two keys must be placed in your application's Info.plist. These entries are the CFBundleHelpBookFolder key and the CFBundleHelpBookName key. The CFBundleHelpBookFolder points to the directory inside your application bundle's Resource directory that contains your help files. The CFBundleHelpBookName key contains the name of your help book's title. When these two keys are placed in your application's Info.plist file, they will look something like:

<key>CFBundleHelpBookFolder</key> <value> <string>MyCoolApp Help</string> </value> <key>CFBundleHelpBookName</key> <value> <string>MyCoolApp Help</string> </value>

There are two other keys that must be part of the Info.plist file, and that should be already set by your application. These are they CFBundleName and CFBundleIdentifier keys.

These keys are discussed in the book Inside Mac OS X: System Overview. Briefly, they let the system know the name of the bundle and give it an identifier to use when saving preferences and other information.

To finish the recipe of adding help to an application, you will need a bit of content. A very simple amount of content for your help would be a single index.html file containing the following HTML:

<html> <head> <meta name="AppleTitle" content="MyCoolApp Help"/> <title>MyCoolApp Help</title> </head> <body> <h1>Welcome to MyCoolApp's Help!</h1> <p>Content...</p> </body> </html>

The most important part of this file is the meta tag with a name of AppleTitle. This tag must contain a value that matches the value of the CFBundleHelpBookName key defined above in the Info.plist. Of course, for a real help system, you would want to provide quite a bit more content in the form of many more HTML pages, but for the sake of this example, we'll keep it simple.

Once you have these keys defined, and your help is copied into the correct directory in your Application's Bundle (this is easy enough to do if you are using Project Builder to build your application), then everything just works. When your application tells the system to display help (a feature built into Cocoa applications for free), then the Help Viewer will open up and show you the following page.

Screen shot of the help viewer.
Your basic help viewer page.

There is much more to providing effective help functions to your application. The Apple Help system allows your help to launch AppleScripts and to provide advanced hints to the indexing engine. This article is intended to give you the absolute basics to get started. You can find out all about it by reading the documentation that comes with the Developer Tools.

James Duncan Davidson is a freelance author, software developer, and consultant focusing on Mac OS X, Java, XML, and open source technologies. He currently resides in San Francisco, California.

Return to the Mac DevCenter.