Every Carbon application must support menus—the standard ones supplied by Mac OS X and those your application provides. Menus allow users to view or choose from a list of choices any commands or attributes provided by your application. You can add application-specific menus and customize many of the standard menu items to suit your application’s needs.
The easiest way to create, display, and set up the behavior of pull-down, hierarchical, and contextual menus is to use Interface Builder. It provides you with a menu bar that’s already loaded with the standard menus and items. To set up the menus for your application, do the following steps:
Modify the default menu bar by:
Disabling the items your application doesn’t need
Preparing the items your application needs
Adding application-specific menus and menu items
Add code to your project to:
Call Interface Builder Services to create the menu bar from the nib file
Process the menu commands
In this chapter, you’ll:
Look at a typical menu bar for an application running on Mac OS X
Go through the menu bar provided by Interface Builder to see which items are set up for you and which ones you need to prepare
Discuss hierarchical and contextual menus
Modify the menu bar for the Moon Travel Planner application
The Mac OS has a menu bar with a number of standard menus and menu items that should appear in any application. Figure 7.1 shows the menu bar for the Finder on Mac OS X. The Apple menu on the left is always present. The menu to the right of the Apple menu is the Application menu; it takes the name of the application that’s running. On Mac OS X, the Finder is an application, so the menu is named Finder. The Application menu, along with the menus called out to the right of it, make up an application’s menus. Some are standard, such as File, Edit, Window, and Help, while others are specific to the application. The View and Go menus are specific to the Finder.
When the user opens a menu from the menu bar, they see a pull-down menu, as shown in Figure 7.2. Menus should have a one-word title that represents what’s in the menu. The ellipsis character indicates the user must supply more information after choosing the item. In the case of the Go to Folder command, the user is presented a dialog and must choose or type a location. Menu items that aren’t followed by an ellipsis character indicate the item will issue a command when it’s chosen. Menu items should do something (such as save a file, show a movie) or change an attribute (such as change the font size).
A keyboard equivalent provides an alternative to choosing an item from the menu. Mac OS X reserves certain keyboard combinations as equivalents to menu commands; these shortcuts affect all applications. As long as a combination isn’t reserved, you can assign it to a menu item. You can find a complete list of reserved keyboard equivalents in Inside Mac OS X: Aqua Human Interface Guidelines in Carbon Help (available in the Project Builder Help menu).
The menu bar provided with Interface Builder (shown in Figure 7.3) is a template you’ll modify to suit the needs of your application. Interface Builder automatically includes standard menus—Application, File, Edit, Window, and Help. (If you open Interface Builder and the menu bar isn’t open, double-click the MainMenu icon in the Instances pane.)
In this section, we’ll go through each menu in the menu bar to see what you get “free” with Interface Builder. As you go through each menu, you’ll see that some items are already wired to do something, while others you’ll need to assign a command to and then provide the code that gets invoked by the command. Once you see what’s in the menu bar, we’ll take a look at two other types of menus you can create: hierarchical and contextual menus.
The Application menu contains items that apply to your application as a whole, rather than to a specific document or window. Figure 7.4 shows the Application menu template as it looks in Interface Builder. The template contains the only item you can modify, About NewApplication. When a user chooses the About menu item, it should issue a command that opens your application’s About window to display version and copyright information. You have to do a few things to make the menu item issue a command and open the About window: assign the item a command (which you’ll do later in this chapter), write code to open the About window, and create the window (which you’ll do later in Chapter 10).
When your application actually runs, the Application menu will contain all the standard items (such as Quit) shown in Figure 7.5 in addition to the About item. The operating system automatically includes the other items for you.
The File menu contains commands that can be applied to a document. The standard File menu is shown in Figure 7.6. In most cases, each command should apply to a single file. The commands are necessary for any application that is document-centered. If you write an application that doesn’t use documents and for which none of the File menu commands apply, you can disable the items in the File menu.
None of the File menu items are configured to do anything. For each item your application plans to provide to the user, you must assign a command and then implement the minimum expected behavior for that item by calling the appropriate functions from the Carbon programming interface. The commands must be programmed by you to do the following:
Open. Displays the standard dialog so the user can open an existing document.
Close. Closes the active window. If it’s a window in which the user has made changes, you should provide an opportunity to save changes. In a single-window application, closing the window should not quit the application.
Save. Saves the active document and leaves the document open.
Save As. Opens a dialog to let the user enter a new filename for the active document, saves a copy of the active document with the new user-defined name, and leaves the original document open.
Page Setup. Opens a dialog in which the user can specify printing parameters, such as size and orientation.
Print. Opens a dialog for specifying printing options, such as printer, page range, and number of copies.
Later in this book, we’ll show you how to write code to implement Open, Close, Save, Save As, Page Setup, and Print.
Commands that allow users to change or edit the contents of a document or to move data between applications are in the Edit menu. The editing commands use a system utility—the Clipboard—for temporary storage of data that’s cut or copied from a document. Data remains on the Clipboard until the user replaces the contents with a new cut or copy operation. Figure 7.7 shows the Edit menu you get with Interface Builder.
Note
If you need to see what’s on the Clipboard, go to the Finder and choose Show Clipboard from the Edit menu.
Unlike the File menu, every item in the Edit menu is already assigned a command. You need to implement the following standard behavior:
You don’t need to implement the following items for a text field added using Interface Builder. The commands will behave as follows automatically. However, if you are developing an application that provides more sophisticated text handling, you will need to implement them. For example, if you are using the Multilingual Text Engine functions provided in Carbon, you will need to handle these commands:
Some Edit items might not always be appropriate. For example, if no action has been taken by the user, then Undo should not be enabled. It should appear dimmed to the user. Your application must implement code that enables and disables menu items appropriately.
The Window menu provides commands for managing multiple document windows. Figure 7.8 shows a Window menu with two items, Minimize and Arrange in Front. When an application runs, the menu also lists the application’s open document windows and those windows that are minimized.
The Minimize and Arrange in Front items are already assigned commands and are set up to behave as follows:
If your application provides onscreen help (and it should), the Help menu is always the rightmost menu. The first item is the name of the application and the word “Help” (Moon Travel Planner Help, for example). If you plan to provide users with a standard Apple help book for your application, you won’t need to use Interface Builder’s Help menu. In fact, as you’ll see later in this chapter, you’ll need to delete the Help menu, as the Help menu and handling the Help menu item comes “for free” with the use of a standard Apple help book.
However, if you plan to provide help in a form other than a standard Apple help book, you’ll need to use Interface Builder’s Help menu. You’ll also need to assign commands to Help menu items and implement code to open help for your application.
You can use hierarchical menus to offer additional menu item choices without taking up more space in the menu bar. When the user points to a menu item that has a submenu indicator, a submenu appears. Submenus have all the features of menus, including keyboard equivalents, status markers (such as checkmarks), icons, and so on. Figure 7.10 shows a hierarchical menu.
The default menus provided by Interface Builder do not include any hierarchical menus. You can easily add one by dragging a submenu object from the Menus palette. See Chapter 5 for more information on the Menus palette.
A contextual menu is one that appears next to an item when the user presses the Control key while clicking the item. The contextual menu provides convenient access to often-used commands associated with the item. Figure 7.11 shows the Finder’s contextual menu for the Clock utility.
If you use a contextual menu in your application, include a small subset of the most commonly used commands in the appropriate context. You can add a contextual menu using the menu object provided in Interface Builder’s Menu palette.