---

NSToolbar Class Reference

Overview

NSToolbar and NSToolbarItem provide the mechanism for a titled window to display a toolbar just below its title bar, as shown below:

Tasks

Creating an NSToolbar Object

• – initWithIdentifier:

Toolbar Attributes

• – displayMode
• – setDisplayMode:
• – showsBaselineSeparator
• – setShowsBaselineSeparator:
• – allowsUserCustomization
• – setAllowsUserCustomization:
• – identifier
• – items
• – visibleItems
• – sizeMode
• – setSizeMode:

Managing the Delegate

• – delegate
• – setDelegate:

Managing Items on the Toolbar

• – insertItemWithItemIdentifier:atIndex:
• – removeItemAtIndex:
• – toolbarWillAddItem:  delegate method
• – toolbarDidRemoveItem:  delegate method
• – setSelectedItemIdentifier:
• – selectedItemIdentifier

Displaying the Toolbar

• – isVisible
• – setVisible:

Toolbar Customization

• – runCustomizationPalette:
• – customizationPaletteIsRunning

Autosaving the Configuration

• – autosavesConfiguration
• – setAutosavesConfiguration:
• – configurationDictionary
• – setConfigurationFromDictionary:

Working With Item Identifiers

• – toolbar:itemForItemIdentifier:willBeInsertedIntoToolbar:  delegate method
• – toolbarAllowedItemIdentifiers:  delegate method
• – toolbarDefaultItemIdentifiers:  delegate method
• – toolbarSelectableItemIdentifiers:  delegate method
• – validateVisibleItems

Instance Methods

allowsUserCustomization

Returns a Boolean value that indicates whether users are allowed to modify the toolbar.

- (BOOL)allowsUserCustomization

Return Value

YES if users are allowed to modify the toolbar, NO otherwise. The default is NO.

Discussion

If the value is NO, then the Customize Toolbar… menu item is disabled and other modification is disabled. This attribute does not affect the user’s ability to show or hide the toolbar.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setAllowsUserCustomization:
• – autosavesConfiguration

Declared In

NSToolbar.h

autosavesConfiguration

Returns a Boolean value that indicates whether the receiver autosaves its configuration.

- (BOOL)autosavesConfiguration

Return Value

YES if the receiver autosaves its configuration, otherwise NO. The default is NO.

Discussion

When autosaving is enabled, the receiver will automatically write the toolbar settings to user defaults if the toolbar configuration changes. The toolbar's configuration is identified in user defaults by the toolbar identifier. If there are multiple toolbars active with the same identifier, they all share the same configuration.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setAutosavesConfiguration:
• – configurationDictionary

Declared In

NSToolbar.h

configurationDictionary

Returns the receiver’s configuration as a dictionary.

- (NSDictionary *)configurationDictionary

Return Value

A dictionary containing configuration information for the toolbar.

Discussion

Contains displayMode, isVisible, and a list of the item identifiers currently in the toolbar.

Special Considerations

Do not depend on any details of the normal contents of a configuration dictionary.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setConfigurationFromDictionary:

Declared In

NSToolbar.h

customizationPaletteIsRunning

Returns a Boolean value that indicates whether the receiver’s customization palette is running (in use).

- (BOOL)customizationPaletteIsRunning

Return Value

YES if the receiver's customization palette is running, otherwise NO.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – runCustomizationPalette:

Declared In

NSToolbar.h

delegate

Returns the receiver’s delegate.

- (id)delegate

Return Value

The receiver's delegate.

Discussion

Every toolbar must have a delegate, which must implement the required delegate methods.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setDelegate:

Declared In

NSToolbar.h

displayMode

Returns the receiver’s display mode.

- (NSToolbarDisplayMode)displayMode

Return Value

The receiver's display mode.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setDisplayMode:

Declared In

NSToolbar.h

identifier

Returns the receiver’s identifier.

- (NSString *)identifier

Return Value

