Table of Contents

NSMenuItem


Inherits from:
com.apple.yellow.foundation.NSObject
Implements:
_NSObsoleteMenuItemProtocol
Package:
com.apple.yellow.application


Class Description


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, you cannot replace the NSMenuItem class with a different class. You may, however, subclass NSMenuItem if necessary.

NSMenuItem methods allow you to set the titles, actions, targets, tags, images, enabled states, and similar attributes of individual menu items, as well as to obtain the current values of these attributes. Whenever one of a menu item's attributes change, the menu item notifies the associated NSMenu via itemChanged. NSMenuItem also allows a object to set keyboard equivalents. See the sections below for more on this functionality.See the NSMenu, NSMenuView, and NSMenuItemCell class specifications and the NSMenuValidation protocol specification for more information on menus.


Keyboard Equivalents


An NSMenuItem can be assigned a keyboard equivalent, so that when the user types a character the menu item's action is sent. The keyboard equivalent is defined in two parts. First is the basic key equivalent, which must be a Unicode character that can be generated by a single key press without modifier keys (Shift excepted). It is also possible to use a sequence of Unicode characters so long as the user's key mapping is able to generate the sequence with a single key press. The basic key equivalent is set using setKeyEquivalent and returned by keyEquivalent. The second part defines the modifier keys that must also be pressed. This is set using setKeyEquivalentModifierMask and returned by keyEquivalentModifierMask. The modifier mask by default includes CommandKeyMask, and may also include the masks for the Shift, Alternate, or other modifier keys. Specifying keyboard equivalents in two parts allows you to define a modified keyboard equivalent without having to know which character is generated by the basic key plus the modifier. For example, you can define the keyboard equivalent Command-Alt-f without having to know which character is generated by typing Alt-f.

Certain NSMenuItem methods can override assigned keyboard equivalents with those the user has specified in the defaults system. The setUsesUserKeyEquivalents method turns this behavior on or off, and usesUserKeyEquivalents returns its status. To determine the user-defined key equivalent for an NSMenuItem object, invoke the userKeyEquivalent instance method. If user-defined key equivalents are active and an NSMenuItem object has a user-defined key equivalent, its keyEquivalent method returns the user-defined key equivalent and not the one set using setKeyEquivalent.


Mnemonics


An NSMenuItem can also be assigned a mnemonic, however, they won't have any effect. Mnemonics are represented by an underlined character in the title of a menu item. The mnemonic can be any character that can be generated by a single key press without modifier keys (Shift excepted). When the menu is active, the user can type the underlined character in the menu item in order to activate that menu item. A particular mnemonic character should only be used once within the set of menu items contained either in the same menu as the menu item or in the application's main menu.


Radio-Style Grouping


By using a few NSMenuItem methods , you can implement radio-style groupings of menu commands. In other words, you can have a grouping of menu commands (usually segregated visually with separator items) and only one command in the group can be selected; the selected item is marked by an image, usually a radio-button image, but sometimes a checkmark. If the user selects another command in the group, the previous command is unmarked and the selected command displays the image. As an example of a radio-style grouping, a game could have three commands to indicate the level of play: Beginner, Intermediate, and Advanced.

To implement this feature, first set the images you want to use for the possible command states: "on," "off," and "mixed" (the last is useful for triple-state or indeterminate situations). To set the image, use the commands setOnStateImage, setOffStateImage, and setMixedStateImage. The default image for the "on" state is a checkmark (MenuCheckmark) and for the "mixed" state the image is a dash (MenuMixedState). The "off" state typically has no image. The radio-button image (which you must set explicitly) is MenuRadio.

In an action method that responds to all commands in the group use setState to uncheck the menu item that is currently marked:

curItem.setState(OffState);

Then mark the newly selected command:

sender.setState (OnState);




Method Types


Constructors
NSMenuItem
Enabling a menu item
setEnabled
isEnabled
Setting the target and action
setTarget
target
setAction
action
Setting the title
setTitle
title
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
Representing an object
setRepresentedObject
representedObject


Constructors



NSMenuItem

public NSMenuItem()

Description forthcoming.

public NSMenuItem( String aString, NSSelector selector, String aString)

Description forthcoming.


Static Methods



protocolSeparatorItem

public static _NSObsoleteMenuItemProtocol protocolSeparatorItem()

Returns a menu item that is used to separate logical groups of menu commands. This menu item is disabled. The default separator item is a simple horizontal line.

See Also: isSeparatorItem, setEnabled



setUsesUserKeyEquivalents

public static void setUsesUserKeyEquivalents(boolean flag)

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.

See Also: usesUserKeyEquivalents, userKeyEquivalent



usesUserKeyEquivalents

public static boolean usesUserKeyEquivalents()

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

See Also: setUsesUserKeyEquivalents, userKeyEquivalent




Instance Methods



action

public NSSelector action()

Returns the receiver's action method.

See Also: target, setAction



hasSubmenu

public boolean hasSubmenu()

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

See Also: setSubmenuForItem (NSMenu)



image

public NSImage image()

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

See Also: setImage



isEnabled

public boolean isEnabled()

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

See Also: setEnabled



isSeparatorItem

public boolean isSeparatorItem()

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

See Also: separatorItem



keyEquivalent

public String keyEquivalent()

Returns the receiver's unmodified keyboard equivalent, or the empty string if one hasn't been defined. Use keyEquivalentModifierMask to determine the modifier mask for the key equivalent.

See Also: userKeyEquivalent, mnemonic, setKeyEquivalent



keyEquivalentModifierMask

public int keyEquivalentModifierMask()

