[TOC] [Prev] [Next] [Bottom]

NSMenuItem

Adopted By:
NSMenuItem

Conforms To:
NSCoding,
NSCopying
NSObject (NSObject)

Declared In:
AppKit/NSMenuItem.h


Warning: The NSMenuItem protocol will be removed from the Application Kit in the Premier release of Rhapsody. The NSMenuItem class will solely assume all associated functionality. This change does not affect binary compatibility between different versions of projects, but might cause failures in project builds. To adapt your projects to this change, alter all references to the protocol (for example, "id <NSMenuItem>") to references to the class ("NSMenuItem").

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.

Keyboard Equivalents

An object conforming to the NSMenuItem protocol can be assigned a keyboard eqivalent, so that when the user types a character the menu item's action is sent. The keyboard eqivalent 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 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:.

Mnemonics

On certain platforms, currently including Microsoft Windows, an object conforming to the NSMenuItem protocol can also be assigned a mnemonic. Mnemonics can be assigned on other platforms as well, 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. On Microsoft Windows a user activates the menu by pressing the Alternate key. 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 methods of the NSMenuItem protocol, 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];


Method Types

Creating conforming 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

Class Methods

separatorItem

+ (id <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:


setUsesUserKeyEquivalents:

+ (void)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

+ (BOOL)usesUserKeyEquivalents

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

See also: + setUsesUserKeyEquivalents:, - userKeyEquivalent


Instance Methods

action

- (SEL)action

Returns the receiver's action method.

See also: - target, - setAction:


hasSubmenu

- (BOOL)hasSubmenu

Returns YES if the receiver has a submenu, NO if it doesn't.

See also: - setSubmenu:forItem:(NSMenu)


image

- (NSImage *)image

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

See also: - setImage:


initWithTitle:action:keyEquivalent:

- (id)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

- (BOOL)isEnabled

Returns YES if the receiver is enabled, NO if not.

See also: - setEnabled:


isSeparatorItem

- (BOOL)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

- (NSString *)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

- (unsigned int)keyEquivalentModifierMask

Returns the receiver's keyboard equivalent modifier mask.

See also: - setKeyEquivalentModifierMask:


menu

- (NSMenu *)menu

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

See also: - setMenu:


mixedStateImage

- (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

- (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

- (unsigned 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 NSNotFound.

See also: - setMnemonicLocation:


offStateImage

- (NSImage *)offStateImage

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

See also: - setOffStateImage:


onStateImage

- (NSImage *)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

- (id)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:

- (void)setAction:(SEL)aSelector

Sets the receiver's action method to aSelector.

See also: - setTarget:, - action


setEnabled:

- (void)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:

- (void)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:

- (void)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:

- (void)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:

- (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 overriden to provide specialized behavior.

See also: - menu


setMixedStateImage:

- (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 nil, any current mixed-state image is removed.

See also: - mixedStateImage, - setOffStateImage:, - setOnStateImage:, - setState:


setMnemonicLocation:

- (void)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:

- (void)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:

- (void)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:

- (void)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:

- (void)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:

- (void)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:

- (void)setTag:(int)anInt

Sets the receiver's tag to anInt.

See also: - setRepresentedObject:, - tag


setTarget:

- (void)setTarget:(id)anObject

Sets the receiver's target to anObject.

See also: - setAction:, - target


setTitle:

- (void)setTitle:(NSString *)aString

Sets the receiver's title to aString.

See also: - title


setTitleWithMnemonic:

- (void)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

- (int)state

Returns the state of the receiver, which is NSOffState (the default), NSOnState, or NSMixedState.

See also: - setState:


submenu

- (NSMenu *)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

- (int)tag

Returns the receiver's tag.

See also: - representedObject, - setTag:


target

- (id)target

Returns the receiver's target.

See also: - action, - setTarget:


title

- (NSString *)title

Returns the receiver's title.

See also: - setTitle:


userKeyEquivalent

- (NSString *)userKeyEquivalent

Returns the user-assigned key equivalent for the receiver.

See also: - keyEquivalent



[TOC] [Prev] [Next] [Bottom]

Copyright © 1997, Apple Computer, Inc. All rights reserved.