Mac Developer Library

Developer

AppKit Framework Reference NSToolbarItem Class Reference

Options
Deployment Target:

On This Page
Language:

NSToolbarItem

Inheritance


Import Statement


Swift

import AppKit

Objective-C

@import AppKit;

Availability


Available in OS X v10.0 and later.

The NSToolbarItem class defines each item contained within a window’s NSToolbar instance.

In OS X v10.7, if an NSToolbarItem has an NSSearchField instance as its view, that search field automatically has its minimum and maximum size adjusted to the system-specified standard values (currently 140 and 240 points).

  • Initialize the receiver with a given identifier.

    Declaration

    Swift

    init(itemIdentifier itemIdentifier: String)

    Objective-C

    - (instancetype)initWithItemIdentifier:(NSString *)itemIdentifier

    Parameters

    itemIdentifier

    The identifier for the receiver. itemIdentifier is never seen by users and should not be localized.

    Discussion

    The identifier is used by the toolbar and its delegate to identify the kind of the toolbar item.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the receiver’s identifier.

    Declaration

    Swift

    var itemIdentifier: String { get }

    Objective-C

    @property(readonly, copy) NSString *itemIdentifier

    Return Value

    The receiver’s identifier, which was provided in the initializer.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the toolbar that is using the receiver.

    Declaration

    Swift

    unowned(unsafe) var toolbar: NSToolbar? { get }

    Objective-C

    @property(readonly, assign) NSToolbar *toolbar

    Return Value

    The toolbar that is using the receiver.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the receiver’s label.

    Declaration

    Swift

    var label: String

    Objective-C

    @property(copy) NSString *label

    Return Value

    The receiver’s label, which normally appears in the toolbar and in the overflow menu.

    Discussion

    For a discussion on labels, see Setting a Toolbar Item’s Representation.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets the receiver’s label that appears in the toolbar.

    Declaration

    Swift

    var label: String

    Objective-C

    @property(copy) NSString *label

    Parameters

    label

    The receiver’s label that appears in the toolbar. The length of the label should be appropriate and not too long. The label may be empty.

    Discussion

    The implication is that the toolbar will draw the label for the receiver, and a redraw is triggered by this method. The toolbar is in charge of the label area. For a discussion on labels, see Setting a Toolbar Item’s Representation.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the label that appears when the receiver is in the customization palette.

    Declaration

    Swift

    var paletteLabel: String

    Objective-C

    @property(copy) NSString *paletteLabel

    Return Value

    The label that appears when the receiver is in the customization palette.

    Discussion

    An item must have a palette label if the customization palette is to be used, and for most items it is reasonable to set paletteLabel to be the same value as label. One reason for paletteLabel to be different from label would be if it’s more descriptive; another might be if there is no label.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets the receiver’s label that appears when it is in the customization palette.

    Declaration

    Swift

    var paletteLabel: String

    Objective-C

    @property(copy) NSString *paletteLabel

    Parameters

    paletteLabel

    The label that appears when the receiver is in the customization palette.

    Discussion

    An item must have a palette label if the customization palette is to be used, and for most items it is reasonable to set paletteLabel to be the same value as label. One reason for paletteLabel to be different from label would be if it’s more descriptive; another might be if there is no label.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the tooltip used when the receiver is displayed in the toolbar.

    Declaration

    Swift

    var toolTip: String?

    Objective-C

    @property(copy) NSString *toolTip

    Return Value

    The tooltip used when the receiver is displayed in the toolbar.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – setToolTip:

  • Sets the tooltip to be used when the receiver is displayed in the toolbar.

    Declaration

    Swift

    var toolTip: String?

    Objective-C

    @property(copy) NSString *toolTip

    Parameters

    toolTip

    A string representing the tooltip to be used when the receiver is displayed in the toolbar.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – toolTip

  • Returns the receiver’s menu form representation.

    Declaration

    Swift

    var menuFormRepresentation: NSMenuItem?

    Objective-C

    @property(strong) NSMenuItem *menuFormRepresentation

    Return Value

    The receiver’s menu form representation.

    Discussion

    By default, this method returns nil, even though there is a default menu form representation.

    For a discussion on menu forms, see Setting a Toolbar Item’s Representation.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets the receiver’s menu form.

    Declaration

    Swift

    var menuFormRepresentation: NSMenuItem?

    Objective-C

    @property(strong) NSMenuItem *menuFormRepresentation

    Parameters

    menuItem

    The menu form for the receiver.

    Discussion

    For a discussion on menu forms see Setting a Toolbar Item’s Representation.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the receiver’s tag.

    Declaration

    Swift

    var tag: Int

    Objective-C

    @property NSInteger tag

    Return Value

    The receiver’s tag.

    Discussion

    You can use the tag for your own custom purpose.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – setTag:

  • Sets the receiver’s tag.

    Declaration

    Swift

    var tag: Int

    Objective-C

    @property NSInteger tag

    Parameters

    tag

    The tag for the receiver.

    Discussion

    You can use the tag for your own custom purpose.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – tag

  • Returns the receiver’s target.

    Declaration

    Swift

    weak var target: AnyObject?

    Objective-C

    @property(weak) id target

    Return Value

    The receiver’s target.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – setTarget:

  • Sets the object that will receive the action when the toolbar item is selected.

    Declaration

    Swift

    weak var target: AnyObject?

    Objective-C

    @property(weak) id target

    Parameters

    target

    The target for the receiver.

    Discussion

    If target is nil, the toolbar will call action and attempt to invoke the action on the first responder and, failing that, pass the action up the responder chain.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – target
    – setAction:
    validateToolbarItem: (NSToolbarValidation)

  • Returns the receiver’s action.

    Declaration

    Swift

    var action: Selector

    Objective-C

    @property SEL action

    Return Value

    The receiver’s action.

    Discussion

    For custom view items, this method sends action to the view if it responds and returns the result.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – setAction:

  • Sets the receiver’s action.

    Declaration

    Swift

    var action: Selector

    Objective-C

    @property SEL action

    Parameters

    action

    The action for the receiver.

    Discussion

    For a custom view item, this method calls setAction: on the view if it responds.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • isEnabled - isEnabled Available in OS X v10.0 through OS X v10.9

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

    Declaration

    Objective-C

    - (BOOL)isEnabled

    Return Value

    YEStrue if the receiver is enabled, otherwise NOfalse.

    Discussion

    For a view item, this method calls isEnabled on the view if it responds and returns the result.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

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

  • Sets the receiver’s enabled flag.

    Declaration

    Swift

    var enabled: Bool

    Objective-C

    @property(getter=isEnabled) BOOL enabled

    Parameters

    enabled

    YEStrue to enable the receiver, otherwise NOfalse.

    Discussion

    For a custom view item, this method calls setEnabled: on the view if it responds.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – isEnabled

  • Returns the image of the receiver.

    Declaration

    Swift

    var image: NSImage?

    Objective-C

    @property(strong) NSImage *image

    Return Value

    The image of the receiver.

    Discussion

    For an image item this method returns the result of the most recent setImage:. For view items, this method calls image on the view if it responds and returns the result.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – setImage:

  • Sets the image for the receiver or of the view.

    Declaration

    Swift

    var image: NSImage?

    Objective-C

    @property(strong) NSImage *image

    Parameters

    image

    The image for the receiver, or of the view if it has already been set for the receiver.

    Discussion

    For a custom view item (one whose view has already been set), this method calls setImage: on the view if it responds. If image contains multiple representations, NSToolbarItem chooses the most appropriately sized representation when displaying.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the receiver’s view.

    Declaration

    Swift

    var view: NSView?

    Objective-C

    @property(strong) NSView *view

    Return Value

    The receiver’s view.

    Discussion

    Note that many of the set/get methods are implemented by calls forwarded to the NSView object referenced by this attribute, if the object responds to it.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – setView:

  • Use this method to make the receiver into a view item.

    Declaration

    Swift

    var view: NSView?

    Objective-C

    @property(strong) NSView *view

    Parameters

    view

    The view for the receiver.

    Discussion

    Note that many of the set/get methods are implemented by calls forwarded to view, if it responds to it.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the receiver’s minimum size.

    Declaration

    Swift

    var minSize: NSSize

    Objective-C

    @property NSSize minSize

    Return Value

    The receiver’s minimum size.

    Discussion

    See Setting a Toolbar Item’s Size for a discussion on item sizes.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – setMinSize:

  • Sets the receiver’s minimum size to a given size.

    Declaration

    Swift

    var minSize: NSSize

    Objective-C

    @property NSSize minSize

    Parameters

    size

    The minimum size for the receiver.

    Discussion

    See Setting a Toolbar Item’s Size in Toolbar Programming Topics for Cocoa for a discussion on item sizes.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – minSize

  • Returns the receiver’s maximum size.

    Declaration

    Swift

    var maxSize: NSSize

    Objective-C

    @property NSSize maxSize

    Return Value

    The receiver’s maximum size.

    Discussion

    See Setting a Toolbar Item’s Size for a discussion on item sizes.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – setMaxSize:

  • Sets the receiver’s maximum size to a given size.

    Declaration

    Swift

    var maxSize: NSSize

    Objective-C

    @property NSSize maxSize

    Parameters

    size

    The maximum size for the receiver.

    Discussion

    See Setting a Toolbar Item’s Size for a discussion on item sizes.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – maxSize

  • Returns the receiver’s visibility priority.

    Declaration

    Swift

    var visibilityPriority: Int

    Objective-C

    @property NSInteger visibilityPriority

    Return Value

    The receiver’s visibility priority. Possible values are described in “Item Priority”.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Sets the receiver’s visibility priority.

    Declaration

    Swift

    var visibilityPriority: Int

    Objective-C

    @property NSInteger visibilityPriority

    Parameters

    visibilityPriority

    The visibility priority for the receiver. The values for visibilityPriority are described in “Item Priority”.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • This method is called by the receiver’s toolbar during validation.

    Declaration

    Swift

    func validate()

    Objective-C

    - (void)validate

    Discussion

    You may invoke this method directly if you have disabled automatic validation for an item—typically you do this for performance reasons if your validation code is slow. For further discussion, see Validating Toolbar Items.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – setEnabled:

  • Returns a Boolean value that indicates whether the receiver is automatically validated by the toolbar.

    Declaration

    Swift

    var autovalidates: Bool

    Objective-C

    @property BOOL autovalidates

    Return Value

    YEStrue if the receiver is automatically validated by the toolbar, otherwise NOfalse.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Sets the receiver’s auto validation flag.

    Declaration

    Swift

    var autovalidates: Bool

    Objective-C

    @property BOOL autovalidates

    Parameters

    resistance

    YEStrue to set the receiver to automatically be validated by the toolbar; otherwise NOfalse.

    Discussion

    By default NSToolbar automatically invokes the receiver’s validate method on a regular basis. If your validate method is time consuming, you can disable auto validation on a per toolbar item basis.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Returns a Boolean value that indicates whether the receiver can be represented in the toolbar at more than one position.

    Declaration

    Swift

    var allowsDuplicatesInToolbar: Bool { get }

    Objective-C

    @property(readonly) BOOL allowsDuplicatesInToolbar

    Return Value

    YEStrue to allow dragging the receiver into the toolbar at more than one position, otherwise NOfalse.

    Discussion

    You use this method by overriding it in a subclass to always return YEStrue; typically, you wouldn’t call it. By default, if an item with the same identifier is already in the toolbar, dragging it in again will effectively move it to the new position.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • NSToolbarItem defines the following standard toolbar item identifiers.

    Declaration

    Swift

    let NSToolbarSeparatorItemIdentifier: String let NSToolbarSpaceItemIdentifier: String let NSToolbarFlexibleSpaceItemIdentifier: String let NSToolbarShowColorsItemIdentifier: String let NSToolbarShowFontsItemIdentifier: String let NSToolbarCustomizeToolbarItemIdentifier: String let NSToolbarPrintItemIdentifier: String

    Objective-C

    NSString *NSToolbarSeparatorItemIdentifier; NSString *NSToolbarSpaceItemIdentifier; NSString *NSToolbarFlexibleSpaceItemIdentifier; NSString *NSToolbarShowColorsItemIdentifier; NSString *NSToolbarShowFontsItemIdentifier; NSString *NSToolbarCustomizeToolbarItemIdentifier; NSString *NSToolbarPrintItemIdentifier;

    Constants

    • NSToolbarSeparatorItemIdentifier

      NSToolbarSeparatorItemIdentifier

      The Separator item.

      In OS X v10.7 and later the separator icon has been removed from the toolbar and customization palettes. This constant is ignored.

      Available in OS X v10.0 and later.

    • NSToolbarSpaceItemIdentifier

      NSToolbarSpaceItemIdentifier

      The Space item.

      Available in OS X v10.0 and later.

    • NSToolbarFlexibleSpaceItemIdentifier

      NSToolbarFlexibleSpaceItemIdentifier

      The Flexible Space item.

      Available in OS X v10.0 and later.

    • NSToolbarShowColorsItemIdentifier

      NSToolbarShowColorsItemIdentifier

      The Colors item. Shows the color panel.

      Available in OS X v10.0 and later.

    • NSToolbarShowFontsItemIdentifier

      NSToolbarShowFontsItemIdentifier

      The Fonts item. Shows the font panel.

      Available in OS X v10.0 and later.

    • NSToolbarCustomizeToolbarItemIdentifier

      NSToolbarCustomizeToolbarItemIdentifier

      The Customize item. Shows the customization palette.

      In OS X v10.7 and later the customization icon has been removed from the toolbar and customization palettes. This constant is ignored.

      Available in OS X v10.0 and later.

    • NSToolbarPrintItemIdentifier

      NSToolbarPrintItemIdentifier

      The Print item. Sends printDocument: to firstResponder.

      Available in OS X v10.0 and later.

  • When a toolbar does not have enough space to fit all its items, it must push some items into the overflow menu. These values allow you to suggest a priority for a toolbar item.

    Declaration

    Swift

    var NSToolbarItemVisibilityPriorityStandard: Int { get } var NSToolbarItemVisibilityPriorityLow: Int { get } var NSToolbarItemVisibilityPriorityHigh: Int { get } var NSToolbarItemVisibilityPriorityUser: Int { get }

    Objective-C

    enum { NSToolbarItemVisibilityPriorityStandard = 0, NSToolbarItemVisibilityPriorityLow = -1000, NSToolbarItemVisibilityPriorityHigh = 1000, NSToolbarItemVisibilityPriorityUser = 2000 };

    Constants

    • NSToolbarItemVisibilityPriorityStandard

      NSToolbarItemVisibilityPriorityStandard

      The default visibility priority.

      Available in OS X v10.4 and later.

    • NSToolbarItemVisibilityPriorityLow

      NSToolbarItemVisibilityPriorityLow

      Items with this priority will be the first items to be pushed to the overflow menu.

      Available in OS X v10.4 and later.

    • NSToolbarItemVisibilityPriorityHigh

      NSToolbarItemVisibilityPriorityHigh

      Items with this priority are less inclined to be pushed to the overflow menu.

      Available in OS X v10.4 and later.

    • NSToolbarItemVisibilityPriorityUser

      NSToolbarItemVisibilityPriorityUser

      Items with this priority are the last to be pushed to the overflow menu. Only the user should set items to this priority.

      Available in OS X v10.4 and later.

    Discussion

    To suggest that an item always remain visible, give it a value greater than NSToolbarItemVisibilityPriorityStandard, but less than NSToolbarItemVisibilityPriorityUser. In configurable toolbars, users can control the priority of an item and the priority is autosaved by the NSToolbar. These values are used by the setVisibilityPriority: and visibilityPriority methods: