3.8 Toolbars

Cocoa implements toolbars in the NSToolbar and NSToolbarItem classes. NSToolbar implements the toolbar itself, while NSToolbarItem represents the individual icons and controls within the toolbar.

Unfortunately, as of the December 2002 release of the Developer Tools, toolbars cannot be created within Interface Builder. Instead, you have to create them manually with code.

To create a toolbar, instantiate an instance of NSToolbar and initialize it with the method initWithIdentifier:. The identifier in this method is a string that identifies the toolbar within an application (it is used, for example, in document-based applications to reflect changes in a toolbar in one document window in all the toolbars of all open document-windows). To attach a toolbar to a window, invoke NSWindow's setToolbar:; the toolbar method of NSWindow returns a window's assigned toolbar.

NSWindow provides a two action methods for interacting with toolbars. The method toggleToolbarShown: hides and shows the toolbar. This is the action for the "Hide Toolbar" menu item (as well as the pill-shaped button on the right side of the window's title bar). Note that toggleToolbarShown: causes the title of this menu item to alternate between "Hide Toolbar" and "Show Toolbar". This method relies on NSToolbar's isVisible and setVisible: methods. isVisible returns YES if the toolbar is present, and NO otherwise; setVisible: takes a BOOL indicating whether the toolbar should be hidden or shown.

NSWindow's runToolbarCustomizationPalette: method is the action method for the "Customize Toolbar..." menu item. It uses NSToolbar's runCustomizationPalette: and customizationPaletteIsRunning methods. The runCustomizationPalette: opens a sheet for the customization palette and dismisses the sheet when the user is done.

NSToolbarItem represents the buttons, icons, and controls within a toolbar. The initWithItemIdentifier: method initializes instances of NSToolbarItem. The item identifier is a string that uniquely identifies the toolbar item. The Application Kit provides a number of standard toolbar items, such as the "Colors" and "Fonts" items, as well as separator and space items. Passing one of the string constants listed in Table 3-3 creates these standard toolbar items.

NSToolbarSeparatorItemIdentifier

NSToolbarSpaceItemIdentifier

NSToolbarFlexibleSpaceItemIdentifier

NSToolbarShowColorsItemIdentifier

NSToolbarShowFontsItemIdentifier

NSToolbarCustomizeToolbarItemIdentifier

NSToolbarPrintItemIdentifier

You can set many attributes in a toolbar item. Minimally, you should assign the toolbar item a label, an image, an action, and a target. The item label is set with the method setLabel:. This label appears under the item image in the toolbar. You can also give the toolbar item a more descriptive label that appears in the customization palette by using the method setPaletteLabel:. The icon image of the toolbar item is set with setImage:, which takes an NSImage as its argument. To set the target/action pair of the toolbar item, use setTarget: and setAction:. If you do not set the target, the action of the toolbar item is invoked in the first responder that implements it.

A toolbar item can be either a simple icon button, such as the Mailboxes and Junk icons shown in Figure 3-10, or a custom NSView containing any control you wish. The Search field in Figure 3-10 is an example of a toolbar item that uses a custom view rather than an icon button. The simple icon buttons are created by giving the toolbar item an image, as discussed in the last paragraph. To assign a custom view to a toolbar item, use the method setView:.

Figure 3-10. The Mail toolbar

NSToolbar relies on a delegate object to supply the toolbar items that populate the toolbar and the customization palette. The delegate should be able to return an NSToolbarItem for every control that might appear in the toolbar. You can set this delegate by sending a setDelegate: message to the toolbar. The delegate is required to implement the following three methods:

toolbar:itemForItemIdentifier:willBeInsertedIntoToolbar:

This method should return a fully configured instance of NSToolbarItem for the specified toolbar and item identifier. The willBeInsertedIntoToolbar: flag indicates whether the item is about to be inserted into the toolbar. If this parameter is YES, you can expect that the delegate method toolbarWillAddItem: will be called soon.

toolbarAllowedItemIdentifiers:

This method should return an NSArray of item identifier strings for all items that may go into the toolbar. The order of the item identifiers in the returned array determines the order in which the items appear in the customization palette.

toolbarDefaultItemIdentifiers:

This method returns an NSArray of item identifiers for the items that make up the default toolbar. The order of the item identifiers in this array determines the order in which items appear in the default toolbar.

Optionally, the toolbar delegate may implement the following two methods:

toolbarWillAddItem:

Called just before a toolbar item is added to a toolbar. The parameter is a notification posted by the toolbar. The object of this notification is the toolbar to which the item will be added. The toolbar item is available in the userInfo dictionary under the key @"item".

toolbarDidRemoveItem:

Called just after a toolbar item is removed from a toolbar. The parameter is a notification posted by the toolbar. The object of this notification is the toolbar from which the item will be removed. The toolbar item is available in the userInfo dictionary under the key @"item".

Example 3-4 shows how a toolbar delegate is implemented to create a simple toolbar.

Example 3-4. Implementing a toolbar delegate

- (NSArray *)toolbarAllowedItemIdentifiers:(NSToolbar*)toolbar
{
    return [NSArray arrayWithObjects:@"Item1",
                      @"Item2",
                      NSToolbarSeparatorItemIdentifier,
                      NSToolbarSpaceItemIdentifier,
                      NSToolbarFlexibleSpaceItemIdentifier,
                      NSToolbarShowColorsItemIdentifier,
                      NSToolbarCustomizeToolbarItemIdentifier,
                      nil];
}

- (NSArray *)toolbarDefaultItemIdentifiers:(NSToolbar*)toolbar
{
    return [NSArray arrayWithObjects:@" Item1",
                      NSToolbarFlexibleSpaceItemIdentifier,
                      @"Item2", nil];
}

- (NSToolbarItem *)toolbar:(NSToolbar *)toolbar 
        itemForItemIdentifier:(NSString *)itemIdentifier 
        willBeInsertedIntoToolbar:(BOOL)flag
{
    NSToolbarItem *item = [[NSToolbarItem alloc] 
                      initWithIdentifer:itemIdentifier];

    /*
     * If customize the item based on the identifier;
     * Standard toolbar items fall through and are returned
     */
    if ( [itemIdentifier isEqualToString:@"Item1" ) {
        [item setLabel:@"Do This"];
        [item setAction:@selector(doThis)];
        [item setImage:[NSImage imageNamed:@"DoThis"]];
    } else if ( [itemIdentifier isEqualToString:@"Item12") {
        [item setLabel:@"Do That"];
        [item setAction:@selector(doThat)];
        [item setImage:[NSImage imageNamed:@"DoThat"]];
    }
    return [item autorelease];
}