NSToolbarDelegate Protocol Reference

Conforms to
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.6 and later.
Companion guide
Declared in
NSToolbar.h
Related sample code

Overview

The NSToolbarDelegate protocol defines the optional methods implemented by delegates of NSToolbar objects.

Tasks

Configuring a Toolbar

Responding to Additions and Deletions in the Toolbar

Instance Methods

toolbar:itemForItemIdentifier:willBeInsertedIntoToolbar:

Sent to request a new toolbar item; returns a toolbar item of the identified kind for the specified toolbar.

- (NSToolbarItem *)toolbar:(NSToolbar *)toolbar itemForItemIdentifier:(NSString *)itemIdentifier willBeInsertedIntoToolbar:(BOOL)flag
Parameters
toolbar

The toolbar for which the item is being requested.

itemIdentifier

The identifier for the requested item.

flag

YES if the item will be immediately inserted into the toolbar. If flag is NO the toolbar item is being requested for display in the toolbar customization sheet and should always be enabled or provide some other canonical representation. If you ignore this parameter the same toolbar item will be used in the toolbar and in the customization sheet.

Return Value

The toolbar item for the specified toolbar and identifier. Return nil to indicate that the identified kind of toolbar item is not supported. When an item is requested again, you may return the same NSToolbarItem object returned earlier or a different instance.

Discussion

Implement this method to create new toolbar item instances. This method is called lazily on behalf of a toolbar instance, which must be the sole owner of the toolbar item. A toolbar may ask again for a kind of toolbar item already supplied to it, in which case this method may return the same toolbar item it returned before or a different one. If your delegate services multiple toolbars, each attached to a different window, it is best to return a different item for each toolbar—an NSToolbarItem object can only be in one toolbar at a time.

If the item is a custom view item, the NSView object must be fully formed when the item is returned. Do not assume that the returned item is going to be added as an active item in the toolbar, as it could be that it will be used only in the customization palette. (The customization palette makes a copy of the returned item.)

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSToolbar.h

toolbarAllowedItemIdentifiers:

Sent to discover the allowed item identifiers for a toolbar.

- (NSArray *)toolbarAllowedItemIdentifiers:(NSToolbar *)toolbar
Parameters
toolbar

The toolbar whose allowed item identifiers are to be returned.

Return Value

An array of toolbar item identifiers for toolbar, specifying the contents and the order of the items in the configuration palette.

Discussion

Every allowed item must be explicitly listed, even the standard ones. The identifiers returned should include all of those returned by toolbarDefaultItemIdentifiers:.

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSToolbar.h

toolbarDefaultItemIdentifiers:

Sent to discover the default item identifiers for a toolbar.

- (NSArray *)toolbarDefaultItemIdentifiers:(NSToolbar *)toolbar
Parameters
toolbar

The toolbar whose default item identifiers are to be returned.

Return Value

An array of toolbar item identifiers for toolbar, specifying the contents and the order of the items in the default toolbar configuration.

Discussion

During initialization of toolbar, this method is called only if a toolbar configuration for the identifier of toolbar is not found in the user preferences. This method is called during initialization of the toolbar customization palette.

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSToolbar.h

toolbarDidRemoveItem:

Sent just after an item has been removed from a toolbar.

- (void)toolbarDidRemoveItem:(NSNotification *)notification
Parameters
notification

A notification named NSToolbarDidRemoveItemNotification.

Discussion

This method allows you to remove information related to the item that may have been cached.

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSToolbar.h

toolbarSelectableItemIdentifiers:

Sent to discover the selectable item identifiers for a toolbar.

- (NSArray *)toolbarSelectableItemIdentifiers:(NSToolbar *)toolbar
Parameters
toolbar

The toolbar whose selectable item identifiers are to be returned.

Return Value

An array of item identifiers that should indicate selection in the specified toolbar.

Discussion

Toolbars that need to indicate item selection should return an array containing the identifiers of the selectable toolbar items.

If implemented, toolbar will display the currently selected item with a visual highlight. Clicking on an item whose identifier is selectable will automatically update the toolbar's selected item identifier, when possible. Clicking an item whose identifier is not selectable will not update the toolbar's selected item identifier.

Availability
  • Available in OS X v10.3 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
See Also
Declared In
NSToolbar.h

toolbarWillAddItem:

Sent just before a new item is added to a toolbar.

- (void)toolbarWillAddItem:(NSNotification *)notification
Parameters
notification

A notification named NSToolbarWillAddItemNotification.

Discussion

If you need to cache a reference to a toolbar item or need to set up some initial state before a toolbar item is added, this is where to do it.

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSToolbar.h