| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/AppKit.framework |
| Availability | Available in Mac OS X v10.0 and later. |
| Companion guide | |
| Declared in | NSToolbar.h |
| Related sample code |
NSToolbar and NSToolbarItem provide the mechanism for a titled window to display a toolbar just below its title bar, as shown below:
– displayMode
– setDisplayMode:
– showsBaselineSeparator
– setShowsBaselineSeparator:
– allowsUserCustomization
– setAllowsUserCustomization:
– identifier
– items
– visibleItems
– sizeMode
– setSizeMode:
– insertItemWithItemIdentifier:atIndex:
– removeItemAtIndex:
– setSelectedItemIdentifier:
– selectedItemIdentifier
– autosavesConfiguration
– setAutosavesConfiguration:
– configurationDictionary
– setConfigurationFromDictionary:
Returns a Boolean value that indicates whether users are allowed to modify the toolbar.
- (BOOL)allowsUserCustomization
YES if users are allowed to modify the toolbar, NO otherwise. The default is NO.
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.
NSToolbar.hReturns a Boolean value that indicates whether the receiver autosaves its configuration.
- (BOOL)autosavesConfiguration
YES if the receiver autosaves its configuration, otherwise NO. The default is NO.
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.
NSToolbar.hReturns the receiver’s configuration as a dictionary.
- (NSDictionary *)configurationDictionary
A dictionary containing configuration information for the toolbar.
Contains displayMode, isVisible, and a list of the item identifiers currently in the toolbar.
Do not depend on any details of the normal contents of a configuration dictionary.
NSToolbar.hReturns a Boolean value that indicates whether the receiver’s customization palette is running (in use).
- (BOOL)customizationPaletteIsRunning
YES if the receiver's customization palette is running, otherwise NO.
NSToolbar.hReturns the receiver’s delegate.
- (id < NSToolbarDelegate >)delegate
The receiver's delegate.
Every toolbar must have a delegate, which must implement the required delegate methods.
NSToolbar.hReturns the receiver’s display mode.
- (NSToolbarDisplayMode)displayMode
The receiver's display mode.
NSToolbar.hReturns the receiver’s identifier.
- (NSString *)identifier
The receiver's identifier, a string used by the class to identify the kind of toolbar.
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.
– setAutosavesConfiguration:NSToolbar.hInitializes a newly allocated toolbar with the specified identifier.
- (id)initWithIdentifier:(NSString *)identifier
A string used by the class to identify the kind of the toolbar.
The initialized toolbar object.
identifier is never seen by users and should not be localized. See identifier for important information.
NSToolbar.hInserts the specified item at the specified index.
- (void)insertItemWithItemIdentifier:(NSString *)itemIdentifier atIndex:(NSInteger)index
The identifier of the item to insert.
The index at which to insert the item.
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.
NSToolbar.hReturns a Boolean value that indicates whether the receiver is visible.
- (BOOL)isVisible
YES if the receiver is visible, otherwise NO.
NSToolbar.hReturns the receiver's current items, in order.
- (NSArray *)items
An array of the items in the toolbar.
NSToolbar.hRemoves the specified item.
- (void)removeItemAtIndex:(NSInteger)index
The index of the item to remove.
Typically, you should not call this method; you should let the user reconfigure the toolbar. See identifier for important information.
NSToolbar.hRuns the receiver’s customization palette.
- (void)runCustomizationPalette:(id)sender
The control sending the message.
NSToolbar.hReturns the identifier of the receiver’s currently selected item, or nil if there is no selection.
- (NSString *)selectedItemIdentifier
The identifier of the receiver’s currently selected item, or nil if there is no selection.
NSToolbar.hSets whether users are allowed to modify the toolbar.
- (void)setAllowsUserCustomization:(BOOL)allowsCustomization
YES to allow users to modify the toolbar, NO otherwise.
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.
NSToolbar.hSets whether the receiver autosaves its configuration.
- (void)setAutosavesConfiguration:(BOOL)flag
YES to indicate that the receiver should autosave its configuration, NO otherwise.
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.
NSToolbar.hSets the receiver’s configuration using configDict.
- (void)setConfigurationFromDictionary:(NSDictionary *)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.
This method immediately affects toolbars with the same identifier in all windows of your application.
Do not depend on any details of the normal contents of a configuration dictionary.
NSToolbar.hSets the receiver’s delegate.
- (void)setDelegate:(id < NSToolbarDelegate >)delegate
The new delegate object.
Every toolbar must have a delegate, which must implement the required delegate methods.
NSToolbar.hSets the receiver’s display mode.
- (void)setDisplayMode:(NSToolbarDisplayMode)displayMode
The new display mode.
NSToolbar.hSets the receiver's selected item to the specified toolbar item.
- (void)setSelectedItemIdentifier:(NSString *)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.
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.
– selectedItemIdentifier– toolbarSelectableItemIdentifiers: (NSToolbarDelegate)NSToolbar.hSets whether the toolbar shows the separator between the toolbar and the main window contents.
- (void)setShowsBaselineSeparator:(BOOL)flag
YES if the toolbar should show the separator between the toolbar and the main window contents, otherwise NO.
NSToolbar.hSets the receiver’s size mode.
- (void)setSizeMode:(NSToolbarSizeMode)sizeMode
The new size mode.
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.
NSToolbar.hSets whether the receiver is visible or hidden.
- (void)setVisible:(BOOL)shown
YES to indicate the receiver should be made visible, NO to indicate it should be hidden.
NSToolbar.hReturns a Boolean value that indicates whether the toolbar shows the separator between the toolbar and the main window contents.
- (BOOL)showsBaselineSeparator
YES if the toolbar shows the separator between the toolbar and the main window contents, otherwise NO. The default is YES.
NSToolbar.hReturns the receiver’s size mode.
- (NSToolbarSizeMode)sizeMode
The receiver's size mode.
NSToolbar.hCalled on window updates to validate the visible items.
- (void)validateVisibleItems
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 Mac 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.
NSToolbar.hReturns the receiver’s currently visible items.
- (NSArray *)visibleItems
An array of the toolbar's visible items.
Items in the overflow menu are not considered visible.
NSToolbar.hThese constants specify toolbar display modes and are used by displayMode and setDisplayMode:.
enum {
NSToolbarDisplayModeDefault,
NSToolbarDisplayModeIconAndLabel,
NSToolbarDisplayModeIconOnly,
NSToolbarDisplayModeLabelOnly
};
typedef NSUInteger NSToolbarDisplayMode;
NSToolbarDisplayModeDefaultThe default display mode.
Available in Mac OS X v10.0 and later.
Declared in NSToolbar.h.
NSToolbarDisplayModeIconAndLabelThe toolbar will display icons and labels.
Available in Mac OS X v10.0 and later.
Declared in NSToolbar.h.
NSToolbarDisplayModeIconOnlyThe toolbar will display only icons.
Available in Mac OS X v10.0 and later.
Declared in NSToolbar.h.
NSToolbarDisplayModeLabelOnlyThe toolbar will display only labels.
Available in Mac OS X v10.0 and later.
Declared in NSToolbar.h.
NSToolbar.hThese constants specify toolbar display modes and are used by sizeMode and setSizeMode:.
enum {
NSToolbarSizeModeDefault,
NSToolbarSizeModeRegular,
NSToolbarSizeModeSmall
};
typedef NSUInteger NSToolbarSizeMode;
NSToolbarSizeModeDefaultThe toolbar uses the system-defined default size, which is NSToolbarSizeModeRegular.
Available in Mac OS X v10.2 and later.
Declared in NSToolbar.h.
NSToolbarSizeModeRegularThe toolbar uses regular-sized controls and 32 by 32 pixel icons.
Available in Mac OS X v10.2 and later.
Declared in NSToolbar.h.
NSToolbarSizeModeSmallThe toolbar uses small-sized controls and 24 by 24 pixel icons.
Available in Mac OS X v10.2 and later.
Declared in NSToolbar.h.
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 |
|---|---|
| The |
– toolbarDidRemoveItem: (NSToolbarDelegate)NSToolbar.hPosted 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 |
|---|---|
| The |
– toolbarWillAddItem: (NSToolbarDelegate)NSToolbar.hLast updated: 2009-09-02
