- Inherits from:
- NSObject
- Conforms to:
- NSMenuItem
- NSObject (NSObject)
Declared in:
- AppKit/NSMenuItem.h
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 NSCommandKeyMask
,
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 (NSMenuCheckmark
)
and for the "mixed" state the image is a dash (NSMenuMixedState
).
The "off" state typically has no image. The radio-button image
(which you must set explicitly) is NSMenuRadio
.
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:NSOffState];
Then mark the newly selected command:
[sender setState:NSOnState];
- Creating NSMenuItem objects
- - initWithTitle:action:keyEquivalent:
- 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
- + 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
- Representing an object
- - setRepresentedObject:
- - representedObject
+ (id <NSMenuItem>)separatorItem
See Also: - isSeparatorItem, - setEnabled:
+ (void)setUsesUserKeyEquivalents:(BOOL)flag
See Also: + usesUserKeyEquivalents, - userKeyEquivalent
+ (BOOL)usesUserKeyEquivalents
See Also: + setUsesUserKeyEquivalents:, - userKeyEquivalent
- (SEL)action
See Also: - target, - setAction:
- (BOOL)hasSubmenu
See Also: - setSubmenu:forItem: (NSMenu)
- (NSImage *)image
See Also: - setImage:
- (id)initWithTitle:(NSString
*)itemName
action:(SEL)anAction
keyEquivalent:(NSString *)charCode
NSStateOff
, the default
on-state image is a checkmark, and the default mixed-state image
is a dash.- (BOOL)isEnabled
See Also: - setEnabled:
- (BOOL)isSeparatorItem
See Also: - separatorItem
- (NSString *)keyEquivalent
See Also: - userKeyEquivalent, - mnemonic, - setKeyEquivalent:
- (unsigned int)keyEquivalentModifierMask
See Also: - setKeyEquivalentModifierMask:
- (NSMenu *)menu
See Also: - setMenu:
- (NSImage *)mixedStateImage
See Also: - setMixedStateImage:
- (NSString *)mnemonic
See Also: - setTitleWithMnemonic:
- (unsigned)mnemonicLocation
NSNotFound
.See Also: - setMnemonicLocation:
- (NSImage *)offStateImage
See Also: - setOffStateImage:
- (NSImage *)onStateImage
See Also: - setOnStateImage:
- (id)representedObject
See Also: - tag, - setRepresentedObject:
- (void)setAction:(SEL)aSelector
See Also: - setTarget:, - action
- (void)setEnabled:(BOOL)flag
See Also: - isEnabled
- (void)setImage:(NSImage
*)menuImage
See Also: - image
- (void)setKeyEquivalent:(NSString
*)aString
See Also: - setMnemonicLocation:, - keyEquivalent
- (void)setKeyEquivalentModifierMask:(unsigned
int)mask
NSShiftKeyMask
NSAlternateKeyMask
NSCommandKeyMask
You
should always set NSCommandKeyMask
in mask.
NSShiftKeyMask
is
relevant only for function keys; that is, for key events whose modifier
flags include NSFunctionKeyMask
.
For all other key events NSShiftKeyMask
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
- (void)setMenu:(NSMenu
*)aMenu
See Also: - menu
- (void)setMixedStateImage:(NSImage
*)itemImage
See Also: - mixedStateImage, - setOffStateImage:, - setOnStateImage:, - setState:
- (void)setMnemonicLocation:(unsigned)location
See Also: - mnemonicLocation
- (void)setOffStateImage:(NSImage
*)itemImage
See Also: - offStateImage, - setMixedStateImage:, - setOffStateImage:, - setState:
- (void)setOnStateImage:(NSImage
*)itemImage
See Also: - onStateImage, - setMixedStateImage:, - setOffStateImage:, - setState:
- (void)setRepresentedObject:(id)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
- (void)setState:(int)itemState
NSOffState
, NSOnState
,
or NSMixedState
. The
image associated with the new state is displayed to the left of
the menu item.See Also: - state, - setMixedStateImage:, - setOffStateImage:, - setOnStateImage:
- (void)setSubmenu:(NSMenu
*)aSubmenu
See Also: - submenu, - hasSubmenu
- (void)setTag:(int)anInt
See Also: - setRepresentedObject:, - tag
- (void)setTarget:(id)anObject
See Also: - setAction:, - target
- (void)setTitle:(NSString
*)aString
See Also: - title
- (void)setTitleWithMnemonic:(NSString
*)aString
[aMenuItem setTitleWithMnemonic:NSLocalizedString(@"Re&ceive")];
See Also: - mnemonic, - setMnemonicLocation:
- (int)state
NSOffState
(the default), NSOnState
,
or NSMixedState
.See Also: - setState:
- (NSMenu *)submenu
See Also: - hasSubmenu, - setSubmenu:
- (int)tag
See Also: - representedObject, - setTag:
- (id)target
See Also: - action, - setTarget:
- (NSString *)title
See Also: - setTitle:
- (NSString *)userKeyEquivalent
See Also: - keyEquivalent