---

NSMenuItem

Overview

The NSMenuItem class defines objects that are used as command items in menus. Additionally, the NSMenuItem class also includes some private functionality needed to maintain binary compatibility with other components of Cocoa. Because of this fact, you cannot replace the NSMenuItem class with a different class. You may, however, subclass NSMenuItem if necessary.

Interfaces Implemented

• action

• tag

Tasks

Constructors

• NSMenuItem

Enabling a Menu Item

• setEnabled
• isEnabled

Setting the Target and Action

• setTarget
• target
• setAction
• action

Setting the Title

• setTitle
• title
• setAttributedTitle
• attributedTitle

Setting the Tag

• setTag
• tag

Setting the State

• setState
• state

Setting the Image

• setImage
• image
• setOnStateImage
• onStateImage
• setOffStateImage
• offStateImage
• setMixedStateImage
• mixedStateImage

Managing Submenus

• setSubmenu
• submenu
• hasSubmenu

Getting a Separator Item

• protocolSeparatorItem
• separatorItem
• isSeparatorItem

Setting the Owning Menu

• setMenu
• menu

Managing Key Equivalents

• setKeyEquivalent
• keyEquivalent
• setKeyEquivalentModifierMask
• keyEquivalentModifierMask

Managing Mnemonics

• setMnemonicLocation
• mnemonicLocation
• setTitleWithMnemonic
• mnemonic

Managing User Key Equivalents

• setUsesUserKeyEquivalents
• usesUserKeyEquivalents
• userKeyEquivalent
• userKeyEquivalentModifierMask

Managing Alternates

• setAlternate
• isAlternate

Managing Indentation Levels

• setIndentationLevel
• indentationLevel

Managing Tool Tips

• setToolTip
• toolTip

Representing an Object

• setRepresentedObject
• representedObject

Static Methods

protocolSeparatorItem

Returns a menu item that is used to separate logical groups of menu commands.

public static _NSObsoleteMenuItemProtocol protocolSeparatorItem()

Discussion

This menu item is disabled. The default separator item is blank space.

See Also

• isSeparatorItem
• setEnabled

setUsesUserKeyEquivalents

If flag is true, menu items conform to user preferences for key equivalents; otherwise, the key equivalents originally assigned to the menu items are used.

public static void setUsesUserKeyEquivalents(boolean flag)

See Also

• usesUserKeyEquivalents
• userKeyEquivalent

usesUserKeyEquivalents

Returns true if menu items conform to user preferences for key equivalents; otherwise, returns false.

public static boolean usesUserKeyEquivalents()

See Also

• setUsesUserKeyEquivalents
• userKeyEquivalent

Instance Methods

action

Returns the receiver’s action method.

public NSSelector action()

See Also

• target
• setAction

attributedTitle

Returns the custom title string for a menu item.

public NSAttributedString attributedTitle()

Availability

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

See Also

• setAttributedTitle
• title

hasSubmenu

Returns true if the receiver has a submenu, false if it doesn’t.

public boolean hasSubmenu()

See Also

• setSubmenuForItem (NSMenu)

image

Returns the image displayed by the receiver, or null if it displays no image.

public NSImage image()

See Also

• setImage

indentationLevel

Returns the menu item indentation level for the receiver.

public int indentationLevel()

Discussion

The return value is from 0 to 15. The default indentation level is 0.

Availability

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

See Also

• setIndentationLevel

isAlternate

Returns whether the receiver is an alternate to the previous menu item.

public boolean isAlternate()

Availability

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

See Also

• setAlternate

isEnabled

Returns true if the receiver is enabled, false if not.

public boolean isEnabled()

See Also

• setEnabled

isSeparatorItem

Returns whether the receiver is a separator item (that is, a menu item used to visually segregate related menu items).

public boolean isSeparatorItem()

See Also

• separatorItem

keyEquivalent

Returns the receiver’s unmodified keyboard equivalent, or the empty string if one hasn’t been defined.

public String keyEquivalent()

Discussion

Use keyEquivalentModifierMask to determine the modifier mask for the key equivalent.

See Also

• userKeyEquivalent
• mnemonic
• setKeyEquivalent

keyEquivalentModifierMask

Returns the receiver’s keyboard equivalent modifier mask.

public int keyEquivalentModifierMask()

See Also

• setKeyEquivalentModifierMask

menu

Returns the menu to which the receiver belongs, or null if no menu has been set.

public NSMenu menu()

See Also

• setMenu

mixedStateImage

Returns the image used to depict a “mixed state.”

public NSImage mixedStateImage()

Discussion

A mixed state is useful for indicating “off” and “on” attribute values in a group of selected objects, such as a selection of text containing boldface and plain (nonboldface) words. By default this is a horizontal line.

See Also

• setMixedStateImage

mnemonic

Deprecated. Returns the character in the menu item title that appears underlined for use as a mnemonic.

public String mnemonic()

Discussion

If there is no mnemonic character, returns an empty string.

See Also

