Creating a Dock Tile Plug-in

Starting in OS X v10.6, you can customize an application’s Dock tile icon and menu when the application is not running. For example, you may want to update the badge text to indicate that new content will be available the next time the application is launched. Similarly, you may want to provide a customized menu based on the content available for the user. To do this, you create a Dock tile plug-in and associate it with your application. The application’s plug-in is loaded automatically when the application is added to the Dock.

A Dock tile plug-in is intended only to update the Dock tile icon and menu. A Dock plug-in should not block the main thread and should minimize the processing it performs. If you need to perform significant background processing, you should create a background-only application that communicates with your Dock tile plug-in.

You should be familar with the tasks described for Cocoa applications because many of the same concepts are used by Dock tile plug-ins. See Dock Tile Tasks for Cocoa Applications for more information.

Creating the Plug-in

A Dock tile plug-in is a loadable bundle. For more information about creating loadable bundles, see Code Loading Programming Topics.

The Dock tile plug-in must be placed inside the Contents/PlugIns directory of your application’s package. The plug-in is associated with the application by adding a NSDockTilePlugIn key to the application’s information property list. The value associated with this key is the name of the plug-in’s bundle, which must end with a .docktileplugin extension.

The principal class of the plug-in must implement the NSDockTilePlugIn protocol. The setDockTile: method is the only required method in this protocol. When the plug-in is loaded, an object of the principal class is instantiated, and its setDockTile: method is called. The call to this method provides an NSDockTile object to your plug-in. Your plug-in should retain the Dock tile object and perform any other initialization required by your plug-in. For example, if your plug-in receives information from a background-only application, it can register for a notification event sent by that other application.

Your Dock tile plug-in continues to run as long as your application’s tile is in the Dock, even if your application is actually running. Apple recommends that you update your Dock tile in either the application or the plug-in, but not both at the same time. Your application can continue to update the Dock tile inside your plug-in by having the plug-in receive notifications from your application. If both the application and the plug-in update the dock tile, the application takes precedence.

When your application is removed from the Dock, the setDockTile: method is called with a nil parameter. Your setDockTile: method should remove any strong references to the Dock tile object, clean up any resources your Dock Tile plug-in allocated, and exit.

Changing the Dock Tile Icon

When your application needs to customize the Dock tile, it manipulates the NSDockTile object that was provided to the initial call to the setDockTile: method.

Providing a Custom Menu in a Plug-in

Your class can optionally provide a dockMenu method to provide additional custom menu items. This method works similarly to the applicationDockMenu: method provided by the application delegate. OS X calls your plug-in’s dockMenu method when the user requests the menu for your Dock tile.