Moon Travel Planner: Adding Help

Let’s add a help book and a help tag to the Moon Travel Planner application. Since Moon Travel Planner is small and easy to use, a simple help book (without chapters) is sufficient. A help book is included with the materials for this book.

To add the help book and a help tag to the Moon Travel Planner application, you must do the following:

  1. Add the Moon Travel Planner help book to the project.

  2. Modify the property list so it includes the help book name and folder.

  3. Register the help book.

  4. Write a help tag.

Add the Help Book to the Project

The Moon Travel Planner help book needs to be added to the language-specific folder, English.lproj, and then added as a resource to the Moon Travel Planner application:

  1. In the Finder, copy the Moon Travel Planner Help folder to the English.lproj folder in the Moon Travel Planner folder. Use the help book provided with the Moon Travel Planner materials (see the the preface for information on how to obtain the materials).

  2. Open the Moon Travel Planner project in Project Builder.

  3. Add the Moon Travel Planner Help folder to the Moon Travel Planner project. Choose Add Files from the Project menu, select the Moon Travel Planner Help folder, and click Open. Select “Create Folder References for any added folders” and click Add. Project Builder adds the folder as a resource if you’ve selected this option.

  4. If you need to, drag the Moon Travel Planner Help folder to the Resources group.

Modify the Application’s Property List

In this section you’ll add two entries to the application’s property list so Apple Help can locate the Moon Travel Planner help book. The first entry consists of the CFBundleHelpBookFolder key with a string value identifying the folder for your help book. The second entry consists of a CFBundleHelpBookName key with a string value specifying the help book’s title, as defined in your title page file (the help’s home page). Together, the entries assure that when the user chooses Moon Travel Planner Help from the Help menu, Help Viewer opens to the title page of the Moon Travel Planner help book.

When you include the CFBundleHelpBookFolder property in your property list, Carbon automatically provides a Help menu for your application. This is why you deleted the Help menu in Chapter 7. You don’t need the Help menu provided by Interface Builder.

Follow these steps to modify the Moon Travel Planner property list:

  1. Click the Targets tab, then click Moon Travel Planner in the Targets list.

  2. Click the Application Settings tab, then click the Expert button.

  3. Create an entry for the help book folder name. Click New Sibling, type CFBundleHelpBookFolder as the property name, and press Return. Then double-click the Value column, type Moon Travel Planner Help as the property value, and press Return.

  4. Create an entry for the help book name. Click New Sibling, type CFBundleHelpBookName as the property name, and press Return. Then double-click the Value column, type Moon Travel Planner Help as the property value, and press Return.

Register the Help Book

When the Moon Travel Planner application launches, it should call a function to register the help book. Once the help book is registered, it appears in the Help Center. In this section, you’ll add code to register the help book.

First, you need to declare the registration function you’ll use. In the main.c file in your Moon Travel Planner project, type the following statement before the main function, just after the event and command handler declarations:

               OSStatus MTPRegisterMoonTravelHelp (void);

Next, you’ll create the function. The function needs to provide the application bundle to the Apple Help function that does the actual registration. Copy the code shown in Example 12.3 to the bottom of the main.c file.

Example 12-3. The Function for Registering the Help Book

OSStatus MTPRegisterMoonTravelHelp (void)
{
  CFBundleRef   myAppsBundle;
  CFURLRef      myBundleURL;
  FSRef         myBundleRef;
  OSStatus      err = 0;
  
  myAppsBundle = NULL;                                              // 1
  myBundleURL = NULL;

  myAppsBundle = CFBundleGetMainBundle();                           // 2
 if (myAppsBundle == NULL) { err = fnfErr; goto bail;}              // 3
  myBundleURL = CFBundleCopyBundleURL(myAppsBundle);                // 4
 if (myBundleURL == NULL) { err = fnfErr; goto bail;}
  CFURLGetFSRef (myBundleURL, &myBundleRef);                        // 5
 if ( ! CFURLGetFSRef(myBundleURL, &myBundleRef) )
{ 
        err = fnfErr;
        goto bail;
    }
  err = AHRegisterHelpBook (&myBundleRef);                          // 6
 if (err != noErr) goto bail;
    CFRelease (myBundleURL);                                        // 7
    return noErr;                                                   // 8
    bail:
        if (myBundleURL != NULL) CFRelease(myBundleURL); 
        return err;
}

Here’s what the function does:

  1. Sets up a known state you can check against when you do error checking throughout the function.

  2. The Core Foundation Bundle Services function CFBundleGetMainBundle returns a reference to the application’s main bundle.

  3. This statement, and others like it in this function, check to make sure something other than NULL is returned. If NULL is returned, the err is set to indicate a “not found” error, and the function jumps to the bail statement.

  4. The Core Foundation Bundle Services function CFBundleCopyBundleURL returns the location of the bundle.

  5. The Core Foundation URL Services function CFURLGetFSRef returns the file specification reference (FSRef) for the bundle URL.

  6. The Apple Help function AHRegisterHelpBook registers the help book associated with the application.

  7. The Core Foundation Base Services function CFRelease releases the memory associated with myBundleURL.

  8. If all goes well, the function exits here. Otherwise, the bail statement executes, the function releases the memory associated with myBundleURL, and returns an error.

Your application needs to call the MTPRegisterMoonTravelHelp function when the application starts up. You should add this statement just before the statement RunApplicationEventLoop:

MTPRegisterMoonTravelHelp();

Add a Help Tag

Now that you have provided help pages for your Moon Travel Planner application, you will learn how to provide hints to the user through help tags. For the purposes of this tutorial, we will create a tag for the graphic in the Moon Travel Planner window:

  1. Make the Moon Travel Planner project window active. Click the Project Builder icon in the Dock.

  2. Open the main.nib file. Double-click the main.nib file in the Resources list.

  3. Open the Moon Travel Planner window. Double-click the MainWindow icon in the Instances pane.

  4. Open the Picture Info window. Click the graphic in the Moon Travel Planner window, then choose Show Info from the Tools menu.

  5. Add a help tag to the graphic. Choose Help from the pop-up menu in the Picture Info window.

    Displaying help information for a control

    Figure 12-3. Displaying help information for a control

  6. Write the help tag content. In the Text field shown in Figure 12.4, type Luna, satellite of the earth.

  7. Specify the help tag location. Choose Default from the Display Side pop-up menu, as shown in Figure 12.4.

    Choosing a location for a help tag

    Figure 12-4. Choosing a location for a help tag

Make Sure Help Works Properly

You need to make sure that the Moon Travel Planner help book opens and the help tag you added appears. Let’s build, run, and test the application.

  1. Click the Build button in the upper-left corner of the Moon Travel Planner project window.

  2. Click the Run button in the upper-left corner of the project window.

  3. Choose Moon Travel Planner Help from the Help menu. Does Apple Help Viewer open? It should look like the page shown in Figure 12.5.

    The first page of Moon Travel Planner Help

    Figure 12-5. The first page of Moon Travel Planner Help

  4. Click the Moon Travel Planner main window to make it active.

  5. Place the pointer over the graphic. In a few seconds you should see the help tag appear. Does it look similar to the one shown in Figure 12.6?

    The help tag for the moon picture

    Figure 12-6. The help tag for the moon picture

  6. Move the pointer off the picture. The tag should disappear.

  7. Click Quit.

If everything worked, you’re ready to move on!

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset
18.116.21.152