Mac Developer Library

Developer

AppKit Framework Reference NSToolbar Class Reference

Options
Deployment Target:

On This Page
Language:

NSToolbar

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

Inheritance


Conforms To


Import Statement


import AppKit @import AppKit;

Availability


Available in OS X v10.0 and later.
  • 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 identifier for important information.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – identifier

  • Returns the receiver’s display mode.

    Declaration

    Swift

    var displayMode: NSToolbarDisplayMode

    Objective-C

    @property NSToolbarDisplayMode displayMode

    Return Value

    The receiver's display mode.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets the receiver’s display mode.

    Declaration

    Swift

    var displayMode: NSToolbarDisplayMode

    Objective-C

    @property NSToolbarDisplayMode displayMode

    Parameters

    displayMode

    The new display mode.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – displayMode

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

    Return Value

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

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    var showsBaselineSeparator: Bool

    Objective-C

    @property BOOL showsBaselineSeparator

    Parameters

    flag

    YEStrue if the toolbar should show the separator between the toolbar and the main window contents, otherwise NOfalse.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    var allowsUserCustomization: Bool

    Objective-C

    @property BOOL allowsUserCustomization

    Return Value

    YEStrue if users are allowed to modify the toolbar, NOfalse otherwise. The default is NOfalse.

    Discussion

    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.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets whether users are allowed to modify the toolbar.

    Declaration

    Swift

    var allowsUserCustomization: Bool

    Objective-C

    @property BOOL allowsUserCustomization

    Parameters

    allowsCustomization

    YEStrue to allow users to modify the toolbar, NOfalse 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.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the receiver’s identifier.

    Declaration

    Swift

    var identifier: String { get }

    Objective-C

    @property(readonly, copy) 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.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    setAutosavesConfiguration:

  • Returns the receiver's current items, in order.

    Declaration

    Swift

    var items: [AnyObject] { get }

    Objective-C

    @property(readonly, copy) NSArray *items

    Return Value

    An array of the items in the toolbar.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the receiver’s currently visible items.

    Declaration

    Swift

    var visibleItems: [AnyObject]? { get }

    Objective-C

    @property(readonly, copy) NSArray *visibleItems

    Return Value

    An array of the toolbar's visible items.

    Discussion

    Items in the overflow menu are not considered visible.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – items

  • Returns the receiver’s size mode.

    Declaration

    Swift

    var sizeMode: NSToolbarSizeMode

    Objective-C

    @property NSToolbarSizeMode sizeMode

    Return Value

    The receiver's size mode.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.2 and later.

  • Sets the receiver’s size mode.

    Declaration

    Swift

    var sizeMode: NSToolbarSizeMode

    Objective-C

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

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.2 and later.

    See Also

    – sizeMode

  • Returns the receiver’s delegate.

    Declaration

    Swift

    unowned(unsafe) var delegate: NSToolbarDelegate?

    Objective-C

    @property(assign) id<NSToolbarDelegate> delegate

    Return Value

    The receiver's delegate.

    Discussion

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

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets the receiver’s delegate.

    Declaration

    Swift

    unowned(unsafe) var delegate: NSToolbarDelegate?

    Objective-C

    @property(assign) id<NSToolbarDelegate> delegate

    Parameters

    delegate

    The new delegate object.

    Discussion

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

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – delegate

  • isVisible isVisible Available in OS X v10.0 through OS X v10.9

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

    Declaration

    Objective-C

    - (BOOL)isVisible

    Return Value

    YEStrue if the receiver is visible, otherwise NOfalse.

    Import Statement

    Availability

    Available in OS X v10.0 through OS X v10.9.

    See Also

    – setVisible:

  • Sets whether the receiver is visible or hidden.

    Declaration

    Swift

    var visible: Bool

    Objective-C

    @property(getter=isVisible) BOOL visible

    Parameters

    shown

    YEStrue to indicate the receiver should be made visible, NOfalse to indicate it should be hidden.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – isVisible

  • 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

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    var customizationPaletteIsRunning: Bool { get }

    Objective-C

    @property(readonly) BOOL customizationPaletteIsRunning

    Return Value

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

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    var autosavesConfiguration: Bool

    Objective-C

    @property BOOL autosavesConfiguration

    Return Value

    YEStrue if the receiver autosaves its configuration, otherwise NOfalse. The default is NOfalse.

    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.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets whether the receiver autosaves its configuration.

    Declaration

    Swift

    var autosavesConfiguration: Bool

    Objective-C

    @property BOOL autosavesConfiguration

    Parameters

    flag

    YEStrue to indicate that the receiver should autosave its configuration, NOfalse 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.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the receiver’s configuration as a dictionary.

    Declaration

    Swift

    var configurationDictionary: [NSObject : AnyObject] { get }

    Objective-C

    @property(readonly, copy) 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.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets the receiver’s configuration using configDict.

    Declaration

    Swift

    func setConfigurationFromDictionary(_ configDict: [NSObject : AnyObject])

    Objective-C

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

    Import Statement

    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

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    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

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    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

    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

    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

    import AppKit

    Availability

    Available in OS X v10.0 and later.