Mac Developer Library

Developer

AppKit Framework Reference NSToolbarItem Class Reference

Options
Deployment Target:

On This Page
Language:

NSToolbarItem

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.

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    var itemIdentifier: String { get }

    Objective-C

    @property(readonly, copy) NSString *itemIdentifier

    Availability

    Available in OS X v10.0 and later.

  • The toolbar that is using the receiver. (read-only)

    Declaration

    Swift

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

    Objective-C

    @property(readonly, assign) NSToolbar *toolbar

    Availability

    Available in OS X v10.0 and later.

  • The receiver’s label.

    Declaration

    Swift

    var label: String

    Objective-C

    @property(copy) NSString *label

    Discussion

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

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    var paletteLabel: String

    Objective-C

    @property(copy) NSString *paletteLabel

    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.

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    var toolTip: String?

    Objective-C

    @property(copy) NSString *toolTip

    Availability

    Available in OS X v10.0 and later.

  • The receiver’s menu form representation.

    Declaration

    Swift

    var menuFormRepresentation: NSMenuItem?

    Objective-C

    @property(strong) NSMenuItem *menuFormRepresentation

    Discussion

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

    Availability

    Available in OS X v10.0 and later.

  • tag tag Property

    The receiver’s tag.

    Declaration

    Swift

    var tag: Int

    Objective-C

    @property NSInteger tag

    Discussion

    You can use the tag for your own custom purpose.

    Availability

    Available in OS X v10.0 and later.

  • The receiver’s target.

    Declaration

    Swift

    weak var target: AnyObject?

    Objective-C

    @property(weak) id target

    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.

    Availability

    Available in OS X v10.0 and later.

    See Also

    action
    validateToolbarItem: (NSToolbarValidation)

  • The receiver’s action.

    Declaration

    Swift

    var action: Selector

    Objective-C

    @property SEL action

    Availability

    Available in OS X v10.0 and later.

    See Also

    target

  • A Boolean value that indicates whether the receiver is enabled.

    Declaration

    Swift

    var enabled: Bool

    Objective-C

    @property(getter=isEnabled) BOOL enabled

    Discussion

    YEStrue if the receiver is enabled, otherwise NOfalse.

    Availability

    Available in OS X v10.10 and later.

    See Also

    view

  • The image of the receiver.

    Declaration

    Swift

    var image: NSImage?

    Objective-C

    @property(strong) NSImage *image

    Availability

    Available in OS X v10.0 and later.

  • view view Property

    The receiver’s view.

    Declaration

    Swift

    var view: NSView?

    Objective-C

    @property(strong) NSView *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.

    Availability

    Available in OS X v10.0 and later.

  • The receiver’s minimum size.

    Declaration

    Swift

    var minSize: NSSize

    Objective-C

    @property NSSize minSize

    Discussion

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

    Availability

    Available in OS X v10.0 and later.

  • The receiver’s maximum size.

    Declaration

    Swift

    var maxSize: NSSize

    Objective-C

    @property NSSize maxSize

    Discussion

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

    Availability

    Available in OS X v10.0 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.

    Availability

    Available in OS X v10.0 and later.

    See Also

    enabled

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

    Declaration

    Swift

    var autovalidates: Bool

    Objective-C

    @property BOOL autovalidates

    Discussion

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

    Availability

    Available in OS X v10.4 and later.

  • A Boolean value that indicates whether the receiver can be represented in the toolbar at more than one position. (read-only)

    Declaration

    Swift

    var allowsDuplicatesInToolbar: Bool { get }

    Objective-C

    @property(readonly) BOOL allowsDuplicatesInToolbar

    Discussion

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

    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.

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