---

NSToolbar

Overview

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

Tasks

Constructors

• NSToolbar

Toolbar Attributes

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

Managing the Delegate

• delegate
• setDelegate

Managing Items on the Toolbar

• insertItemWithItemIdentifierAtIndex
• removeItemAtIndex
• setSelectedItemIdentifier
• selectedItemIdentifier

Displaying the Toolbar

• isVisible
• setVisible

Toolbar Customization

• runCustomizationPalette
• customizationPaletteIsRunning

Autosaving the Configuration

• autosavesConfiguration
• setAutosavesConfiguration
• configurationDictionary
• setConfigurationFromDictionary

Toolbar Item Validation

• validateVisibleItems

Adding and removing items

• toolbarWillAddItem  delegate method
• toolbarDidRemoveItem  delegate method

Working with item identifiers

• toolbarAllowedItemIdentifiers  delegate method
• toolbarDefaultItemIdentifiers  delegate method
• toolbarItemForItemIdentifier  delegate method
• toolbarSelectableItemIdentifiers  delegate method

Instance Methods

allowsUserCustomization

Answers whether or not users are allowed to modify the toolbar.

public boolean allowsUserCustomization()

Discussion

The default value is false. If the value is false, then the Customize Toolbar… menu item is disabled and other modification is disabled. If the value is true, be sure to also set autosavesConfiguration to true, so the user’s changes persist. This attribute does not affect the user’s ability to show or hide the toolbar.

See Also

• setAllowsUserCustomization
• autosavesConfiguration

autosavesConfiguration

Returns whether the receiver autosaves its configuration.

public boolean autosavesConfiguration()

Discussion

If true, the receiver will automatically write the toolbar settings to user defaults if the toolbar configuration changes. The default is false.

The information about the toolbar configuration is identified in user defaults by the toolbar identifier. If there are multiple toolbars active with the same identifier, then they all share the same configuration, so it is this shared configuration that is saved.

See Also

• setAutosavesConfiguration
• configurationDictionary

configurationDictionary

Returns the receiver’s configuration as a dictionary.

public NSDictionary configurationDictionary()

Discussion

Contains displayMode, isVisible, and a list of the item identifiers currently in the toolbar. You can add your own items if you need to.

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

See Also

• setConfigurationFromDictionary

customizationPaletteIsRunning

Returns whether the receiver’s customization palette is running (in use).

public boolean customizationPaletteIsRunning()

See Also

• runCustomizationPalette

delegate

Returns the receiver’s delegate.

public Object delegate()

Discussion

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

See Also

• setDelegate

displayMode

Returns the receiver’s display mode, which is one of the values described in “Constants.”

public int displayMode()

See Also

• setDisplayMode

identifier

Returns the receiver’s identifier, which identifies the kind of the toolbar.

public String identifier()

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. Also, if a toolbar autosaves its configuration, the item identifier is used as the autosave name.

insertItemWithItemIdentifierAtIndex

Inserts the item identified by itemIdentifier at index.

public void insertItemWithItemIdentifierAtIndex(String itemIdentifier, int index)

Discussion

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

See Also

• removeItemAtIndex

isVisible

Returns whether the receiver is visible.

public boolean isVisible()

See Also

• setVisible

items

Returns all current items in the receiver, in order.

public NSArray items()

See Also

• visibleItems

removeItemAtIndex

Removes the item at index.

public void removeItemAtIndex(int index)

Discussion

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

See Also

• insertItemWithItemIdentifierAtIndex

runCustomizationPalette

Runs the receiver’s customization palette.

public void runCustomizationPalette(Object sender)

Discussion

When the user is done customizing, the palette will be dismissed.

See Also

• customizationPaletteIsRunning

selectedItemIdentifier

Returns the identifier of the receiver’s currently selected item, or null

public String selectedItemIdentifier()

Discussion

if there is no selection.

Availability

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

See Also

• setSelectedItemIdentifier

setAllowsUserCustomization

Sets whether or not users are allowed to modify the toolbar to allowsCustomization.

public void setAllowsUserCustomization(boolean allowsCustomization)

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.

See Also

• allowsUserCustomization

setAutosavesConfiguration

Sets whether the receiver autosaves its configuration.

public void setAutosavesConfiguration(boolean flag)

Discussion

If true, the receiver will automatically write changes the user makes to user defaults. Customizable toolbars will want to set flag to true. Setting it to false means changes in configuration are not written automatically; however you can use the configurationDictionary to do it yourself.

See Also

• allowsUserCustomization
• autosavesConfiguration

setConfigurationFromDictionary

Sets the receiver’s configuration using configDict.

