- Inherits from:
- com.apple.yellow.foundation.NSObject
- Implements:
- _NSObsoleteMenuItemProtocol
- Package:
- com.apple.yellow.application
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.
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.
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.
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);
- 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
public NSMenuItem()
public NSMenuItem(
String aString,
NSSelector selector,
String aString)
public static _NSObsoleteMenuItemProtocol protocolSeparatorItem()
See Also: isSeparatorItem, setEnabled
public static void setUsesUserKeyEquivalents(boolean flag)
See Also: usesUserKeyEquivalents, userKeyEquivalent
public static boolean usesUserKeyEquivalents()
See Also: setUsesUserKeyEquivalents, userKeyEquivalent
public NSSelector action()
public boolean hasSubmenu()
See Also: setSubmenuForItem (NSMenu)
public NSImage image()
See Also: setImage
public boolean isEnabled()
See Also: setEnabled
public boolean isSeparatorItem()
See Also: separatorItem
public String keyEquivalent()
See Also: userKeyEquivalent, mnemonic, setKeyEquivalent
public int keyEquivalentModifierMask()
See Also: setKeyEquivalentModifierMask
public NSMenu menu()
See Also: setMenu
public NSImage mixedStateImage()
See Also: setMixedStateImage
public String mnemonic()
See Also: setTitleWithMnemonic
public int mnemonicLocation()
NotFound
.See Also: setMnemonicLocation
public NSImage offStateImage()
See Also: setOffStateImage
public NSImage onStateImage()
See Also: setOnStateImage
public Object representedObject()
See Also: tag, setRepresentedObject
public NSMenuItem separatorItem()
See Also: isSeparatorItem, setEnabled
public void setAction(NSSelector aSelector)
public void setEnabled(boolean flag)
See Also: isEnabled
public void setImage(NSImage menuImage)
See Also: image
public void setKeyEquivalent(String aString)
See Also: setMnemonicLocation, keyEquivalent
public void setKeyEquivalentModifierMask(int mask)
ShiftKeyMask
AlternateKeyMask
CommandKeyMask
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
public void setMenu(NSMenu aMenu)
See Also: menu
public void setMixedStateImage(NSImage itemImage)
See Also: mixedStateImage, setOffStateImage, setOnStateImage, setState
public void setMnemonicLocation(int location)
See Also: mnemonicLocation
public void setOffStateImage(NSImage itemImage)
See Also: offStateImage, setMixedStateImage, setOffStateImage, setState
public void setOnStateImage(NSImage itemImage)
See Also: onStateImage, setMixedStateImage, setOffStateImage, setState
public void setRepresentedObject(Object anObject)
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
public void setState(int itemState)
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
public void setSubmenu(NSMenu aSubmenu)
See Also: submenu, hasSubmenu
public void setTag(int anInt)
See Also: setRepresentedObject, tag
public void setTarget(Object anObject)
public void setTitle(String aString)
See Also: title
public void setTitleWithMnemonic(String aString)
[aMenuItem.setTitleWithMnemonic ("Re&ceive");]
See Also: mnemonic, setMnemonicLocation
public int state()
OffState
(the default), OnState
,
or MixedState
.See Also: setState
public NSMenu submenu()
See Also: hasSubmenu, setSubmenu
public int tag()
See Also: representedObject, setTag
public Object target()
public String title()
See Also: setTitle
public String userKeyEquivalent()
See Also: keyEquivalent
public int userKeyEquivalentModifierMask()