NSToolbarItem Class Reference

Inherits from
NSObject
Conforms to
NSValidatedUserInterfaceItem
NSCopying
NSObject (NSObject)
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.0 and later.
Companion guide
Toolbar Programming Topics for Cocoa
Declared in
NSToolbarItem.h
Related sample code

Overview

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

Tasks

Creating a Toolbar Item

Managing Attributes

Visibility Priority

Validation

Controlling Duplicates

Instance Methods

action

Returns the receiver’s action.

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

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSToolbarItem.h

allowsDuplicatesInToolbar

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

- (BOOL)allowsDuplicatesInToolbar
Return Value

YES to allow dragging the receiver into the toolbar at more than one position, otherwise NO.

Discussion

You use this method by overriding it in a subclass to always return YES; 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.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSToolbarItem.h

autovalidates

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

- (BOOL)autovalidates
Return Value

YES if the receiver is automatically validated by the toolbar, otherwise NO.

Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
NSToolbarItem.h

image

Returns the image of the receiver.

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

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSToolbarItem.h

initWithItemIdentifier:

Initialize the receiver with a given identifier.

- (id)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.
Related Sample Code
Declared In
NSToolbarItem.h

isEnabled

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

- (BOOL)isEnabled
Return Value

YES if the receiver is enabled, otherwise NO.

Discussion

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

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSToolbarItem.h

itemIdentifier

Returns the receiver’s identifier.

- (NSString *)itemIdentifier
Return Value

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

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSToolbarItem.h

label

Returns the receiver’s label.

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

Availability
  • Available in OS X v10.0 and later.
See Also
Related Sample Code
Declared In
NSToolbarItem.h

maxSize

Returns the receiver’s maximum size.

- (NSSize)maxSize
Return Value

The receiver’s maximum size.

Discussion

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

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSToolbarItem.h

menuFormRepresentation

Returns the receiver’s menu form representation.

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

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSToolbarItem.h

minSize

Returns the receiver’s minimum size.

- (NSSize)minSize
Return Value

The receiver’s minimum size.

Discussion

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

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSToolbarItem.h

paletteLabel

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

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

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSToolbarItem.h

setAction:

Sets the receiver’s action.

