Dock Tile Tasks for Cocoa Applications

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

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

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’s Dock 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];
[[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];

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"];

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.

Adding Static Menu Items With a Nib File

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

  1. Launch Interface Builder.

  2. Create a new nib file for your menu.

  3. Create a menu that includes the items you wish to add to the menu.

  4. Connect the dockMenu outlet of the file’s owner (which by default is NSApplication) to your menu.

  5. Add the nib name to the Info.plist, using the key AppleDockMenu. The nib name is specified without an extension.

Dynamically Adding Menu Items With the Application Delegate

An application can also provide items dynamically to your application’s Dock tile’s 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.