• setTitleWithMnemonic

mnemonicLocation

Deprecated. Returns the position of the underlined character in the menu item title used as a mnemonic.

public int mnemonicLocation()

Discussion

The position is the 0 based index of that character in the title string. If the receiver has no mnemonic character, returns NSArray.NotFound.

See Also

• setMnemonicLocation

offStateImage

Returns the image used to depict the receiver’s “off” state, or null if the image has not been set.

public NSImage offStateImage()

Discussion

By default there is no image.

See Also

• setOffStateImage

onStateImage

Returns the image used to depict the receiver’s “on” state, or null if the image has not been set.

public NSImage onStateImage()

Discussion

By default this image is a checkmark.

See Also

• setOnStateImage

representedObject

Returns the object that the receiving menu item represents.

public Object representedObject()

Discussion

For example, you might have a menu list the names of views that are swapped into the same panel. The represented objects would be the appropriate NSView objects. The user would then be able to switch back and forth between the different views that are displayed by selecting the various menu items.

See Also

• tag
• setRepresentedObject

separatorItem

Returns a menu item that is used to separate logical groups of menu commands.

public NSMenuItem separatorItem()

Discussion

This menu item is disabled. The default separator item is blank space.

See Also

• isSeparatorItem
• setEnabled

setAction

Sets the receiver’s action method to aSelector.

public void setAction(NSSelector aSelector)

Discussion

See Action Messages for additional information on action messages.

See Also

• setTarget
• action

setAlternate

Marks the receiver as an alternate to the previous menu item.

public void setAlternate(boolean isAlternate)

Discussion

If the receiver has the same key equivalent as the previous item, but has different key equivalent modifiers, the items are folded into a single visible item and the appropriate item shows while tracking the menu. The menu items may also have no key equivalent as long as the key equivalent modifiers are different.

If there are two or more items with no key equivalent but different modifiers, then the only way to get access to the alternate items is with the mouse. If you mark items as alternates but their key equivalents don’t match, they might be displayed as separate items. Marking the first item as an alternate has no effect.

The isAlternate value is archived.

Availability

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

See Also

• isAlternate

setAttributedTitle

Specifies a custom string for a menu item.

public void setAttributedTitle(NSAttributedString string)

Discussion

You can use this method to add styled text and embedded images to menu item strings. If you do not set a text color for the attributed string, it is black when not selected, white when selected, and gray when disabled. Colored text remains unchanged when selected.

When you call this method to set the menu title to an attributed string, the setTitle method is also called to set the menu title with a plain string. If you clear the attributed title, the plain title remains unchanged. To clear the attributed title, set the attributed string to either null or an empty attributed string.

The attributed string is not archived in the old nib format.

Availability

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

See Also

• attributedTitle
• setTitle

setEnabled

Sets whether the receiver is enabled based on flag.

public void setEnabled(boolean flag)

Discussion

If a menu item is disabled, its keyboard equivalent is also disabled. See the “NSMenu.MenuValidation” interface specification for cautions regarding this method.

See Also

• isEnabled

setImage

Sets the receiver’s image to menuImage.

public void setImage(NSImage menuImage)

Discussion

If menuImage is null, the current image (if any) is removed. This image is not affected by changes in menu-item state.

See Also

• image

setIndentationLevel

Sets the menu item indentation level for the receiver.

public void setIndentationLevel(int indentationLevel)

Discussion

The value for indentationLevel may be from 0 to 15. If indentationLevel is greater than 15, the value is pinned to the maximum. If indentationLevel is less than 0, an exception is thrown. The default indentation level is 0.

The indentationLevel value is archived.

Availability

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

See Also

• indentationLevel

setKeyEquivalent

Sets the receiver’s unmodified key equivalent to aString.

public void setKeyEquivalent(String aString)

Discussion

If you want to remove the key equivalent from a menu item, pass an empty string ("") for aString (never pass null). Use setKeyEquivalentModifierMask to set the appropriate mask for the modifier keys for the key equivalent.

If you want to specify the Backspace key as the key equivalent for a menu item, use a single character string with NSBackspaceCharacter (defined in NSText.h as 0x08) and for the Forward Delete key, use NSDeleteCharacter (defined in NSText.h as 0x7F). Note that these are not the same characters you get from an NSEvent key-down event when pressing those keys.

See Also

• setMnemonicLocation
• keyEquivalent

setKeyEquivalentModifierMask

Sets the receiver’s keyboard equivalent modifiers (indicating modifiers such as the Shift or Option keys) to those in mask.

public void setKeyEquivalentModifierMask(int mask)

Discussion

mask is an integer bit field containing any of these modifier key masks, combined using the C bitwise OR operator:

• NSEvent.ShiftKeyMask

• NSEvent.AlternateKeyMask

• NSEvent.CommandKeyMask

• NSEvent.ControlKeyMask

You should always set NSEvent.CommandKeyMask in mask.