- (void)setAction:(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.

Availability
  • Available in OS X v10.0 and later.
See Also
Related Sample Code
Declared In
NSToolbarItem.h

setAutovalidates:

Sets the receiver’s auto validation flag.

- (void)setAutovalidates:(BOOL)resistance
Parameters
resistance

YES to set the receiver to automatically be validated by the toolbar; otherwise NO.

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.

Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
NSToolbarItem.h

setEnabled:

Sets the receiver’s enabled flag.

- (void)setEnabled:(BOOL)enabled
Parameters
enabled

YES to enable the receiver, otherwise NO.

Discussion

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

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSToolbarItem.h

setImage:

Sets the image for the receiver or of the view.

- (void)setImage:(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.

Availability
  • Available in OS X v10.0 and later.
See Also
Related Sample Code
Declared In
NSToolbarItem.h

setLabel:

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

- (void)setLabel:(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”.

Availability
  • Available in OS X v10.0 and later.
See Also
Related Sample Code
Declared In
NSToolbarItem.h

setMaxSize:

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

- (void)setMaxSize:(NSSize)size
Parameters
size

The maximum size for the receiver.

Discussion

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

Availability
  • Available in OS X v10.0 and later.
See Also
Related Sample Code
Declared In
NSToolbarItem.h

setMenuFormRepresentation:

Sets the receiver’s menu form.

- (void)setMenuFormRepresentation:(NSMenuItem *)menuItem
Parameters
menuItem

The menu form for the receiver.

Discussion

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

Availability
  • Available in OS X v10.0 and later.
See Also
Related Sample Code
Declared In
NSToolbarItem.h

setMinSize:

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

- (void)setMinSize:(NSSize)size
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.

Availability
  • Available in OS X v10.0 and later.
See Also
Related Sample Code
Declared In
NSToolbarItem.h

setPaletteLabel:

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

- (void)setPaletteLabel:(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.

Availability
  • Available in OS X v10.0 and later.
See Also
Related Sample Code
Declared In
NSToolbarItem.h

setTag:

Sets the receiver’s tag.

- (void)setTag:(NSInteger)tag
Parameters
tag

The tag for the receiver.

Discussion

You can use the tag for your own custom purpose.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSToolbarItem.h

setTarget:

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

- (void)setTarget:(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.

Availability
  • Available in OS X v10.0 and later.
See Also
Related Sample Code
Declared In
NSToolbarItem.h

setToolTip:

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

- (void)setToolTip:(NSString *)toolTip
Parameters
toolTip

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

Availability
  • Available in OS X v10.0 and later.
See Also
Related Sample Code
Declared In
NSToolbarItem.h

setView:

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

- (void)setView:(NSView *)view
Parameters
view

The view for the receiver. The view and all of its contents must conform to the NSCoding protocol if the toolbar supports customization.

Discussion

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

Availability
  • Available in OS X v10.0 and later.
See Also
Related Sample Code
Declared In
NSToolbarItem.h

setVisibilityPriority:

Sets the receiver’s visibility priority.

- (void)setVisibilityPriority:(NSInteger)visibilityPriority
Parameters
visibilityPriority

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

Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
NSToolbarItem.h

tag

Returns the receiver’s tag.

- (NSInteger)tag
Return Value

The receiver’s tag.

Discussion

You can use the tag for your own custom purpose.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSToolbarItem.h

target

Returns the receiver’s target.

- (id)target
Return Value

The receiver’s target.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSToolbarItem.h

toolbar

Returns the toolbar that is using the receiver.

- (NSToolbar *)toolbar
Return Value

The toolbar that is using the receiver.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSToolbarItem.h

toolTip

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

- (NSString *)toolTip
Return Value

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

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSToolbarItem.h

validate

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

- (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
Related Sample Code
Declared In
NSToolbarItem.h

view

Returns the receiver’s view.

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

Availability
  • Available in OS X v10.0 and later.
See Also
Related Sample Code
Declared In
NSToolbarItem.h

visibilityPriority

Returns the receiver’s visibility priority.

- (NSInteger)visibilityPriority
Return Value

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

Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
NSToolbarItem.h

Constants

Standard Identifiers

NSToolbarItem defines the following standard toolbar item identifiers.

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

The Separator item. (Deprecated. 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.

Declared in NSToolbarItem.h.

NSToolbarSpaceItemIdentifier

The Space item.

Available in OS X v10.0 and later.

Declared in NSToolbarItem.h.

NSToolbarFlexibleSpaceItemIdentifier

The Flexible Space item.

Available in OS X v10.0 and later.

Declared in NSToolbarItem.h.

NSToolbarShowColorsItemIdentifier

The Colors item. Shows the color panel.

Available in OS X v10.0 and later.

Declared in NSToolbarItem.h.

NSToolbarShowFontsItemIdentifier

The Fonts item. Shows the font panel.

Available in OS X v10.0 and later.

Declared in NSToolbarItem.h.

NSToolbarCustomizeToolbarItemIdentifier

The Customize item. Shows the customization palette. (Deprecated. 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.

Declared in NSToolbarItem.h.

NSToolbarPrintItemIdentifier

The Print item. Sends printDocument: to firstResponder.

Available in OS X v10.0 and later.

Declared in NSToolbarItem.h.

Item Priority

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.

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

The default visibility priority.

Available in OS X v10.4 and later.

Declared in NSToolbarItem.h.

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.

Declared in NSToolbarItem.h.

NSToolbarItemVisibilityPriorityHigh

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

Available in OS X v10.4 and later.

Declared in NSToolbarItem.h.

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.

Declared in NSToolbarItem.h.

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:

Declared In
NSToolbarItem.h


© 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-07-23)

Did this document help you? Yes It's good, but... Not helpful...