NSToolbar Class Reference

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

Overview

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

A toolbar

Tasks

Creating an NSToolbar Object

Toolbar Attributes

Getting and Setting the Delegate

Managing Items on the Toolbar

Displaying the Toolbar

Toolbar Customization

Full Screen Accessory View Settings

Autosaving the Configuration

Validating Visible Items

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 OS X v10.0 and later.
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 OS X v10.0 and later.
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 OS X v10.0 and later.
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 OS X v10.0 and later.
Declared In
NSToolbar.h

delegate

Returns the receiver’s delegate.

- (id < NSToolbarDelegate >)delegate
Return Value

The receiver's delegate.

Discussion

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

Availability
  • Available in OS X v10.0 and later.
Declared In
NSToolbar.h

displayMode

Returns the receiver’s display mode.

- (NSToolbarDisplayMode)displayMode
Return Value

The receiver's display mode.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSToolbar.h

fullScreenAccessoryView

Returns the full screen accessory view.

- (NSView *)fullScreenAccessoryView
Return Value

The accessory view or nil if none is specified.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSToolbar.h

fullScreenAccessoryViewMaxHeight

Returns the maximum height of the toolbar’s accessory view.

- (CGFloat)fullScreenAccessoryViewMaxHeight
Return Value

The height in points.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSToolbar.h

fullScreenAccessoryViewMinHeight

Returns the minimum height of the toolbar’s accessory view.

- (CGFloat)fullScreenAccessoryViewMinHeight
Return Value

The minimum height of the accessory view.

Availability
  • Available in OS X v10.7 and later.
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 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 OS X v10.0 and later.
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 OS X v10.0 and later.
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 OS X v10.0 and later.
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 OS X v10.0 and later.
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 OS X v10.0 and later.
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 OS X v10.0 and later.
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 OS X v10.3 and later.
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 OS X v10.0 and later.
Related Sample Code
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 OS X v10.0 and later.
Related Sample Code
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 OS X v10.0 and later.
Declared In
NSToolbar.h

setDelegate:

Sets the receiver’s delegate.

- (void)setDelegate:(id < NSToolbarDelegate >)delegate
Parameters
delegate

The new delegate object.

Discussion

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

Availability
  • Available in OS X v10.0 and later.
See Also
Related Sample Code
Declared In
NSToolbar.h

setDisplayMode:

Sets the receiver’s display mode.

- (void)setDisplayMode:(NSToolbarDisplayMode)displayMode
Parameters
displayMode

The new display mode.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSToolbar.h

setFullScreenAccessoryView:

Sets the toolbar full screen accessory view.

- (void)setFullScreenAccessoryView:(NSView *)view
Parameters
view

The accessory view.

Discussion

When entering full screen mode, the accessory view is removed from the window if necessary, and attaches underneath the toolbar.

When leaving full screen mode, the accessory view is returned to the window, if it was in the window previously.

To customize this behavior, you can implement the NSWindow delegate method windowWillExitFullScreen:

Availability
  • Available in OS X v10.7 and later.
Declared In
NSToolbar.h

setFullScreenAccessoryViewMaxHeight:

Sets the maximum height of the toolbar’s full screen accessory view.

- (void)setFullScreenAccessoryViewMaxHeight:(CGFloat)maxHeight
Parameters
maxHeight

The maximum height of the accessory view, in points.

Discussion

The maxHeight is used when displaying a a fully revealed menu bar. During the reveal, the toolbar’s accessory view's frame is interpolated between its fullScreenAccessoryViewMinHeight and maxHeight.

By default the maximum height gets set to the height of the accessory view's frame when it is set.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSToolbar.h

setFullScreenAccessoryViewMinHeight:

Sets the minimum height of the toolbar’s full screen accessory view.

- (void)setFullScreenAccessoryViewMinHeight:(CGFloat)minHeight
Parameters
minHeight

The minimum height of the accessory view.

Discussion

The minHeight is used when the menu bar is hidden. During the reveal, the toolbar’s accessory view's frame is interpolated between its minHeight and fullScreenAccessoryViewMaxHeight.

If the minimum height is 0 the accessory view is not resized; instead a special transition is used to reveal it with the menu bar. This simplifies the accessory view's task, because it does not have to handle the case of the height being set to 0.

To create a fixed-height accessory view, set the fullScreenAccessoryViewMinHeight and fullScreenAccessoryViewMinHeight height to be equal.

The default value is 0.

Availability
  • Available in OS X v10.7 and later.
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 OS X v10.3 and later.
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 OS X v10.4 and later.
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 OS X v10.2 and later.
See Also
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 OS X v10.0 and later.
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 OS X v10.4 and later.
Declared In
NSToolbar.h

sizeMode

Returns the receiver’s size mode.

- (NSToolbarSizeMode)sizeMode
Return Value

The receiver's size mode.

Availability
  • Available in OS X v10.2 and later.
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.

In OS X v 10.6 and later toolbars no longer automatically validate for some events, including: NSLeftMouseDragged, NSRightMouseDragged, NSOtherMouseDragged, NSMouseEntered, NSMouseExited, NSScrollWheel, NSCursorUpdate, NSKeyDown. In addition, validation for NSKeyUp and NSFlagsChanged events is deferred with the timer restarting for every new deferrable event. So a sequence of key events will not trigger any validation at all, until either a pause of .85 seconds, or an event other than NSKeyUp or NSFlagsChanged is processed. This change was made as an optimization.

To trigger validation for a single toolbar manually, send the toolbar a validateVisibleItems message. To trigger validation for all toolbars, invoke NSApplication’s setWindowsNeedUpdate: passing YES.

Availability
  • Available in 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 OS X v10.0 and later.
See Also
Declared In
NSToolbar.h

Constants

NSToolbarDisplayMode

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

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

The default display mode.

Available in OS X v10.0 and later.

Declared in NSToolbar.h.

NSToolbarDisplayModeIconAndLabel

The toolbar will display icons and labels.

Available in OS X v10.0 and later.

Declared in NSToolbar.h.

NSToolbarDisplayModeIconOnly

The toolbar will display only icons.

Available in OS X v10.0 and later.

Declared in NSToolbar.h.

NSToolbarDisplayModeLabelOnly

The toolbar will display only labels.

Available in OS X v10.0 and later.

Declared in NSToolbar.h.

Declared In
NSToolbar.h

NSToolbarSizeMode

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

enum {
   NSToolbarSizeModeDefault,
   NSToolbarSizeModeRegular,
   NSToolbarSizeModeSmall
};
typedef NSUInteger NSToolbarSizeMode;
Constants
NSToolbarSizeModeDefault

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

Available in 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 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 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:

Key

Value

@"item"

The NSToolbarItem object that was removed.

Availability
See Also
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:

Key

Value

@"item"

The NSToolbarItem object being added.

Availability
See Also
Declared In
NSToolbar.h