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 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 menu is to add the property
AppleDockMenuto the application’s
Info.plistfile. See “Adding a Property to the Information Property List.”
Use the functions
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 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
kEventClassApplicationand 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 menu for your application Dock tile by doing the following:
Create a menu in Interface Builder.
Add a property to your application’s information property list to specify the name of the Interface Builder file that contains your 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 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 menu. (See Learning Carbon for information on using Interface Builder.) The 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. Figure 4-1 shows custom items for a 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 Figure 4-1 has the command
Figure 4-2 shows an Interface Builder Instances pane for the
TestDockMenu.nib file. This file contains two items, a menu for the Dock, named
DockMenu, and a submenu for the menu, named
Adding a Property for the Dock Menu
Follow these steps to add the
AppleDockMenu property to the information property list for your application.
Open your application’s project in Project Builder.
Click the Targets tab, then click the appropriate target in the Targets list.
Click the Application Settings tab, then click Expert.
Click the New Sibling button.
AppleDockMenuin the Property List column.
Make sure the class is set to string.
In the Value column, type the name of the Interface Builder nib file that contains the Dock menu object, but do not include the
Figure 4-3 show an information property list as it appears in Project Builder. Note the value of the
AppleDockMenuproperty 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.
Build and run the application.
Using the Application Dock Tile Menu Functions
If your application is not a bundle or if it needs to create the application’s menu at runtime, then you can use the functions
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.
SetApplicationDockTileMenu increments the reference count of the menu you pass to it. Before the menu is displayed, it receives the Carbon events
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 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 Listing 4-1.
Listing 4-1 Passing a menu reference to the function SetEventParameter
err = SetEventParameter (inEvent,
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—
kMenuIconResourceType. If your application uses a standard system icon provided by Icon Services, you should use the selector
kMenuSystemIconSelectorType, as shown in Listing 4-2. To load the icon, you need to call the Icon Services function
Listing 4-2 Using a standard system icon in the application Dock Menu
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 Listing 4-3. 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 4-3 Using an icon specified in a .icns file
(Handle) CFSTR("mySpecialIcon.icns") );