Toolbar Management Checklist
Before you begin coding:
If you have image-based toolbar items, find or create the images (in the proper size and aspect ratio) and add them to your project as a resource.
If you have view-based toolbar items, create each view in Interface Builder, specify an outlet for a custom controller object, and connect the view to the outlet.
If the view is an off-the-shelf palette object, just make an outlet connection.
Specify or (for default toolbar items) identify the unique string identifiers that you intend to use for toolbars and toolbar items.
Add to an application menu (usually named View) the menu items Show Toolbar and Customize Toolbar..., connect these to the First Responder icon in the nib file window, and select the actions
runToolbarCustomizationPalette:. (Note that
NSWindowautomatically changes “Show Toolbar” to “Hide Toolbar” as appropriate.)
For further information, see “Adding and Removing Toolbar Items.”
What happens: The application launches or a document is created or opened, causing a nib file to be loaded and its object unarchived.
It sets the toolbar’s delegate (usually itself).
It associates the toolbar with a window by sending the NSWindow object a
For further information see “Adding and Removing Toolbar Items”
What happens: The
NSToolbar object begins communicating with its delegate in order to populate the toolbar with toolbar items.
The window gets the allowed and default toolbar item identifiers:
The toolbar object calls the delegate method
toolbarAllowedItemIdentifiers:to get the total set of possible toolbar items.
Unless it finds the default toolbar configuration in user preferences, the toolbar calls the delegate method
toolbarDefaultItemIdentifiers:to get the default set.
To have the default configuration saved to and read from user preferences, the
autosavesConfigurationattribute must be set.
If certain toolbar items should indicate a selected state, the delegate should implement
toolbarSelectableItemIdentifiers:to return the identifiers of those toolbar items.
The window asks for each
NSToolbarItemobject (by identifier) to insert into the toolbar.
To add each toolbar item to the toolbar, the
toolbar:itemForItemIdentifier:willBeInsertedIntoToolbar:to the delegate.
NSToolbarItemobject is image-based, get the image from the application bundle (for example, by using the
imageNamed:) and send
setImage:to the toolbar item. Also set the toolbar item’s label, palette label, target, and action. You may also set a menu form representation.
If the toolbar item is view-based, send
setView:to the toolbar-item object, passing in the outlet to the view. Also set the toolbar item’s label, palette label, its minimum size (
minSize), and its maximum size (
maxSize). (If you do not set a
maxSize, the view does not appear because it is sized to zero in both dimensions.) You may also set a menu form representation.
If the delegate wants to customize a toolbar item before it is added, it can also implement the
For further information see “Adding and Removing Toolbar Items,” “Setting a Toolbar Item’s Representation,” “Setting a Toolbar Item’s Size” and “Setting a Toolbar Item’s Size.”
What happens: Users click toolbar items; the runtime context of the application changes.
Declare and implement action methods for each of your custom toolbar items, usually in a custom controller class.
When you create a toolbar item you can identify the selector of each of these methods through the
NSToolbarItem. Also set the target by calling the
setTarget:, usually passing in
Validate toolbar items.
If the toolbar item is image-based, the target of an action should implement
validateToolbarItem:if it wants validation more specialized than the default. If the toolbar item is view-based, you should create a subclass of
NSToolbarItemfor the item and override the
For further information, see “Validating Toolbar Items.”
What happens: The user chooses the Customize Toolbar menu item.
As the customization sheet opens, the toolbar object calls the delegate methods
toolbarDefaultItemIdentifiers:. Then as the toolbar adds each toolbar item to the customization palette, it sends to the delegate if the item kind is custom image or custom view.
When the user adds an item to the toolbar, the toolbar invokes the delegate method
toolbar:itemForItemIdentifier:willBeInsertedIntoToolbar:; if a new instance of the toolbar item is needed, the toolbar sends
toolbarWillAddItem:to the delegate just before it adds the item.
Just after the user removes an item from the toolbar, the toolbar sends
toolbarDidRemoveItem:to the delegate.
When the user drags the default set to the toolbar, the toolbar reuses as many items already in the toolbar as possible, calling
toolbarDidRemoveItem:for the items it needs to remove and calling
toolbarWillAddItem:for the ones it needs to add.
Note that the toolbar does not call any delegate methods when the user closes the customization sheet.