Mac OS X 10.1 Dock Menu Description and APIs
Mac OS X 10.1 Dock Menu Description and APIs
- Subject: Mac OS X 10.1 Dock Menu Description and APIs
- From: John Geleynse <email@hidden>
- Date: Wed, 15 Aug 2001 09:56:25 -0700
Cocoa Developers,
Recently there've been some questions about Dock menus in Mac OS X 10.1.
Dock menus are the Mac OS X 10.1 equivalent of the Mac OS 9 ControlStrip and
main menu bar 3rd party menus.
Allow me to take a moment and go into detail about when these should be
used, and provide you with preliminary information about the APIs
themselves. The new APIs are available in the Puma 5E and 5F builds
(depending on whether or not you want support in Carbon or Cocoa).
Many of you have been asking for a mechanism to provide global access to
certain features provided by your application and this is the way to do it.
Please note that the system menus area of the main menu bar is not being
made available to 3rd party developers and is reserved by Apple. The Dock is
intended to be the point of entry for 3rd party developers providing this
type of global access functionality.
Essentially what's available to you now is a mechanism for associating and
updating a menu and it's items off of a Dock tile. Whether the Dock tile
belongs to your actual applications or to some faceless background
application is for you to decide. However, since your code needs to be
"running" in order to "know" that the menu was chosen you may want to have
your application, or a help application, launch as a startup/login item,
faceless and with no menubar etc. When a menu item is selected requiring UI
you can then bring up/launch your application with UI Etc. No official API
*yet* exists for this login related stuff but sample code for how to do this
on Mac OS X 10.0.x is available by contacting Developer Technical Support
<email@hidden>.
So here are some details about the APIs themselves, quoting from the release
notes:
In Puma 5F, NSApplication has added support for applications to specify the
contents of the application dock menu. This allows an application to add
menu items below the list of windows in the dock menu.
An application can either specify an NSMenu in a nib, or return an NSMenu
from a delegate method.
To specify an NSMenu in a nib, add the nib name to the info.plist, using the
key AppleDockMenu. The nib name should be specified without an extension.
There will be an IB outlet from NSApplication named dockMenu, which should
be connected to the NSMenu in the nib. This menu should be in its own nib
file so that it can be loaded lazily when the dockMenu is requested, rather
than at launch time.
There is also an application delegate method to allow a delegate to specify
the menu dynamically. If the delegate returns non-nil for this menu, it
takes precedence over the dockMenu in the nib. Because this method is
invoked whenever the dockMenu is to be shown, efficiency is important. The
delegate should keep its own internal representation of the dock menu up to
date rather than updating when this method is invoked.
- (NSMenu *)applicationDockMenu:(NSApplication *)sender;
The target and action for each menu item is passed to the dock. On
selection of the menu item, the dock messages the application, which invokes
[NSApp sendAction:selector to:target from:nil].
The current implementation does not yet support adding an image to a
menuItem or changing the menu title based on modifier keys, which are both
features desired in the dockMenu.
I trust this information proves valuable to those of you interested in this
topic.
John Geleynse
User Experience Technology Manager
Apple Worldwide Developer Relations