Next Page > Hide TOC

Legacy Documentclose button

Important: The information in this document is obsolete and should not be used for new development.

NSMenuItem

Inherits from
Implements
Package
com.apple.cocoa.application
Companion guide

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

NSValidatedUserInterfaceItem

Tasks

Constructors

Enabling a Menu Item

Setting the Target and Action

Setting the Title

Setting the Tag

Setting the State

Setting the Image

Managing Submenus

Getting a Separator Item

Setting the Owning Menu

Managing Key Equivalents

Managing Mnemonics

Managing User Key Equivalents

Managing Alternates

Managing Indentation Levels

Managing Tool Tips

Representing an Object

Constructors

NSMenuItem

Creates a new menu item with no action and key equivalent and the title "NSMenuItem".

public NSMenuItem()

Creates a new NSMenuItem.

public NSMenuItem(String itemName, NSSelector action, String charCode)

Discussion

The arguments itemName and charCode must not be null (if there is no title or key equivalent, specify an empty string). The action argument must be a valid selector or null. For instances of the NSMenuItem class, the default initial state is NSCell.OffState, the default on-state image is a checkmark, and the default mixed-state image is a dash.

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

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

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

public static boolean usesUserKeyEquivalents()

See Also

Instance Methods

action

Returns the receiver’s action method.

public NSSelector action()

See Also

attributedTitle

Returns the custom title string for a menu item.

public NSAttributedString attributedTitle()

Availability
See Also

hasSubmenu

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

public boolean hasSubmenu()

See Also

image

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

public NSImage image()

See Also

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
See Also

isAlternate

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

public boolean isAlternate()

Availability
See Also

isEnabled

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

public boolean isEnabled()

See Also

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

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

keyEquivalentModifierMask

Returns the receiver’s keyboard equivalent modifier mask.

public int keyEquivalentModifierMask()

See Also

menu

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

public NSMenu menu()

See Also

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

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

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

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

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

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

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

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

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
See Also

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
See Also

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

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

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
See Also

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

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:

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

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

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

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

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

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

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

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

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

setTag

Sets the receiver’s tag to anInt.

public void setTag(int anInt)

See Also

setTarget

Sets the receiver’s target to anObject.

public void setTarget(Object anObject)

See Also

setTitle

Sets the receiver’s title to aString.

public void setTitle(String aString)

See Also

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

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
See Also

state

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

public int state()

See Also

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

tag

Returns the receiver’s tag.

public int tag()

See Also

target

Returns the receiver’s target.

public Object target()

See Also

title

Returns the receiver’s title.

public String title()

See Also

toolTip

Returns the help tag for a menu item.

public String toolTip()

Availability
See Also

userKeyEquivalent

Returns the user-assigned key equivalent for the receiver.

public String userKeyEquivalent()

See Also

userKeyEquivalentModifierMask

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

public int userKeyEquivalentModifierMask()



Next Page > Hide TOC


© 1997, 2007 Apple Inc. All Rights Reserved. (Last updated: 2007-02-01)


Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.