---

NSToolbarItem Class Reference

Overview

Each item in an NSToolbar is an instance of NSToolbarItem.

Adopted Protocols

• – copyWithZone:

• – action

• – tag

Tasks

Creating a Toolbar Item

• – initWithItemIdentifier:

Managing Attributes

• – itemIdentifier
• – toolbar
• – label
• – setLabel:
• – paletteLabel
• – setPaletteLabel:
• – toolTip
• – setToolTip:
• – menuFormRepresentation
• – setMenuFormRepresentation:
• – tag
• – setTag:
• – target
• – setTarget:
• – action
• – setAction:
• – isEnabled
• – setEnabled:
• – image
• – setImage:
• – view
• – setView:
• – minSize
• – setMinSize:
• – maxSize
• – setMaxSize:

Visibility Priority

• – visibilityPriority
• – setVisibilityPriority:

Validation

• – validate
• – autovalidates
• – setAutovalidates:

Controlling Duplicates

• – allowsDuplicatesInToolbar

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 Mac OS X v10.0 and later.

See Also

• – setAction:

Related Sample Code

• EnhancedDataBurn
• ToolbarSample

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 Mac 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 Mac OS X v10.4 and later.

See Also

• – setAutovalidates:

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 Mac OS X v10.0 and later.

See Also

• – setImage:

Related Sample Code

• ToolbarSample

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 Mac OS X v10.0 and later.

Related Sample Code

• EnhancedDataBurn
• GridCalendar
• iSpend
• Quartz Composer QCTV
• ToolbarSample

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 Mac OS X v10.0 and later.

See Also

• – setEnabled:
• – view

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 Mac OS X v10.0 and later.

See Also

• – initWithItemIdentifier:

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 Mac OS X v10.0 and later.

See Also

• – setLabel:
• – menuFormRepresentation

Related Sample Code

• PDFKitLinker2
• Quartz Composer QCTV
• ToolbarSample

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 Mac OS X v10.0 and later.

See Also

• – setMaxSize:

Related Sample Code

• Quartz Composer QCTV

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 Mac OS X v10.0 and later.

See Also

• – setMenuFormRepresentation:

Related Sample Code

• ToolbarSample

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 Mac OS X v10.0 and later.

See Also

• – setMinSize:

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 Mac OS X v10.0 and later.

See Also

• – setPaletteLabel:

Related Sample Code

• ToolbarSample

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.

See Action Messages for additional information on action messages.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – action
• – setTarget:

Related Sample Code

• EnhancedDataBurn
• GridCalendar
• iSpend
• PDFKitLinker2
• ToolbarSample

Declared In

NSToolbarItem.h

setAutovalidates:

Sets the receiver’s auto validation flag.

- (void)setAutovalidates:(BOOL)resistance

Parameters

resistance

YES to set the receiver to be automatically 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 Mac OS X v10.4 and later.

See Also

• – autovalidates

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 Mac OS X v10.0 and later.

See Also

• – isEnabled

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 Mac OS X v10.0 and later.

See Also

• – image
• – view

Related Sample Code

• EnhancedDataBurn
• GridCalendar
• iSpend
• PDFKitLinker2
• ToolbarSample

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 Mac OS X v10.0 and later.

See Also

• – label
• – paletteLabel

Related Sample Code

• EnhancedDataBurn
• GridCalendar
• iSpend
• PDFKitLinker2
• ToolbarSample

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 Mac OS X v10.0 and later.

See Also

• – maxSize

Related Sample Code

• iSpend
• PDFKitLinker2
• Quartz Composer QCTV
• ToolbarSample

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 Mac OS X v10.0 and later.

See Also

• – menuFormRepresentation

Related Sample Code

• PDFKitLinker2
• ToolbarSample

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” for a discussion on item sizes.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – minSize

Related Sample Code

• iSpend
• PDFKitLinker2
• Quartz Composer QCTV
• ToolbarSample

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 Mac OS X v10.0 and later.

See Also

• – paletteLabel
• – setLabel:

Related Sample Code

• EnhancedDataBurn
• GridCalendar
• iSpend
• PDFKitLinker2
• ToolbarSample

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 Mac OS X v10.0 and later.

See Also

• – tag

Declared In

NSToolbarItem.h

setTarget:

Sets the receiver’s target.

- (void)setTarget:(id)target

Parameters

target

The target for the receiver.

Discussion

If target is nil, the toolbar will call action on the first responder that implements it (see About the Responder Chain).

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – target
• – setAction:
• – validateToolbarItem: (NSToolbarValidation)

Related Sample Code

• EnhancedDataBurn
• iSpend
• PDFKitLinker2
• ToolbarSample

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 Mac OS X v10.0 and later.

See Also

• – toolTip

Related Sample Code

• EnhancedDataBurn
• GridCalendar
• iSpend
• PDFKitLinker2
• ToolbarSample

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 Mac OS X v10.0 and later.

See Also

• – view
• – setMaxSize:
• – setMinSize:

Related Sample Code

• iSpend
• PDFKitLinker2
• Quartz Composer QCTV
• ToolbarSample

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 Mac OS X v10.4 and later.

See Also

• – visibilityPriority

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 Mac OS X v10.0 and later.

See Also

• – setTag:

Declared In

NSToolbarItem.h

target

Returns the receiver’s target.

- (id)target

Return Value

The receiver’s target.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setTarget:

Related Sample Code

• EnhancedDataBurn
• ToolbarSample

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 Mac 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 Mac OS X v10.0 and later.

See Also

• – setToolTip:

Related Sample Code

• ToolbarSample

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 Mac OS X v10.0 and later.

See Also

• – setEnabled:

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 Mac OS X v10.0 and later.

See Also

• – setView:

Related Sample Code

• PDFKitLinker2
• Quartz Composer QCTV
• ToolbarSample

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 Mac OS X v10.4 and later.

See Also

• – setVisibilityPriority:

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.

Available in Mac OS X v10.0 and later.

Declared in NSToolbarItem.h.

NSToolbarSpaceItemIdentifier

The Space item.

Available in Mac OS X v10.0 and later.

Declared in NSToolbarItem.h.

NSToolbarFlexibleSpaceItemIdentifier

The Flexible Space item.

Available in Mac OS X v10.0 and later.

Declared in NSToolbarItem.h.

NSToolbarShowColorsItemIdentifier

The Colors item. Shows the color panel.

Available in Mac OS X v10.0 and later.

Declared in NSToolbarItem.h.

NSToolbarShowFontsItemIdentifier

The Fonts item. Shows the font panel.

Available in Mac OS X v10.0 and later.

Declared in NSToolbarItem.h.

NSToolbarCustomizeToolbarItemIdentifier

The Customize item. Shows the customization palette.

Available in Mac OS X v10.0 and later.

Declared in NSToolbarItem.h.

NSToolbarPrintItemIdentifier

The Print item. Sends printDocument: to firstResponder, but you can change this in toolbarWillAddItem: if you need to do so.

Available in Mac OS X v10.0 and later.

Declared in NSToolbarItem.h.

Discussion

The following figure illustrates the items in the order in which they are described above.

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

---