Mac Developer Library

Developer

AppKit Framework Reference NSToolbar Class Reference

Options
Deployment Target:

On This Page
Language:

NSToolbar

Inheritance


Conforms To


Import Statement


Swift

import AppKit

Objective-C

@import AppKit;

Availability


Available in OS X v10.0 and later.

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

image: ../Art/Toolbar_2x.png
  • init(identifier:) - initWithIdentifier: Designated Initializer

    Initializes a newly allocated toolbar with the specified identifier.

    Declaration

    Swift

    init(identifier identifier: String)

    Objective-C

    - (instancetype)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 the identifier property for important information.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    identifier

  • The toolbar’s display mode.

    Declaration

    Swift

    var displayMode: NSToolbarDisplayMode

    Objective-C

    @property NSToolbarDisplayMode displayMode

    Discussion

    For a list of possible display modes, see NSToolbarDisplayMode.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • A Boolean value that indicates whether the toolbar shows the separator between the toolbar and the main window contents.

    Declaration

    Swift

    var showsBaselineSeparator: Bool

    Objective-C

    @property BOOL showsBaselineSeparator

    Discussion

    YEStrue if the toolbar shows the separator between the toolbar and the main window contents; otherwise, NOfalse. The default is NOfalse.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • A Boolean value that indicates whether users are allowed to modify the toolbar.

    Declaration

    Swift

    var allowsUserCustomization: Bool

    Objective-C

    @property BOOL allowsUserCustomization

    Discussion

    YEStrue if users are allowed to modify the toolbar; otherwise, NOfalse. If the value is NOfalse, 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.

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

    The default is NOfalse.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • A Boolean value that indicates whether the toolbar can add items for Action extensions.

    Declaration

    Swift

    var allowsExtensionItems: Bool

    Objective-C

    @property BOOL allowsExtensionItems

    Discussion

    When YEStrue, the toolbar can dynamically create toolbar items for Action extensions in the toolbar configuration panel. To be included, an extension needs to set the NSExtensionServiceAllowsToolbarItem key to YEStrue in its Info.plist. For more informaiton, see App Extension Keys in Information Property List Key Reference.

    The default value is NO.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.10 and later.

  • The receiver’s identifier. (read-only)

    Declaration

    Swift

    var identifier: String { get }

    Objective-C

    @property(readonly, copy) NSString *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. The identifier is used as the autosave name for toolbars that save their configuration.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • items items Property

    An array containing the toolbar’s current items, in order. (read-only)

    Declaration

    Swift

    var items: [AnyObject] { get }

    Objective-C

    @property(readonly, copy) NSArray *items

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    visibleItems

  • An array containing the toolbar’s currently visible items. (read-only)

    Declaration

    Swift

    var visibleItems: [AnyObject]? { get }

    Objective-C

    @property(readonly, copy) NSArray *visibleItems

    Discussion

    Items in the overflow menu are not considered visible.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    items

  • sizeMode sizeMode Property

    The toolbar’s size mode.

    Declaration

    Swift

    var sizeMode: NSToolbarSizeMode

    Objective-C

    @property NSToolbarSizeMode sizeMode

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.2 and later.

  • delegate delegate Property

    The toolbar’s delegate.

    Declaration

    Swift

    unowned(unsafe) var delegate: NSToolbarDelegate?

    Objective-C

    @property(assign) id< NSToolbarDelegate > delegate

    Discussion

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Inserts the specified item at the specified index.

    Declaration

    Swift

    func insertItemWithItemIdentifier(_ itemIdentifier: String, atIndex index: Int)

    Objective-C

    - (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 the identifier property for important information.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Removes the specified item.

    Declaration

    Swift

    func removeItemAtIndex(_ index: Int)

    Objective-C

    - (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 the identifier property for important information.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    var selectedItemIdentifier: String?

    Objective-C

    @property(copy) NSString *selectedItemIdentifier

    Return Value

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

    See Also

  • visible visible Property

    A Boolean value that indicates whether the toolbar is visible.

    Declaration

    Swift

    var visible: Bool

    Objective-C

    @property(getter=isVisible) BOOL visible

    Discussion

    YEStrue if the toolbar is visible; otherwise, NOfalse.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.10 and later.

  • Runs the receiver’s customization palette.

    Declaration

    Swift

    func runCustomizationPalette(_ sender: AnyObject?)

    Objective-C

    - (void)runCustomizationPalette:(id)sender

    Parameters

    sender

    The control sending the message.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • A Boolean value that indicates whether the receiver’s customization palette is running (in use). (read-only)

    Declaration

    Swift

    var customizationPaletteIsRunning: Bool { get }

    Objective-C

    @property(readonly) BOOL customizationPaletteIsRunning

    Discussion

    YEStrue if the receiver's customization palette is running; otherwise, NOfalse.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • The toolbar’s full screen accessory view.

    Declaration

    Swift

    var fullScreenAccessoryView: NSView?

    Objective-C

    @property(strong) NSView *fullScreenAccessoryView

    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:

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

    Deprecated in OS X v10.10.

  • The maximum height of the toolbar’s full screen accessory view, in points.

    Declaration

    Swift

    var fullScreenAccessoryViewMaxHeight: CGFloat

    Objective-C

    @property CGFloat fullScreenAccessoryViewMaxHeight

    Discussion

    The fullScreenAccessoryViewMaxHeight 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 fullScreenAccessoryViewMaxHeight properties.

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

    Deprecated in OS X v10.10.

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

    Declaration

    Swift

    var fullScreenAccessoryViewMinHeight: CGFloat

    Objective-C

    @property CGFloat fullScreenAccessoryViewMinHeight

    Discussion

    The fullScreenAccessoryViewMinHeight is used when the menu bar is hidden. During the reveal, the toolbar’s accessory view's frame is interpolated between its fullScreenAccessoryViewMinHeight 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 fullScreenAccessoryViewMaxHeight and fullScreenAccessoryViewMinHeight properties to be equal.

    The default value is 0.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

    Deprecated in OS X v10.10.

  • A Boolean value that indicates whether the receiver autosaves its configuration.

    Declaration

    Swift

    var autosavesConfiguration: Bool

    Objective-C

    @property BOOL autosavesConfiguration

    Discussion

    YEStrue if the receiver autosaves its configuration; otherwise, NOfalse. 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.

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

    The default is NOfalse.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • A dictionary containing configuration information for the toolbar. (read-only)

    Declaration

    Swift

    var configurationDictionary: [NSObject : AnyObject] { get }

    Objective-C

    @property(readonly, copy) NSDictionary *configurationDictionary

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Called on window updates to validate the visible items.

    Declaration

    Swift

    func validateVisibleItems()

    Objective-C

    - (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 YEStrue.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • These constants specify toolbar display modes and are used by the displayMode property.

    Declaration

    Swift

    enum NSToolbarDisplayMode : UInt { case Default case IconAndLabel case IconOnly case LabelOnly }

    Objective-C

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

    Constants

    • Default

      NSToolbarDisplayModeDefault

      The default display mode.

      Available in OS X v10.0 and later.

    • IconAndLabel

      NSToolbarDisplayModeIconAndLabel

      The toolbar will display icons and labels.

      Available in OS X v10.0 and later.

    • IconOnly

      NSToolbarDisplayModeIconOnly

      The toolbar will display only icons.

      Available in OS X v10.0 and later.

    • LabelOnly

      NSToolbarDisplayModeLabelOnly

      The toolbar will display only labels.

      Available in OS X v10.0 and later.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • These constants specify toolbar display modes and are used by the sizeMode property.

    Declaration

    Swift

    enum NSToolbarSizeMode : UInt { case Default case Regular case Small }

    Objective-C

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

    Constants

    • Default

      NSToolbarSizeModeDefault

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

      Available in OS X v10.2 and later.

    • Regular

      NSToolbarSizeModeRegular

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

      Available in OS X v10.2 and later.

    • Small

      NSToolbarSizeModeSmall

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

      Available in OS X v10.2 and later.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.2 and later.

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.