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 menu for your application Dock tile.
To add static menu items to the 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 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’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
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
[[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
[[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
[[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.
Launch Interface Builder.
Create a new nib file for your menu.
Create a menu that includes the items you wish to add to the menu.
dockMenuoutlet 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 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.