NSEvent.ShiftKeyMask is relevant only for function keys—that is, for key events whose modifier flags include NSEvent.FunctionKeyMask. For all other key events NSEvent.ShiftKeyMask is ignored, and characters typed while the Shift key is pressed are interpreted as the shifted versions of those characters; for example, Command-Shift-c is interpreted as Command-C.

See the NSEvent class specification for more information about modifier mask values.

See Also

• keyEquivalentModifierMask

setMenu

Sets the receiver’s menu to aMenu.

public void setMenu(NSMenu aMenu)

Discussion

This method is invoked by the owning NSMenu when the receiver is added or removed. You shouldn’t have to invoke this method in your own code, although it can be overridden to provide specialized behavior.

See Also

• menu

setMixedStateImage

Sets the image of the receiver that indicates a “mixed” state, that is, a state neither “on” nor “off.”

public void setMixedStateImage(NSImage itemImage)

Discussion

If itemImage is null, any current mixed-state image is removed. Changing state images is currently unsupported in Mac OS X.

See Also

• mixedStateImage
• setOffStateImage
• setOnStateImage
• setState

setMnemonicLocation

Deprecated. Sets the character of the menu item title at location that is to be underlined.

public void setMnemonicLocation(int location)

Discussion

location must be from 0 to 254. This character identifies the access key by which users can access the menu item.

See Also

• mnemonicLocation

setOffStateImage

Sets the image of the receiver that indicates an “off” state.

public void setOffStateImage(NSImage itemImage)

Discussion

If itemImage is null, any current off-state image is removed. Changing state images is currently unsupported in Mac OS X.

See Also

• offStateImage
• setMixedStateImage
• setOffStateImage
• setState

setOnStateImage

Sets the image of the receiver that indicates an “on” state.

public void setOnStateImage(NSImage itemImage)

Discussion

If itemImage is null, any current on-state image is removed. Changing state images is currently unsupported in Mac OS X.

See Also

• onStateImage
• setMixedStateImage
• setOffStateImage
• setState

setRepresentedObject

Sets the object represented by the receiver to anObject.

public void setRepresentedObject(Object anObject)

Discussion

By setting a represented object for a menu item, you make an association between the menu item and that object. The represented object functions as a more specific form of tag that allows you to associate any object, not just an int, with the items in a menu.

For example, an NSView object might be associated with a menu item—when the user chooses the menu item, the represented object is fetched and displayed in a panel. Several menu items might control the display of multiple views in the same panel.

See Also

• setTag
• representedObject

setState

Sets the state of the receiver to itemState, which should be one of NSCell.OffState, NSCell.OnState, or NSCell.MixedState.

public void setState(int itemState)

Discussion

The image associated with the new state is displayed to the left of the menu item.

See Also

• state
• setMixedStateImage
• setOffStateImage
• setOnStateImage

setSubmenu

Sets the submenu of the receiver to aSubmenu.

public void setSubmenu(NSMenu aSubmenu)

Discussion

The default implementation of the NSMenuItem class throws an exception if aSubmenu already has a supermenu.

See Also

• submenu
• hasSubmenu

setTag

Sets the receiver’s tag to anInt.

public void setTag(int anInt)

See Also

• setRepresentedObject
• tag

setTarget

Sets the receiver’s target to anObject.

public void setTarget(Object anObject)

See Also

• setAction
• target

setTitle

Sets the receiver’s title to aString.

public void setTitle(String aString)

See Also

• title

setTitleWithMnemonic

Deprecated. Sets the title of a menu item with a character denoting an access key.

public void setTitleWithMnemonic(String aString)

Discussion

Use an ampersand character to mark the character (the one following the ampersand) to be designated.

See Also

• mnemonic
• setMnemonicLocation

setToolTip

Sets a help tag for a menu item.

public void setToolTip(String toolTip)

Discussion

You can call this method for any menu item, including items in the main menu bar.

This string is not archived in the old nib format.

Availability

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

See Also

• toolTip

state

Returns the state of the receiver, which is NSCell.OffState (the default), NSCell.OnState, or NSCell.MixedState.

public int state()

See Also

• setState

submenu

Returns the submenu associated with the receiving menu item, or null if no submenu is associated with it.

public NSMenu submenu()

Discussion

If the receiver responds true to hasSubmenu, the submenu is returned.

See Also

• hasSubmenu
• setSubmenu

tag

Returns the receiver’s tag.

public int tag()

See Also

• representedObject
• setTag

target

Returns the receiver’s target.

public Object target()

See Also

• action
• setTarget

title

Returns the receiver’s title.

public String title()

See Also

• setTitle

toolTip

Returns the help tag for a menu item.

public String toolTip()

Availability

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

See Also

• setToolTip

userKeyEquivalent

Returns the user-assigned key equivalent for the receiver.

public String userKeyEquivalent()

See Also

• keyEquivalent

userKeyEquivalentModifierMask

Returns the modifier mask for the receiver’s user-assigned key equivalent.

public int userKeyEquivalentModifierMask()

---