Adopted By:
NSMenuItem
Conforms To:
NSCoding,
NSCopying
NSObject (NSObject)
Declared In:
AppKit/NSMenuItem.h
Protocol Description
The NSMenuItem protocol declares methods that are used to manipulate command items in menus. The NSMenuItem class adopts this protocol, implementing all methods the protocol declares, and provides the basic functionality of command items. With some implementations of the OpenStep specification (including OPENSTEP), you cannot replace the NSMenuItem class with a different class which conforms to the NSMenuItem protocol. You may, however, subclass the NSMenuItem class if necessary.
The methods declared by the NSMenuItem protocol 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. As implemented for the NSMenuItem class, a menu item, whenever one of its attributes changes, notifies the associated NSMenu via the itemChanged:
method. The protocol also allows a conforming object to set keyboard equivalents and (for Microsoft Windows) mnemonics for menu items. 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.
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 methods in the NSMenuItem protocol can override assigned keyboard equivalents with those the user has specified in the defaults system. The setUsesUserKeyEquivalents:
protocol 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:
.
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];
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:
setUsesUserKeyEquivalents:
(BOOL)flag
If flag is YES, 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
Returns YES if menu items conform to user preferences for key equivalents; otherwise, returns NO.
See also:
+ setUsesUserKeyEquivalents:, - userKeyEquivalent
action
Returns the receiver's action method.
See also:
- target, - setAction:
hasSubmenu
Returns YES if the receiver has a submenu, NO if it doesn't.
See also:
- setSubmenu:forItem:
(NSMenu)
image
Returns the image displayed by the receiver, or nil
if it displays no image.
See also:
- setImage:
initWithTitle:
(NSString *)itemName action:
(SEL)anAction keyEquivalent:
(NSString *)charCode
Returns an initialized instance of an object that conforms to the NSMenuItem protocol. The arguments itemName and charCode must not be nil
(if there is no title or key equivalent, specify an empty NSString). The anAction argument must be a valid selector or NULL For instances of the NSMenItem class, the default initial state is NSStateOff, the default on-state image is a checkmark, and the default mixed-state image is a dash.
isEnabled
Returns YES if the receiver is enabled, NO if not.
See also:
- setEnabled:
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
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:
-
(unsigned int)keyEquivalentModifierMask
Returns the receiver's keyboard equivalent modifier mask.
See also:
- setKeyEquivalentModifierMask:
menu
Returns the menu to which the receiver belongs, or nil
if no menu has been set.
See also:
- setMenu:
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:
- (NSString *)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
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 NSNotFound.
See also:
- setMnemonicLocation:
Returns the image used to depict the receiver's "off" state, or nil
if the image has not been set.
See also:
- setOffStateImage:
onStateImage
Returns the image used to depict the receiver's "on" state, or nil
if the image has not been set.
See also:
- setOnStateImage:
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 swtich back and forth between the different views that are displayed by selecting the various menu items.
See also:
- tag
, - setRepresentedObject:
setAction:
(SEL)aSelector
Sets the receiver's action method to aSelector.
See also:
- setTarget:
, - action
setEnabled:
(BOOL)flag
Sets whether the receiver is enabled based on flag. If a menu item is disabled, it's keyboard equivalent and mnemonic are also disabled. See the NSMenuValidation informal protocol specification for cautions regarding this method.
See also:
- isEnabled
setImage:
(NSImage *)menuImage
Set's the receiver's image to menuImage. If menuImage is nil
, the current image (if any) is removed. This image is not affected by changes in menu-item state.
See also:
- image
setKeyEquivalent:
(NSString *)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 nil
). Use setKeyEquivalentModifierMask:
to set the appropriate mask for the modifier keys for the key equivalent.
See also:
- setMnemonicLocation:, - keyEquivalent
setKeyEquivalentModifierMask:
(unsigned 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:
NSShiftKeyMask
NSAlternateKeyMask
NSCommandKeyMask
On Mach, you should always set NSCommandKeyMask in mask; on Microsoft Windows, this is not required.
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
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 overriden to provide specialized behavior.
See also:
- menu
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 nil
, any current mixed-state image is removed.
See also:
- mixedStateImage
, - setOffStateImage:
, - setOnStateImage:
, - setState:
setMnemonicLocation:
(unsigned 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 on Windows by which users can access the menu item.
See also:
- mnemonicLocation
setOffStateImage:
(NSImage *)itemImage
Sets the image of the receiver that indicates an "off" state. If itemImage is nil
, any current off-state image is removed.
See also:
- offStateImage
, - setMixedStateImage:
, - setOnStateImage:
, - setState:
setOnStateImage:
(NSImage *)itemImage
Sets the image of the receiver that indicates an "on" state. If itemImage is nil
, any current off-state image is removed.
See also:
- onStateImage
, - setMixedStateImage:
, - setOffStateImage:
, - setState:
setRepresentedObject:
(id)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:
(int)itemState
Sets the state of the receiver to itemState, which should be one of 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:
setSubmenu:
(NSMenu *)aSubmenu
Sets the submenu of the receiver to aSubmenu. The default implementation of the NSMenuItem class raises an exception if aSubmenu already has a supermenu.
See also:
- submenu
, - hasSubmenu
setTag:
(int)anInt
Sets the receiver's tag to anInt.
See also:
- setRepresentedObject:
, - tag
setTarget:
(id)anObject
Sets the receiver's target to anObject.
See also:
- setAction:, - target
setTitle:
(NSString *)aString
Sets the receiver's title to aString.
See also:
- title
setTitleWithMnemonic:
(NSString *)aString
Sets the title of a menu item with a character underlined to denote an access key (Windows only). Use an ampersand character to mark the character (the one following the ampersand) to be underlined. For example, the following message causes the `c' in `Receive' to be underlined:
[aMenuItem setTitleWithMnemonic:NSLocalizedString(@"Re&ceive")];
See also:
- mnemonic
, - setMnemonicLocation:
state
Returns the state of the receiver, which is NSOffState (the default), NSOnState, or NSMixedState.
See also:
- setState:
submenu
Returns the submenu associated with the receiving menu item, or nil
if no submenu is associated with it. In the implementation of the NSMenuItem class, if the receiver responds YES to hasSubmenu
, the submenu is returned.
See also:
- hasSubmenu
, - setSubmenu:
tag
Returns the receiver's tag.
See also:
- representedObject
, - setTag:
target
Returns the receiver's target.
See also:
- action, - setTarget:
title
Returns the receiver's title.
See also:
- setTitle:
userKeyEquivalent
Returns the user-assigned key equivalent for the receiver.
See also:
- keyEquivalent