Dock Tile Tasks for Cocoa Applications

Cocoa applications can customize both the application's Dock Icon and a minimized window’s Dock icon.

The simplest way to customize the application’s Dock icon is to provide a new image to replace the default application icon. See “Customizing the Application’s Dock Icon.”
To change a window’s Dock icon, or to dynamically change the application's Dock Icon, you can draw a Dock icon using a custom view. See “Using a Custom View to Draw a Dock Icon.”
To add text to a Dock icon, you can apply a badge label. See “Changing the Text of a Badge Label.”
To remove the application badge from a window’s Dock icon, see “Hiding the Application Icon Badge on a Window’s Dock Tile Icon.”

Your application can also customize the contextual menu for your application Dock tile.

To add static menu items to the contextual menu, you provide a menu in a nib file and reference this nib file inside your application’s Information Property List. See “Adding Static Menu Items With a Nib File.”
To dynamically change the menu when the user clicks in the Dock, provide an applicationDockMenu: function in your application’s delegate. See “Dynamically Adding Contextual Menu Items With the Application Delegate.”

Customizing the Application’s Dock Icon

While your application is running, you can call the setApplicationIconImage: method of the NSApplication object to directly change the application Dock tile icon.

myImage = [NSImage imageNamed: @"ChangedIcon"];

[NSApp setApplicationIconImage: myImage];

To restore your application’s original icon, you call setApplicationIconImage: with a nil parameter:

[NSApp setApplicationIconImage: nil];

Using a Custom View to Draw a Dock Icon

Dock tile icons can be customized using an NSView object. This is useful if your application needs to dynamically generate Dock tile icons at run time. To provide a custom view, you instantiate a new view object, retrieve the dock tile object from the application or window object, and set your view as its contentView.

myView = [[[MyViewClass alloc] init] autorelease];

[[NSApp dockTile] setContentView: myView];

When the Dock icon needs to be updated, you instruct the Dock to update the icon by calling the dock tile object’s display method.

[[NSApp dockTile] display];

Note: When a window’s dock tile object has a custom view, no application badge is provided. You are responsible for all content except for the badge label.

Changing the Text of a Badge Label

The dock tile object can overlay a short text message on top of the Dock icon. To change the badge label, you call the Dock tile’s setBadgeLabel: method.

[[myWindow dockTile] setBadgeLabel:@"42"];

Note: A window’s Dock tile may only include a badge label if has a custom content view.

Hiding the Application Icon Badge on a Window’s Dock Tile Icon

By default, a window’s Dock icon consists of a miniaturized image of the window’s contents with a badge of the application's Dock Icon layered on top of it. This includes any customized icon you may have provided for the application’s Dock icon. You can optionally turn off the application badge by calling the setShowsApplicationBadge: method.

[[myWindow dockTile] setShowsApplicationBadge: NO];

The application’s Dock Tile icon does not show an application badge, and ignores attempts to show one.

Note: If the window’s dock tile object has a custom view, the application badge is not provided, and the dock tile will ignore this method.

Adding Static Menu Items With a Nib File

If your application needs to add static items to the application’s Dock tile’s contextual menu, you can provide those items in a nib file. To do this, perform the following steps.

Launch Interface Builder.
Create a new nib file for your menu.
Create a menu that includes the items you wish to add to the contextual menu.
Connect the dockMenu outlet of the file’s owner (which by default is NSApplication) to your menu.
Add the nib name to the Info.plist, using the key AppleDockMenu. The nib name is specified without an extension.

Dynamically Adding Contextual Menu Items With the Application Delegate

An application can also provide items dynamically to your application’s Dock tile’s contextual menu. To do this, your application’s delegate object provides a applicationDockMenu: method. This method returns a NSMenu object that provides all the custom menu items you wish to add to the menu. If you also provided a menu using a nib file (see “Adding Static Menu Items With a Nib File”), any menu returned by your delegate replaces the menu provided in the nib file.

< Previous PageNext Page >

Hide TOC

Did this document help you?
Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.