---

NSToolbarItem

Overview

Each item in an NSToolbar is an instance of NSToolbarItem.

Interfaces Implemented

• action

• tag

Tasks

Constructors

• NSToolbarItem

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.

public NSSelector action()

Discussion

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

See Also

• setAction

allowsDuplicatesInToolbar

Returns true to allow dragging the receiver into the toolbar at more than one position.

public boolean allowsDuplicatesInToolbar()

Discussion

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

autovalidates

Returns whether the receiver is automatically validated by the toolbar.

public boolean autovalidates()

Availability

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

See Also

• setAutovalidates

image

Returns the image of the receiver.

public NSImage image()

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.

See Also

• setImage

isEnabled

Returns the receiver’s enabled status.

public boolean isEnabled()

Discussion

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

See Also

• setEnabled
• view

itemIdentifier

Returns the receiver’s identifier, which was provided in the constructor.

public String itemIdentifier()

See Also

• NSToolbarItem

label

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

public String label()

Discussion

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

See Also

• setLabel
• menuFormRepresentation

maxSize

Returns the receiver’s maximum size.

public NSSize maxSize()

Discussion

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

See Also

• setMaxSize

menuFormRepresentation

Returns the receiver’s menu form representation.

public NSMenuItem menuFormRepresentation()

Discussion

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

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

See Also

• setMenuFormRepresentation

minSize

Returns the receiver’s minimum size.

public NSSize minSize()

Discussion

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

See Also

• setMinSize

paletteLabel

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

public String 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.

See Also

• setPaletteLabel

setAction

Sets the receiver’s action to action.

public void setAction(NSSelector action)

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.

See Also

• action
• setTarget

setAutovalidates

Sets the receiver’s auto validation flag to enabled.

public void setAutovalidates(boolean resistance)

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

setEnabled

Sets the receiver’s enabled flag to enabled.

public void setEnabled(boolean enabled)

Discussion

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

See Also

• isEnabled

setImage

Sets the image of the receiver or of the view to image, if the view has already been set.

public void setImage(NSImage image)

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.

See Also

• image
• view

setLabel

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

public void setLabel(String label)

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. It’s OK for an item to have an empty label. You should make sure the length of the label is appropriate and not too long. For a discussion on labels, see “Setting a Toolbar Item’s Representation”.

See Also

• label
• paletteLabel

setMaxSize

Sets the receiver’s maximum size to size.

public void setMaxSize(NSSize size)

Discussion

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

See Also

• maxSize

setMenuFormRepresentation

Sets the receiver’s menu form to menuItem.

public void setMenuFormRepresentation(NSMenuItem menuItem)

Discussion

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

See Also

• menuFormRepresentation

setMinSize

Sets the receiver’s minimum size to size.

public void setMinSize(NSSize size)

Discussion

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

See Also

• minSize

setPaletteLabel

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

public void setPaletteLabel(String 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.

See Also

• paletteLabel
• setLabel

setTag

Sets the receiver’s tag to tag, which can be used for your own custom purpose.

public void setTag(int tag)

See Also

• tag

setTarget

Sets the receiver’s target.

public void setTarget(Object target)

Discussion

If target is unset, the toolbar will call action on the first responder that implements it.

See Also

• target
• setAction
• validateToolbarItem (NSToolbar.ItemValidation)

setToolTip

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

public void setToolTip(String toolTip)

See Also

• toolTip

setView

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

public void setView(NSView view)

Discussion

Note that many of the set/get methods are implemented by calls forwarded to view, if it responds to it. Also, everything recursively contained in view must be archivable if the customization palette is used. For a view item to be archivable, it and all of its contents must implement clone() correctly. This implementation is not an issue for standard framework components, but you must be careful with subclasses of them.

See Also

• view
• setMaxSize
• setMinSize

setVisibilityPriority

Sets the receiver’s visibility priority to visibilityPriority.

public void setVisibiltyPriority(int visibilityPriority)

Discussion

The values for visibilityPriority are described in “Constants.”

Availability

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

See Also

• visibilityPriority

tag

Returns the receiver’s tag, which can be used for your own custom purpose.

public int tag()

See Also

• setTag

target

Returns the receiver’s target.

public Object target()

See Also

• setTarget

toolbar

Returns the toolbar that is using the receiver.

public NSToolbar toolbar()

toolTip

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

public String toolTip()

See Also

• setToolTip

validate

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

public void validate()

Discussion

You use this method by overriding it in a subclass; typically, you wouldn’t call it. For further discussion, see “Validating Toolbar Items”.

See Also

• setEnabled

view

Returns the receiver’s view.

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

See Also

• setView

visibilityPriority

Returns the receiver’s visibility priority.

public int visibilityPriority()

See Also

• setVisibilityPriority

Constants

NSToolbarItem defines the following standard toolbar item identifiers, which are described in the order they are shown in the following figure:

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

---