The procedures for modifying the menu bar in Interface Builder are similar to those you used to modify the main window in Chapter 4:
In this section, you’ll modify the menu bar so it’s customized for the Moon Travel Planner application. You’ll do the following:
Disable the items you won’t need.
Set up the items the application needs.
Add an application-specific menu to the menu bar.
Add code to your project to create the menu bar.
Test the menus.
Let’s take a look at the default menu bar and disable any items you won’t need for the Moon Travel Planner application. The application won’t provide the ability for users to create new files, so you can disable the New menu item in the File menu. Users will be able to choose Open, Close, and Save As commands from the File menu. But you’ll disable Revert and Save. The Moon Travel Planner won’t provide any editing capabilities, so you’ll disable the items in the Edit menu.
Open the menu bar by clicking main.nib in the Resources group of the Moon Travel Planner project, then double-click the MainMenu icon in the Instances pane.
Disable each unneeded item by following these steps:
Click a menu (such as File) to open it.
Click the item in the menu you want to disable.
Choose Show Info from the Tools menu.
Choose Attributes from the pop-up menu.
Make sure Enabled is not selected, as shown in Figure 7.12. When an item is not enabled, it appears dimmed to the user.
You must assign a command to every menu item your application makes available to the user. A command must:
Consist of four characters
Have at least one uppercase character (Apple reserves the use of commands that are all lowercase characters.)
Be unique within your application
When a user chooses a menu item from a menu, the Menu Manager issues the command you assigned to it. The Carbon Event Manager passes the command to your application to handle. Then, your application calls the function that handles it.
It takes two steps to get a menu item working for your application: assigning the command and writing the code to handle it. In this section you’ll add commands for each menu item you’ll use in the Moon Travel Planner. You’ll write the code to process commands in other parts of this book.
Note
As you assign a command to a menu item, make a note of it. You’ll need to refer to a command when you write the code to handle it.
The About command will open a window that displays version and copyright information for the application.
Click the NewApplication menu, then double-click the About NewApplication menu item.
Type
About Moon Travel Planner.Choose Show Info from the Tools menu.
Choose Attributes from the pop-up menu.
Assign
aBtbas the command. In the Command section, typeaBtbin the text field (as shown in Figure 7.13) and press Return.
The Open command will allow users to open a file that contains a suggested itinerary for a trip to the moon. Because the user will only be able to open files that have a special itinerary type, you should first change the name of the Open menu item to Open Itinerary, then add a command.
Click the File menu, then double-click the Open menu item.
Type
Open Itinerary...and press Return. The ellipsis indicates to the user that more information is required to carry out the command. In this case, the ellipsis indicates a dialog will appear.Assign
oPitas the command. From the pop-up menu at the top of the Menu Item Info window, choose Attributes. In the Command section, typeoPitin the text field, and press Return.
Users should be able to close and open an itinerary, or save an itinerary under a different file name. Add these commands to the Close and Save As menu items:
Enter
cLseas the Close menu item’s command.Enter
sAitas the Save As menu item’s command.
In Chapter 8 you’ll create a window (Facts for the Traveler) that displays facts for those considering travel to the moon. You should add page setup and print commands to allow users to print the facts. Add these commands to the Page Setup and Print menu items:
Enter
pGsuas the Page Setup menu item’s command.Enter
pRntas the Print menu item’s command.
In Chapter 12 you’ll add a help book to the Moon Travel Planner application, write code that registers the help book, and set properties that specify the help book name and folder. Mac OS X automatically sets up a Help menu and names the Help menu item based on the properties you set. In our case, the Help menu item will be named Moon Travel Planner Help. The operating system also handles the command issued when the user chooses Moon Travel Planner Help from the Help menu. So there is no need for us to use the Help menu provided by Interface Builder. You must delete it, otherwise your application will have two Help menus:
Click the Help menu.
Press Delete.
Not everything an application needs is in the default menu bar; you usually need to add at least one application-specific menu. You can find help for designing an application-specific menu in Inside Mac OS X: Aqua Human Interface Guidelines.
You already know from the Moon Travel Planner specification (see Chapter 2) that you need to add an application-specific menu called Moon. The Moon menu should have two menu items—Compute Travel Time and Show Facts. The Compute Travel Time menu item will issue the same command issued by the Compute Travel Time button in the main window. The Show Facts menu item will issue a command that opens a window to display enticing facts about the moon as a tourist destination.
You’ll use the Menus palette to add a new menu to the default menu bar:
In Interface Builder, choose Palettes from the Tools menu, then click the Menus icon (the circled icon in Figure 7.14) in the palette’s toolbar.
Drag a Submenu object from the Menu palette to the space between the Edit and Window menus, as shown in Figure 7.15.
Name the menu
Moon. Double-click the word Submenu, typeMoon, and press Return.Name the Item
Compute Travel Time. Double-click the Item menu item, typeCompute Travel Time, and press Return.Assign Command-K as the
Compute Travel Timemenu item’s keyboard equivalent. Click the menu item and choose Show Info from the Tools menu, then typeKin the Key text field of the Menu Shortcut box as shown in Figure 7.16.Enter
tRavas the menu item’s command. TypetRavin the Command text field of the Menu Item Info window and press Return. When the user chooses Compute Travel Time, the Carbon Event Manager sends thetRavcommand to your application. In Chapter 6 you wrote the handler that takes care of thetRavcommand issued by the Compute Travel Time button in the main window. Note the menu item uses the same command. As long as the main window is active when the user chooses the Compute Travel Time item from the Moon menu, the handler takes care of the command. It doesn’t matter whether the menu or the button issues the command.Add a new item to the Moon menu. Drag an Item object from the Menu palette to the space below the Compute Travel Time menu item, as shown in Figure 7.17. When the Item is over a “legal” spot, the pointer changes to show a small + sign and a line appears at the location where the Item is placed.
Name the menu item
Show Facts. Double-click the Item menu item, typeShow Facts, and press Return. In most cases, a menu item should be written as an action so it’s clear to the user what happens when the item is chosen. Although the window’s title is Facts for the Traveler, we’ve named the menu item Show Facts.Assign Shift-Command-F as the Show Facts menu item’s keyboard equivalent. Click the Show Facts menu item, then type Shift-Command-F in the Key text field of the Menu Shortcut box.
Note
You should assign Shift-Command-F rather than Command-F, because in some applications, Command-F is used for the Find command. Although you could use this equivalent here because the Moon Travel Planner application doesn’t have a Find command, it’s not recommended. Using common keyboard equivalents in an uncommon way could make your application less intuitive for users accustomed to the commonly used combinations.
Enter
fActas the menu item’s command. TypefActin the Command text field of the Menu Item Info window and press Return.Save the nib file. Make sure your changes are saved before you add code to the Moon Travel Planner project.
You need to add code to the main function of the Moon Travel Planner project to create the menu bar from the nib file you modified and to handle the commands issued by menu items.
Project Builder already provides code that creates the menu bar from the nib file when your application launches. Let’s take a look at that code:
Make Project Builder active by clicking its icon in the Dock.
Look at the two lines of code in the
mainfunction in themain.cfile, just after theCreateNibReferencestatement. The Interface Builder Services functionSetMenuBarFromNibtakes two parameters, a nib reference and aCFStringobject. You pass the nib reference returned from the functionCreateNibReference(see Chapter 3). You use the functionCFSTRto convert the string “MainMenu” to aCFStringobject. The string you provide must match exactly the name of the menu object in the Instances pane of Interface Builder.SetMenuBarFromNibreads the menu bar definition from the nib file, allocates memory for it, creates it, and sets it as the current menu bar. The functionrequire_noerrexits the application if there is an error that prevents the menu bar from being created from the nib file.
Although there are a number of commands that need to be handled by your application, you won’t write the code for them in this chapter. You’ll do that throughout the book, as follows:
About Moon Travel Planner (
aBtb). See Chapter 10.Open Itinerary (
oPit). See Chapter 11.Close (
cLse). You’ll write code to close the itinerary window in Chapter 11, the Facts for the Traveler window in Chapter 8, and the About window in Chapter 10.Save Itinerary As (
sAit). See Chapter 11.Page Setup (
pGsu). You already set up handling this command in Chapter 6 but in Chapter 9 you’ll write the functions that do page setup.Print (
pRnt). You already set up handling this command in Chapter 6 but in Chapter 9 you’ll write the functions that do the printing.Compute Travel Time (
tRav). You already set this up in Chapter 6.Show Facts (
fAct). See Chapter 8.
In the meantime, you can build and run the application, but the commands that aren’t yet handled won’t do anything.
Let’s build and run the application to make sure the Moon menu looks okay and the Compute Travel Time menu item works:
Click the Build button in the upper-left corner of the Moon Travel Planner project window.
Click the Run button in the upper-left corner of the project window.
Click a mode of transportation.
Choose Compute Travel Time from the Moon menu. Does the value in the Travel Time field change? If so, you are ready to move on!
Choose Quit Moon Travel Planner from the Moon Travel Planner menu.
You’ve taken a look at the default menu bar provided by Interface Builder and at the items in each of the menu bar’s menus. You’ve seen that some items, such as edit items, come “prewired” with commands, while other items you need to set up for your application. If an application needs menus or menu items other than the default ones, you can create new ones using the Menu palette. It’s also possible to disable menu items your application doesn’t need.
You created a new menu and menu items and adjusted the default menu items for the Moon Travel Planner application. You also saw that a command issued by a button in the interface can also be issued from a menu item (Compute Travel Time). Next you’ll take a look at localization and, in particular, how to set up an application so it’s easy to make available in multiple languages or for multiple locations.