< Previous PageNext Page > Hide TOC

Dock Tile Tasks for Carbon Applications

There are two things you can do to customize your application’s Dock tile—modify the Dock icon or add custom items to the Dock menu. If you want to modify your application’s Dock icon see the Tiler sample application.

You should also see the Application Manager Reference for a description of the functions you can use to modify and restore your application’s Dock icon.

This chapter shows you three ways you can add custom menu items to the contextual menu for your application’s Dock tile.

• Add a property to the application’s information property list. If your application is a bundle and only needs to add static menu items, then the easiest way to add custom items to the contextual menu is to add the property AppleDockMenu to the application’s Info.plist file. See “Adding a Property to the Information Property List.”

• Use the functions SetApplicationDockTileMenu and GetApplicationDockTileMenu. If your application is not a bundle or if it needs to create the menu at runtime, then you can use these functions to set and retrieve the items in the menu. See “Using the Application Dock Tile Menu Functions.”

• Handle the Dock tile menu event. If your application needs to create the contextual menu at the time the user clicks the application’s icon in the Dock, you can set up a handler to handle the associated Carbon event—event class kEventClassApplication and event kind kEventAppGetDockTileMenu. See “Handling the Get Dock Tile Menu Event.”

Regardless of the method you use to customize your application Dock menu, each custom menu item must have a command ID, or the application won’t be notified by the Carbon Event Manager when that item is selected.

If you want to add an icon to an item in your application Dock menu, see “Adding an Icon to a Dock Menu Item.”

Adding a Property to the Information Property List

You can customize the contextual menu for your application Dock tile by doing the following:

1. Create a contextual menu in Interface Builder.

2. Add a property to your application’s information property list to specify the name of the Interface Builder file that contains your contextual menu.

Once you do this, Carbon automatically loads the nib file, creates the menu, and provides it to the Dock. Each step is detailed in the following sections.

Creating a Contextual Menu in Interface Builder

You should open Interface Builder from your application’s Project Builder file, then create a new nib file just for your contextual menu. (See Learning Carbon for information on using Interface Builder.) The contextual menu needs to contain only those items you want to add to your application’s Dock menu; standard items (see “Dock Menu”) are added automatically. “Setting the command for a custom item in a contextual menu” shows custom items for a contextual menu that’s being built in Interface Builder.

Each menu item needs to have an associated four-character command that’s unique to your application. The command is what the Carbon Event Manager provides to your application to let you know which item was chosen by the user. The Next Song menu item in “Setting the command for a custom item in a contextual menu” has the command NEXT.

Figure 3-1  Setting the command for a custom item in a contextual menu

“Menu objects for a Dock menu” shows an Interface Builder Instances pane for the TestDockMenu.nib file. This file contains two items, a contextual menu for the Dock, named DockMenu, and a submenu for the contextual menu, named Submenu.

Figure 3-2  Menu objects for a Dock menu

Adding a Property for the Dock Menu

Follow these steps to add the AppleDockMenu property to the information property list for your application.

1. Open your application’s project in Project Builder.

2. Click the Targets tab, then click the appropriate target in the Targets list.

3. Click the Application Settings tab, then click Expert.

4. Click the New Sibling button.

5. Type AppleDockMenu in the Property List column.

6. Make sure the class is set to string.

7. In the Value column, type the name of the Interface Builder nib file that contains the Dock menu object, but do not include the .nib extension.

   “The AppleDockMenu property” show an information property list as it appears in Project Builder. Note the value of the AppleDockMenu property is the string TestDockMenu. This implies the name of the nib file that contains the Dock menu items is TestDockMenu.nib. You must make sure the value you add matches the name of the nib file you create for your Dock menu.

8. Build and run the application.

Figure 3-3  The AppleDockMenu property

Using the Application Dock Tile Menu Functions

If your application is not a bundle or if it needs to create the application’s contextual menu at runtime, then you can use the functions SetApplicationDockTileMenu and GetApplicationDockTileMenu to set and retrieve the items in the menu.

You can use any method (for example Interface Builder or Menu Manager functions) to define and create a menu that contains your custom items. Regardless of how you create the menu, each menu item needs to have an associated four-character command that’s unique to your application.

Once the menu is created, you pass a reference to your menu to the function SetApplicationDockTileMenu. The items in the menu you pass to the function are inserted in the list, between the list of document windows and the standard items.

The function SetApplicationDockTileMenu increments the reference count of the menu you pass to it. Before the contextual menu is displayed, it receives the Carbon events kEventMenuPopulate, kEventMenuOpening, and kEventMenuEnableItems, so any event handlers for these events can update the menu appropriately.

Handling the Get Dock Tile Menu Event

If your application needs to create the contextual menu at the time the user clicks the application’s icon in the Dock, you can set up a handler to handle the Carbon event that is of event class kEventClassApplication and event kind kEventAppGetDockTileMenu. The default handler for this event returns the menu provided by SetApplicationDockTileMenu or the menu located in the nib file for the Dock menu, if it exists.

You can override the default handler by writing and installing your own Carbon event handler. Your application needs to create the custom menu and your handler needs to call the Carbon Event Manager function SetEventParameter with the Carbon event parameter kEventParamMenuRef and a reference to the menu you want to be displayed, as shown in “Passing a menu reference to the function SetEventParameter.”

Listing 3-1  Passing a menu reference to the function SetEventParameter

        err = SetEventParameter (inEvent,

                        kEventParamMenuRef,

                        typeMenuRef,

                        sizeof(menuRef),

                        &myCustomApplicationDockMenu

                        );

Carbon releases the menu reference after the menu is passed to the Dock, so be sure to retain the menu reference with the Menu Manager function RetainMenu if you want to keep the menu reference for later use.

Adding an Icon to a Dock Menu Item

If you want to display an icon next to an item in your application Dock menu (as shown in Figure 1-4) you need to call the function SetMenuItemIconHandle with one of the new selectors provided by the Menu Manager—kMenuSystemIconSelectorType or kMenuIconResourceType. If your application uses a standard system icon provided by Icon Services, you should use the selector kMenuSystemIconSelectorType, as shown in “Using a standard system icon in the application Dock Menu.” To load the icon, you need to call the Icon Services function GetIconRef.

Listing 3-2  Using a standard system icon in the application Dock Menu

SetMenuItemIconHandle (myMenu,

                        1,

                        kMenuSystemIconSelectorType,

                        (Handle) kGenericApplicationIcon);

If you application uses a .icns file located in the application bundle, you should use the selector kMenuIconResourceType with the function SetMenuItemIconHandle, as shown in “Using an icon specified in a .icns file.” The inIconHandle parameter to this function must be a CFStringRef that specifies the name of the .icns file. The Menu Manager locates the file and registers the IconRef for the icon specified in the file, and then displays the icon with the menu item. The CFStringRef is retained by the Menu Manager.

Listing 3-3  Using an icon specified in a .icns file

SetMenuItemIconHandle (myMenu,

                        2,

                        kMenuIconResourceType,

                        (Handle) CFSTR("mySpecialIcon.icns") );

< Previous PageNext Page > Hide TOC