Developer Documentation Table of Contents

NSMenuItem


Adopted by: NSMenuItem
Conforms to:
NSObject
NSCopying
NSCoding
Declared in:
AppKit/NSMenuItem.h



Protocol Description


WARNING

The NSMenuItem protocol is being removed from the Application Kit. 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").

Refer to the NSMenuItem class description, which replaces this.



Method Types


Creating a menu item
- 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
- isSeparatorItem
- separatorItem
Setting the owning menu
- setMenu:
- menu
Managing key equivalents
+ setUsesUserKeyEquivalents:
+ usesUserKeyEquivalents
- setKeyEquivalent:
- keyEquivalent
- setKeyEquivalentModifierMask:
- keyEquivalentModifierMask
Managing mnemonics
- setMnemonicLocation:
- mnemonicLocation
- setTitleWithMnemonic:
- mnemonic
Managing user key equivalents
- userKeyEquivalent
Representing an object
- setRepresentedObject:
- representedObject


Class Methods



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: - setSubmenuForItemsetSubmenu: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 NSMenuItem.

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).

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)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. By default, there is no off state image.

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. By default, the on state image is a checkmark.

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 switch back and forth between the different views that are displayed by selecting the various menu items.

See Also: - tag, - setRepresentedObject:



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.

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, its 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

Sets 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 *)aKeyEquivalent

Sets the receiver's unmodified key equivalent to aKeyEquivalent. If you want to remove the key equivalent from a menu item, pass an empty string ("") for aKeyEquivalent (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:

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



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 overridden 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)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:

- (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:, - setOffStateImage:, - setState:



setOnStateImage:

- (void)setOnStateImage:(NSImage *)itemImage

Sets the image of the receiver that indicates an "on" state. If itemImage is nil, any current on-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 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. 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. 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



userKeyEquivalentModifierMask

- (unsigned int)userKeyEquivalentModifierMask

Description forthcoming.


Table of Contents