Returns the receiver's keyboard equivalent modifier mask.

See Also: setKeyEquivalentModifierMask



menu

public NSMenu menu()

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

See Also: setMenu



mixedStateImage

public NSImage mixedStateImage()

Returns the image used to depict a "mixed state." 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 (non-bolded) worlds.

See Also: setMixedStateImage



mnemonic

public String mnemonic()

Returns the character in the menu item title that appears underlined for use as a mnemonic. If there is no mnemonic character, returns an empty string.

See Also: setTitleWithMnemonic



mnemonicLocation

public int mnemonicLocation()

Returns the position of the underlined character in the menu item title used as a mnemonic. The position is the zero based index of that character in the title string. If the receiver has no mnemonic character, returns NotFound.

See Also: setMnemonicLocation



offStateImage

public NSImage offStateImage()

Returns the image used to depict the receiver's "off" state, or null if the image has not been set.

See Also: setOffStateImage



onStateImage

public NSImage onStateImage()

Returns the image used to depict the receiver's "on" state, or null if the image has not been set.

See Also: setOnStateImage



representedObject

public Object representedObject()

Returns the object that the receiving menu item represents. 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

public NSMenuItem separatorItem()

Returns a menu item that is used to separate logical groups of menu commands. This menu item is disabled. The default separator item is a simple horizontal line.

See Also: isSeparatorItem, setEnabled



setAction

public void setAction(NSSelector aSelector)

Sets the receiver's action method to aSelector.

See Also: setTarget, action



setEnabled

public void setEnabled(boolean flag)

Sets whether the receiver is enabled based on flag. If a menu item is disabled, its keyboard equivalent and mnemonic are also disabled. See the NSMenuValidation informal protocol specification for cautions regarding this method.

See Also: isEnabled



setImage

public void setImage(NSImage menuImage)

Sets the receiver's image to menuImage. 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



setKeyEquivalent

public void setKeyEquivalent(String aString)

Sets the receiver's unmodified key equivalent to aString. 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.

See Also: setMnemonicLocation, keyEquivalent



setKeyEquivalentModifierMask

public void setKeyEquivalentModifierMask(int mask)

Sets the receiver's keyboard equivalent modifiers (indicating modifiers such as the Shift or Alternate keys) to those in mask. mask is an integer bit field containing any of these modifier key masks, combined using the C bitwise OR operator:

You should always set CommandKeyMask in mask.

ShiftKeyMask is relevant only for function keys; that is, for key events whose modifier flags include FunctionKeyMask. For all other key events 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

public void setMenu(NSMenu aMenu)

Sets the receiver's menu to aMenu. 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

public void setMixedStateImage(NSImage itemImage)

Sets the image of the receiver that indicates a "mixed" state, that is, a state neither "on" or "off." If itemImage is null, any current mixed-state image is removed.

See Also: mixedStateImage, setOffStateImage, setOnStateImage, setState



setMnemonicLocation

public void setMnemonicLocation(int location)

Sets the character of the menu item title at location that is to be underlined. location must be between 0 and 254. This character identifies the access key by which users can access the menu item.

See Also: mnemonicLocation



setOffStateImage

public void setOffStateImage(NSImage itemImage)

Sets the image of the receiver that indicates an "off" state. If itemImage is null, any current off-state image is removed.

See Also: offStateImage, setMixedStateImage, setOffStateImage, setState



setOnStateImage

public void setOnStateImage(NSImage itemImage)

Sets the image of the receiver that indicates an "on" state. If itemImage is null, any current on-state image is removed.

See Also: onStateImage, setMixedStateImage, setOffStateImage, setState



setRepresentedObject

public void setRepresentedObject(Object anObject)

Sets the object represented by the receiver to anObject. 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

public void setState(int itemState)

Sets the state of the receiver to itemState, which should be one of OffState, OnState, or MixedState. The image associated with the new state is displayed to the left of the menu item.

See Also: state, setMixedStateImage, setOffStateImage, setOnStateImage



setSubmenu

public void setSubmenu(NSMenu aSubmenu)

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

See Also: submenu, hasSubmenu



setTag

public void setTag(int anInt)

Sets the receiver's tag to anInt.

See Also: setRepresentedObject, tag



setTarget

public void setTarget(Object anObject)

Sets the receiver's target to anObject.

See Also: setAction, target



setTitle

public void setTitle(String aString)

Sets the receiver's title to aString.

See Also: title



setTitleWithMnemonic

public void setTitleWithMnemonic(String aString)

Sets the title of a menu item with a character denoting an access key. Use an ampersand character to mark the character (the one following the ampersand) to be designated. For example, the following message causes the 'c' in 'Receive' to be designated:
[aMenuItem.setTitleWithMnemonic ("Re&ceive");]

See Also: mnemonic, setMnemonicLocation



state

public int state()

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

See Also: setState



submenu

public NSMenu submenu()

Returns the submenu associated with the receiving menu item, or null if no submenu is associated with it. If the receiver responds true to hasSubmenu, the submenu is returned.

See Also: hasSubmenu, setSubmenu



tag

public int tag()

Returns the receiver's tag.

See Also: representedObject, setTag



target

public Object target()

Returns the receiver's target.

See Also: action, setTarget



title

public String title()

Returns the receiver's title.

See Also: setTitle



userKeyEquivalent

public String userKeyEquivalent()

Returns the user-assigned key equivalent for the receiver.

See Also: keyEquivalent



userKeyEquivalentModifierMask

public int userKeyEquivalentModifierMask()

Description forthcoming.


Table of Contents