public void setConfigurationFromDictionary(NSDictionary configDict)

Discussion

This method also immediately affects toolbars of the same kind in other windows.

See Also

• configurationDictionary

setDelegate

Sets the receiver’s delegate to delegate.

public void setDelegate(Object delegate)

Discussion

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

See Also

• delegate

setDisplayMode

Sets the receiver’s display mode.

public void setDisplayMode(int displayMode)

Discussion

displayMode is one of the values described in “Constants.”

See Also

• displayMode

setSelectedItemIdentifier

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

public void setSelectedItemIdentifier(String itemIdentifier)

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.

itemIdentifier may be any identifier returned by toolbarSelectableItemIdentifiers, even if it is not currently in the toolbar. If the selected item is removed from the toolbar, the selectedItemIdentifier does not change.

Availability

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

See Also

• selectedItemIdentifier
• toolbarSelectableItemIdentifiers

setShowsBaselineSeparator

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

public void setShowsBaselineSeparator(boolean flag)

Discussion

If flag is true the baseline is shown. The default is true.

Availability

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

See Also

• showsBaselineSeparator

setSizeMode

Sets the receiver’s size mode.

public void setSizeMode(int sizeMode)

Discussion

The size can be:

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

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

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

Availability

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

See Also

• sizeMode

setVisible

Sets whether the receiver is visible or hidden to shown.

public void setVisible(boolean shown)

See Also

• isVisible

showsBaselineSeparator

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

public boolean showsBaselineSeparator

Discussion

The default is true.

Availability

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

See Also

• setShowsBaselineSeparator

sizeMode

Returns the receiver’s size mode, which is one of the values described in “Constants.”

public int sizeMode()

Availability

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

See Also

• setSizeMode

validateVisibleItems

Called on window updates with the purpose of validating each of the visible items.

public void validateVisibleItems()

Discussion

You use this method by overriding it in a subclass; you should not invoke this method. The toolbar calls this method to iterate through the list of visible items, sending each a validate message. Override it and call super if you want to know when this happens.

visibleItems

Returns the receiver’s currently visible items. An item can be invisible if it has spilled over into the overflow menu.

public NSArray visibleItems()

See Also

• items

Constants

The following constants toolbar display modes and are used by displayMode and setDisplayMode:

The following constants specify toolbar sizes and are used by sizeMode and setSizeMode:

Delegate Methods

toolbarAllowedItemIdentifiers

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

public abstract NSArray toolbarAllowedItemIdentifiers(NSToolbar toolbar)

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.

toolbarDefaultItemIdentifiers

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

public abstract NSArray toolbarDefaultItemIdentifiers(NSToolbar toolbar)

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.

toolbarDidRemoveItem

Posted just after an item has been removed from toolbar.

public abstract void toolbarDidRemoveItem(NSNotification notification)

Discussion

This method allows the chance to remove information related to the item that may have been cached. The notification‘s object is the toolbar from which the item is being removed. The notification‘s userInfo dictionary contains the item being removed under the key "item". If this method is implemented, then when you set the toolbar’s delegate, the toolbar automatically registers this method for DidRemoveItemNotification.

Implementation of this method is optional.

toolbarItemForItemIdentifier

Returns a toolbar item of the kind identified by the given toolbar itemIdentifier.

public abstract NSToolbarItem toolbarItemForItemIdentifier(NSToolbar toolbar, String itemIdentifier, boolean flag)

Discussion

This is where you 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 can and should return the same toolbar item it returned before.

If the item is a custom view item, the NSView 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.)

A null return value tells the toolbar that the identified kind of toolbar item is not supported.

If flag is true, the returned item will be inserted into the toolbar, and you can expect that toolbarWillAddItem is about to be called.

Implementation of this method is required.

toolbarSelectableItemIdentifiers

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

public abstract NSArray toolbarSelectableItemIdentifiers(NSToolbar 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 toolbars selected item identifier, when possible.

Implementation of this method is optional.

Availability

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

See Also

• setSelectedItemIdentifier

toolbarWillAddItem

Posted just before a new item is added to the toolbar.

public abstract void toolbarWillAddItem(NSNotification notification)

Discussion

If you need to cache a reference to the toolbar item or need to set up some initial state, this is where to do it. The object attribute of notification is the toolbar to which the item is being added. The notification‘s userInfo dictionary contains the item being added under the key "item". If this method is implemented, then when you set the toolbar’s delegate, the toolbar automatically registers this method for WillAddItemNotification.

Implementation of this method is optional.

Notifications

DidRemoveItemNotification

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

See Also

• toolbarDidRemoveItem

WillAddItemNotification

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

See Also

• toolbarWillAddItem

---