---

_NSObsoleteMenuItemProtocol

Overview

Refer to the NSMenuItem class description, which replaces this interface.

Tasks

Enabling a Menu Item

• setEnabled
• isEnabled

Setting the Target and Action

• setTarget
• target
• setAction

Setting the Title

• setTitle
• title
• setAttributedTitle
• attributedTitle

Setting the Tag

• setTag

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

• isSeparatorItem

Setting the Owning Menu

• setMenu
• menu

Managing Key Equivalents

• setKeyEquivalent
• keyEquivalent
• setKeyEquivalentModifierMask
• keyEquivalentModifierMask

Managing Mnemonics

• setMnemonicLocation
• mnemonicLocation
• setTitleWithMnemonic
• mnemonic

Managing User Key Equivalents

• userKeyEquivalent
• userKeyEquivalentModifierMask

Managing Alternates

• setAlternate
• isAlternate

Managing Indentation Levels

• setIndentationLevel
• indentationLevel

Managing Tool Tips

• setToolTip
• toolTip

Representing an Object

• setRepresentedObject
• representedObject

Instance Methods

attributedTitle

Returns the custom title string for a menu item.

public abstract 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 abstract boolean hasSubmenu()

See Also

• setSubmenuForItem (NSMenu)

image

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

public abstract NSImage image()

See Also

• setImage

indentationLevel

Returns the menu item indentation level for the receiver.

public abstract int indentationLevel()

Discussion

The return value will be 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 abstract 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 abstract 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 abstract boolean isSeparatorItem()

keyEquivalent

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

public abstract 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 abstract int keyEquivalentModifierMask()

See Also

• setKeyEquivalentModifierMask

menu

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

public abstract NSMenu menu()

See Also

• setMenu

mixedStateImage

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

public abstract 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 bold and plain (nonbolded) words.

See Also

• setMixedStateImage

mnemonic

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

public abstract String mnemonic()

Discussion

If there is no mnemonic character, returns an empty string. Mnemonics are not supported in Mac OS X.

See Also

• setTitleWithMnemonic

mnemonicLocation

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

public abstract int mnemonicLocation()

Discussion

The position is the zero-based index of that character in the title string. If the receiver has no mnemonic character, returns NSArray.NotFound. Mnemonics are not supported in Mac OS X.

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 abstract NSImage offStateImage()

Discussion

By default, there is no off state 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 abstract NSImage onStateImage()

Discussion

By default, the on state image is a checkmark.

See Also

• setOnStateImage

representedObject

Returns the object that the receiving menu item represents.

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

• setRepresentedObject

setAction

Sets the receiver’s action method to aSelector.

public abstract void setAction(NSSelector aSelector)

Discussion

See Action Messages for additional information on action messages.

See Also

• setTarget

setAlternate

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

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

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

indentationLevel is archived.

Availability

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

See Also

• indentationLevel

setKeyEquivalent

Sets the receiver’s unmodified key equivalent to aKeyEquivalent.

public abstract void setKeyEquivalent(String aKeyEquivalent)

Discussion

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

See Also

• setMnemonicLocation
• keyEquivalent

setKeyEquivalentModifierMask

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

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

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 abstract 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 abstract void setMixedStateImage(NSImage itemImage)

Discussion

If itemImage is null, any current mixed-state image is removed.

See Also

• mixedStateImage
• setOffStateImage
• setOnStateImage
• setState

setMnemonicLocation

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

public abstract void setMnemonicLocation(int location)

Discussion

. This character identifies the access key by which users can access the menu item. Mnemonics are not supported in Mac OS X.

See Also

• mnemonicLocation

setOffStateImage

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

public abstract void setOffStateImage(NSImage itemImage)

Discussion

If itemImage is null, any current off-state image is removed.

See Also

• offStateImage
• setMixedStateImage
• setOffStateImage
• setState

setOnStateImage

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

public abstract void setOnStateImage(NSImage itemImage)

Discussion

If itemImage is null, any current on-state image is removed.

See Also

• onStateImage
• setMixedStateImage
• setOffStateImage
• setState

setRepresentedObject

Sets the object represented by the receiver to anObject.

public abstract 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 abstract 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 abstract void setSubmenu(NSMenu aSubmenu)

Discussion

The default implementation throws an exception if aSubmenu already has a supermenu.

See Also

• submenu
• hasSubmenu

setTag

Sets the receiver’s tag to anInt.

public abstract void setTag(int anInt)

See Also

• setRepresentedObject

setTarget

Sets the receiver’s target to anObject.

public abstract void setTarget(Object anObject)

See Also

• setAction
• target

setTitle

Sets the receiver’s title to aString.

public abstract void setTitle(String aString)

See Also

• title

setTitleWithMnemonic

Sets the title of a menu item with a character underlined to denote an access key.

public abstract void setTitleWithMnemonic(String aString)

Discussion

Mnemonics are not supported in Mac OS X.

See Also

• mnemonic
• setMnemonicLocation

setToolTip

Sets a help tag for a menu item.

public abstract 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 abstract 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 abstract NSMenu submenu()

Discussion

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

See Also

• hasSubmenu
• setSubmenu

target

Returns the receiver’s target.

public abstract Object target()

See Also

• setTarget

title

Returns the receiver’s title.

public abstract String title()

See Also

• setTitle

toolTip

Returns the help tag for a menu item.

public abstract 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 abstract String userKeyEquivalent()

See Also

• keyEquivalent

userKeyEquivalentModifierMask

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

public abstract int userKeyEquivalentModifierMask()

---