The receiver's identifier, a string used by the class to identify the kind of toolbar.

Discussion

Within the application all toolbars with the same identifier are synchronized to maintain the same state, including for example, the display mode and item order. The identifier is used as the autosave name for toolbars that save their configuration.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setAutosavesConfiguration:

Declared In

NSToolbar.h

initWithIdentifier:

Initializes a newly allocated toolbar with the specified identifier.

- (id)initWithIdentifier:(NSString *)identifier

Parameters

identifier

A string used by the class to identify the kind of the toolbar.

Return Value

The initialized toolbar object.

Discussion

identifier is never seen by users and should not be localized. See identifier for important information.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – identifier

Declared In

NSToolbar.h

insertItemWithItemIdentifier:atIndex:

Inserts the specified item at the specified index.

- (void)insertItemWithItemIdentifier:(NSString *)itemIdentifier atIndex:(NSInteger)index

Parameters

itemIdentifier

The identifier of the item to insert.

index

The index at which to insert the item.

Discussion

If the toolbar needs a new instance, it will get it from toolbar:itemForItemIdentifier:willBeInsertedIntoToolbar:. Typically, you should not call this method; you should let the user reconfigure the toolbar. See identifier for important information.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – removeItemAtIndex:

Declared In

NSToolbar.h

isVisible

Returns a Boolean value that indicates whether the receiver is visible.

- (BOOL)isVisible

Return Value

YES if the receiver is visible, otherwise NO.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setVisible:

Declared In

NSToolbar.h

items

Returns the receiver's current items, in order.

- (NSArray *)items

Return Value

An array of the items in the toolbar.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – visibleItems

Declared In

NSToolbar.h

removeItemAtIndex:

Removes the specified item.

- (void)removeItemAtIndex:(NSInteger)index

Parameters

index

The index of the item to remove.

Discussion

Typically, you should not call this method; you should let the user reconfigure the toolbar. See identifier for important information.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – insertItemWithItemIdentifier:atIndex:

Declared In

NSToolbar.h

runCustomizationPalette:

Runs the receiver’s customization palette.

- (void)runCustomizationPalette:(id)sender

Parameters

sender

The control sending the message.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – customizationPaletteIsRunning

Declared In

NSToolbar.h

selectedItemIdentifier

Returns the identifier of the receiver’s currently selected item, or nil if there is no selection.

- (NSString *)selectedItemIdentifier

Return Value

The identifier of the receiver’s currently selected item, or nil if there is no selection.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – setSelectedItemIdentifier:

Declared In

NSToolbar.h

setAllowsUserCustomization:

Sets whether users are allowed to modify the toolbar.

- (void)setAllowsUserCustomization:(BOOL)allowsCustomization

Parameters

allowsCustomization

YES to allow users to modify the toolbar, NO otherwise.

Discussion

This value can be changed at any time. For instance, you may not want users to be able to customize the toolbar while some event is being processed. This attribute does not affect the user’s ability to show or hide the toolbar.

If you set the toolbar to allow customization, be sure to also set the toolbar to autosave its configuration so the user’s changes persist.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – allowsUserCustomization
• – setAutosavesConfiguration:

Related Sample Code

• EnhancedDataBurn
• iSpend
• PDFKitLinker2
• Quartz Composer QCTV
• ToolbarSample

Declared In

NSToolbar.h

setAutosavesConfiguration:

Sets whether the receiver autosaves its configuration.

- (void)setAutosavesConfiguration:(BOOL)flag

Parameters

flag

YES to indicate that the receiver should autosave its configuration, NO otherwise.

Discussion

Customizable toolbars should generally supporting autosaving. If you need to customize the saving behavior, you can use the configurationDictionary to access the settings that should be saved.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – allowsUserCustomization
• – autosavesConfiguration

Related Sample Code

• EnhancedDataBurn
• iSpend
• PDFKitLinker2
• ToolbarSample

Declared In

NSToolbar.h

setConfigurationFromDictionary:

