---

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 toggleToolbarShown: and runToolbarCustomizationPalette:. (Note that NSWindow automatically 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.

• A custom controller class in awakeFromNib or, for document-based applications, an NSDocument subclass in windowControllerDidLoadNib: completes the following steps for each toolbar it uses:

  1. It makes a new NSToolbar object using initWithIdentifier:.

  2. It sets attributes of the toolbar if the defaults won’t do using setAllowsUserCustomization:, setAutosavesConfiguration:, and setDisplayMode:.

  3. It sets the toolbar’s delegate (usually itself).

  4. It associates the toolbar with a window by sending the NSWindow object a setToolbar: message.

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.

1. 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 NSToolbar object’s autosavesConfiguration attribute 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.

2. The window asks for each NSToolbarItem object (by identifier) to insert into the toolbar.

   • To add each toolbar item to the toolbar, the NSToolbar object sends toolbar:itemForItemIdentifier:willBeInsertedIntoToolbar: to the delegate.

     If the NSToolbarItem object is image-based, get the image from the application bundle (for example, by using the NSImage class method 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 minSize and 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 toolbarWillAddItem: notification method.

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 setAction: method of NSToolbarItem. Also set the target by calling the setTarget:, usually passing in self.

• 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 NSToolbarItem for the item and override the validate method.

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 toolbarAllowedItemIdentifiers: and 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.

---