Sets the receiver’s configuration using configDict.

- (void)setConfigurationFromDictionary:(NSDictionary *)configDict

Parameters

configDict

A dictionary with the toolbar's configuration information. If you want to provide a custom dictionary, you should first get the receiver's current configuration dictionary, then create a modified copy, rather than trying to construct one yourself.

Discussion

This method immediately affects toolbars with the same identifier in all windows of your application.

Special Considerations

Do not depend on any details of the normal contents of a configuration dictionary.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – configurationDictionary

Declared In

NSToolbar.h

setDelegate:

Sets the receiver’s delegate.

- (void)setDelegate:(id)delegate

Parameters

delegate

The new delegate object.

Discussion

Every toolbar must have a delegate, which must implement the required delegate methods.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – delegate

Related Sample Code

• EnhancedDataBurn
• iSpend
• PDFKitLinker2
• Quartz Composer QCTV
• ToolbarSample

Declared In

NSToolbar.h

setDisplayMode:

Sets the receiver’s display mode.

- (void)setDisplayMode:(NSToolbarDisplayMode)displayMode

Parameters

displayMode

The new display mode.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – displayMode

Related Sample Code

• EnhancedDataBurn
• iSpend
• PDFKitLinker2
• Quartz Composer QCTV
• ToolbarSample

Declared In

NSToolbar.h

setSelectedItemIdentifier:

Sets the receiver's selected item to the specified toolbar item.

- (void)setSelectedItemIdentifier:(NSString *)itemIdentifier

Parameters

itemIdentifier

The identifier of the item to select. itemIdentifier may be any identifier returned by toolbarSelectableItemIdentifiers:, even if it is not currently in the toolbar.

Discussion

Typically, a toolbar will manage the selection of items automatically. This method can be used to select identifiers of custom view items, or to force a selection change. See toolbarSelectableItemIdentifiers: for more details. If itemIdentifier is not recognized by the receiver, the current selected item identifier does not change.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – selectedItemIdentifier
• – toolbarSelectableItemIdentifiers:

Declared In

NSToolbar.h

setShowsBaselineSeparator:

Sets whether the toolbar shows the separator between the toolbar and the main window contents.

- (void)setShowsBaselineSeparator:(BOOL)flag

Parameters

flag

YES if the toolbar should show the separator between the toolbar and the main window contents, otherwise NO.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – showsBaselineSeparator

Declared In

NSToolbar.h

setSizeMode:

Sets the receiver’s size mode.

- (void)setSizeMode:(NSToolbarSizeMode)sizeMode

Parameters

sizeMode

The new size mode.

Discussion

If there is no icon of the given size for a toolbar item, the toolbar item creates one by scaling an icon of another size.

Availability

• Available in Mac OS X v10.2 and later.

See Also

• – sizeMode

Declared In

NSToolbar.h

setVisible:

Sets whether the receiver is visible or hidden.

- (void)setVisible:(BOOL)shown

Parameters

shown

YES to indicate the receiver should be made visible, NO to indicate it should be hidden.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – isVisible

Declared In

NSToolbar.h

showsBaselineSeparator

Returns a Boolean value that indicates whether the toolbar shows the separator between the toolbar and the main window contents.

- (BOOL)showsBaselineSeparator

Return Value

YES if the toolbar shows the separator between the toolbar and the main window contents, otherwise NO. The default is YES.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setShowsBaselineSeparator:

Declared In

NSToolbar.h

sizeMode

Returns the receiver’s size mode.

- (NSToolbarSizeMode)sizeMode

Return Value

The receiver's size mode.

Availability

• Available in Mac OS X v10.2 and later.

See Also

• – setSizeMode:

Declared In

NSToolbar.h

validateVisibleItems

Called on window updates to validate the visible items.

- (void)validateVisibleItems

Discussion

You typically use this method by overriding it in a subclass. The default implementation of this method iterates through the list of visible items, sending each a validate message. Override it and call super if you want to know when this method is called.

This method forces a validation of the entire visible set of items, so typically you should not invoke it directly. Instead, if necessary you should validate on a per item basis only those items that have auto-validation disabled (see validate and Validating Toolbar Items)—you generally do this for performance reasons if your validation code is slow.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSToolbar.h

visibleItems

Returns the receiver’s currently visible items.

- (NSArray *)visibleItems

Return Value

An array of the toolbar's visible items.

Discussion

Items in the overflow menu are not considered visible.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – items

Declared In

NSToolbar.h

Delegate 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.)

Implementation of this method is required.

Availability

• Available in Mac OS X v10.0 and later.

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

Implementation of this method is required.

Availability

• Available in Mac OS X v10.0 and later.

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.

Implementation of this method is required.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSToolbar.h

toolbarDidRemoveItem:

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

- (void)toolbarDidRemoveItem:(NSNotification *)notification

Parameters

notification

The notification object sent to observers of NSToolbarDidRemoveItemNotification.

Discussion

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

Implementation of this method is optional.

Availability

• Available in Mac OS X v10.0 and later.

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.

Implementation of this method is optional.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – setSelectedItemIdentifier:

Declared In

NSToolbar.h

toolbarWillAddItem:

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

- (void)toolbarWillAddItem:(NSNotification *)notification

Parameters

notification

The notification object sent to observers of 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.

Implementation of this method is optional.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSToolbar.h

Constants

NSToolbarDisplayMode

These constants specify toolbar display modes and are used by displayMode and setDisplayMode:.

typedef enum {
   NSToolbarDisplayModeDefault,
   NSToolbarDisplayModeIconAndLabel,
   NSToolbarDisplayModeIconOnly,
   NSToolbarDisplayModeLabelOnly
} NSToolbarDisplayMode;

Constants

NSToolbarDisplayModeDefault

The default display mode.

Available in Mac OS X v10.0 and later.

Declared in NSToolbar.h.

NSToolbarDisplayModeIconAndLabel

The toolbar will display icons and labels.

Available in Mac OS X v10.0 and later.

Declared in NSToolbar.h.

NSToolbarDisplayModeIconOnly

The toolbar will display only icons.

Available in Mac OS X v10.0 and later.

Declared in NSToolbar.h.

NSToolbarDisplayModeLabelOnly

The toolbar will display only labels.

Available in Mac OS X v10.0 and later.

Declared in NSToolbar.h.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSToolbar.h

NSToolbarSizeMode

These constants specify toolbar display modes and are used by sizeMode and setSizeMode:.

typedef enum {
   NSToolbarSizeModeDefault,
   NSToolbarSizeModeRegular,
   NSToolbarSizeModeSmall
} NSToolbarSizeMode;

Constants

NSToolbarSizeModeDefault

The toolbar uses the system-defined default size, which is NSToolbarSizeModeRegular.

Available in Mac OS X v10.2 and later.

Declared in NSToolbar.h.

NSToolbarSizeModeRegular

The toolbar uses regular-sized controls and 32 by 32 pixel icons.

Available in Mac OS X v10.2 and later.

Declared in NSToolbar.h.

NSToolbarSizeModeSmall

The toolbar uses small-sized controls and 24 by 24 pixel icons.

Available in Mac OS X v10.2 and later.

Declared in NSToolbar.h.

Availability

• Available in Mac OS X v10.2 and later.

Declared In

NSToolbar.h

Notifications

NSToolbarDidRemoveItemNotification

Posted after an item is removed from a toolbar. The notification item is the NSToolbar object that had an item removed from it. The userInfo dictionary contains the following information:

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – toolbarDidRemoveItem:

Declared In

NSToolbar.h

NSToolbarWillAddItemNotification

Posted before a new item is added to the toolbar. The notification item is the NSToolbar object having an item added to it. The userInfo dictionary contains the following information:

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – toolbarWillAddItem:

Declared In

NSToolbar.h

---