Important: The information in this document is obsolete and should not be used for new development.
| Adopted by |
NSMenuItem |
| Conforms to | |
| Framework | /System/Library/Frameworks/AppKit.framework |
| Availability | Available in Mac OS X v10.0 through Mac OS X v10.4. |
| Companion guide | Application Menu and Pop-up List Programming Topics for Cocoa |
| Declared in | NSMenuItem.h |
Refer to the NSMenuItem class description, which replaces this protocol.
Warning:
The NSMenuItem protocol is being removed from the Application Kit; you must use the NSMenuItem class instead. 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 *).
– initWithTitle:action:keyEquivalent: required method
– setEnabled: required method
– isEnabled required method
– setTarget: required method
– target required method
– setAction: required method
– action required method
– setTitle: required method
– title required method
– setAttributedTitle: required method
– attributedTitle required method
– setState: required method
– state required method
– setImage: required method
– image required method
– setOnStateImage: required method
– onStateImage required method
– setOffStateImage: required method
– offStateImage required method
– setMixedStateImage: required method
– mixedStateImage required method
– setSubmenu: required method
– submenu required method
– hasSubmenu required method
+ separatorItem required method
– isSeparatorItem required method
– setMenu: required method
– menu required method
+ setUsesUserKeyEquivalents: required method
+ usesUserKeyEquivalents required method
– setKeyEquivalent: required method
– keyEquivalent required method
– setKeyEquivalentModifierMask: required method
– keyEquivalentModifierMask required method
– setMnemonicLocation: required method
– mnemonicLocation required method
– setTitleWithMnemonic: required method
– mnemonic required method
– userKeyEquivalent required method
– userKeyEquivalentModifierMask required method
– setAlternate: required method
– isAlternate required method
– setIndentationLevel: required method
– indentationLevel required method
– setToolTip: required method
– toolTip required method
– setRepresentedObject: required method
– representedObject required method
Returns a menu item that is used to separate logical groups of menu commands. (required)
+ (id <NSMenuItem>)separatorItem
This menu item is disabled. The default separator item is blank space.
Sets whether menu items conform to user preferences for key equivalents. (required)
+ (void)setUsesUserKeyEquivalents:(BOOL)flag
If YES, menu items conform to user preferences for key equivalents; if NO, the key equivalents originally assigned to the menu items are used.
Returns YES if menu items conform to user preferences for key equivalents; otherwise, returns NO. (required)
+ (BOOL)usesUserKeyEquivalents
Returns the receiver’s action method. (required)
- (SEL)action
NSMenuItem.hReturns the custom title string for a menu item. (required)
- (NSAttributedString *)attributedTitle
NSMenuItem.hReturns YES if the receiver has a submenu, NO if it doesn’t. (required)
- (BOOL)hasSubmenu
– setSubmenu:forItem: (NSMenu)NSMenuItem.hReturns the image displayed by the receiver, or nil if it displays no image. (required)
- (NSImage *)image
NSMenuItem.hReturns the menu item indentation level for the receiver. (required)
- (NSInteger)indentationLevel
The return value will be from 0 to 15. The default indentation level is 0.
NSMenuItem.hReturns an initialized instance of an NSMenuItem. (required)
- (id)initWithTitle:(NSString *)itemName action:(SEL)anAction keyEquivalent:(NSString *)charCode
The title of the menu item. It must not be nil (if there is no title, specify an empty NSString).
The action selector to be associated with the menu item. It must be a valid selector or NULL.
A string representing a keyboard key to be used as the key equivalent. It must not be nil (if there is no key equivalent, specify an empty NSString).
Returns an instance of NSMenuItem or nil if the object couldn't be created.
NSMenuItem.hReturns whether the receiver is an alternate to the previous menu item. (required)
- (BOOL)isAlternate
NSMenuItem.hReturns YES if the receiver is enabled, NO if not. (required)
- (BOOL)isEnabled
NSMenuItem.hReturns whether the receiver is a separator item (that is, a menu item used to visually segregate related menu items). (required)
- (BOOL)isSeparatorItem
NSMenuItem.hReturns the receiver’s unmodified keyboard equivalent, or the empty string if one hasn’t been defined. (required)
- (NSString *)keyEquivalent
Use keyEquivalentModifierMask to determine the modifier mask for the key equivalent.
NSMenuItem.hReturns the receiver’s keyboard equivalent modifier mask. (required)
- (NSUInteger)keyEquivalentModifierMask
NSMenuItem.hReturns the menu to which the receiver belongs, or nil if no menu has been set. (required)
- (NSMenu *)menu
NSMenuItem.hReturns the image used to depict a “mixed state.” (required)
- (NSImage *)mixedStateImage
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 (nonbolded) words.
NSMenuItem.hReturns the character in the menu item title that appears underlined for use as a mnemonic. (required)
- (NSString *)mnemonic
If there is no mnemonic character, returns an empty string. Mnemonics are not supported in Mac OS X.
NSMenuItem.hReturns the position of the underlined character in the menu item title used as a mnemonic. (required)
- (NSUInteger)mnemonicLocation
The position is the zero-based index of that character in the title string. If the receiver has no mnemonic character, returns NSNotFound. Mnemonics are not supported in Mac OS X.
NSMenuItem.hReturns the image used to depict the receiver’s “off” state, or nil if the image has not been set. (required)
- (NSImage *)offStateImage
By default, there is no off state image.
NSMenuItem.hReturns the image used to depict the receiver’s “on” state, or nil if the image has not been set. (required)
- (NSImage *)onStateImage
By default, the on state image is a checkmark.
NSMenuItem.hReturns the object that the receiving menu item represents. (required)
- (id)representedObject
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.
NSMenuItem.hSets the receiver’s action method. (required)
- (void)setAction:(SEL)aSelector
A selector identifying the action method.
See Action Messages for additional information on action messages.
NSMenuItem.hMarks the receiver as an alternate to the previous menu item. (required)
- (void)setAlternate:(BOOL)isAlternate
YES if the receiver is an alternate to the previous menu item, NO otherwise.
If the receiver has the same key equivalent as the previous item, but has different key equivalent modifiers, the items are folded into a single visible item and the appropriate item shows while tracking the menu. The menu items may also have no key equivalent as long as the key equivalent modifiers are different.
If there are two or more items with no key equivalent but different modifiers, then the only way to get access to the alternate items is with the mouse. If you mark items as alternates but their key equivalents don’t match, they might be displayed as separate items. Marking the first item as an alternate has no effect.
The isAlternate value is archived.
NSMenuItem.hSpecifies a custom string for a menu item. (required)
- (void)setAttributedTitle:(NSAttributedString *)string
An attributed string to use as the receiver's title.
You can use this method to add styled text and embedded images to menu item strings. If you do not set a text color for the attributed string, it is black when not selected, white when selected, and gray when disabled. Colored text remains unchanged when selected.
When you call this method to set the menu title to an attributed string, the setTitle: method is also called to set the menu title with a plain string. If you clear the attributed title, the plain title remains unchanged.
The attributed string is not archived in the old nib format.
NSMenuItem.hSets whether the receiver is enabled. (required)
- (void)setEnabled:(BOOL)flag
YES if the receiver is to be enabled, NO otherwise.
If a menu item is disabled, its keyboard equivalent is also disabled. See the NSMenuValidation informal protocol specification for cautions regarding this method.
NSMenuItem.hSets the receiver’s image. (required)
- (void)setImage:(NSImage *)menuImage
An NSImage object representing an image to be displayed in the menu item. If menuImage is nil, the current image (if any) is removed.
The menu item's image is not affected by changes in its state.
NSMenuItem.hSets the menu item indentation level for the receiver. (required)
- (void)setIndentationLevel:(NSInteger)indentationLevel
The value for indentationLevel may be from 0 to 15. If indentationLevel is greater than 15, the value is pinned to the maximum. If indentationLevel is less than 0, an exception is raised. The default indentation level is 0.
The indentationLevel value is archived.
NSMenuItem.hSets the receiver’s unmodified key equivalent. (required)
- (void)setKeyEquivalent:(NSString *)aKeyEquivalent
A string containing a character code representing a keyboard key. 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.
NSMenuItem.hSets the receiver’s keyboard equivalent modifiers (indicating modifiers such as the Shift or Option key) to those in mask. (required)
- (void)setKeyEquivalentModifierMask:(NSUInteger)mask
The key masks indicate modifiers such as the Shift or Option keys. mask is an integer bit field containing any of these modifier key masks, combined using the C bitwise OR operator:
NSShiftKeyMask
NSAlternateKeyMask
NSCommandKeyMask
NSControlKeyMask
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.
NSMenuItem.hSets the receiver’s menu. (required)
- (void)setMenu:(NSMenu *)aMenu
The menu object that "owns" the receiver.
This method is invoked by the owning NSMenu object 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.
NSMenuItem.hSets the image of the receiver that indicates a “mixed” state, that is, a state neither “on” nor “off.” (required)
- (void)setMixedStateImage:(NSImage *)itemImage
The NSImage object to use for the "mixed" state of the menu item. If itemImage is nil, any current mixed-state image is removed.
NSMenuItem.hSets the character of the specified menu item that is to be underlined. (required)
- (void)setMnemonicLocation:(NSUInteger)location
An integer index into the character array of the title.
This character identifies the access key by which users can access the menu item. Mnemonics are not supported in Mac OS X.
NSMenuItem.hSets the image of the receiver that indicates an “off” state. (required)
- (void)setOffStateImage:(NSImage *)itemImage
The NSImage object to use for the "off" state of the menu item. If itemImage is nil, any current off-state image is removed.
NSMenuItem.hSets the image of the receiver that indicates an “on” state. (required)
- (void)setOnStateImage:(NSImage *)itemImage
The NSImage object to use for the "on" state of the menu item. If itemImage is nil, any current on-state image is removed.
NSMenuItem.hSets the object represented by the receiver. (required)
- (void)setRepresentedObject:(id)anObject
The object to be represented by the receiver.
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 arbitrary integer, 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.
NSMenuItem.hSets the state of the receiver. (required)
- (void)setState:(NSInteger)itemState
An integer constant representing a state; it should be one of NSOffState, NSOnState, or NSMixedState.
The image associated with the new state is displayed to the left of the menu item.
NSMenuItem.hSets the submenu of the receive. (required)
- (void)setSubmenu:(NSMenu *)aSubmenu
The menu object to set as submenu.
The default implementation raises an exception if aSubmenu already has a supermenu.
NSMenuItem.hSets the receiver’s tag. (required)
- (void)setTag:(NSInteger)anInt
An integer tag to associate with the receiver.
NSMenuItem.hSets the receiver’s target. (required)
- (void)setTarget:(id)anObject
An object to be the target of action messages sent by the receiver.
NSMenuItem.hSets the receiver’s title. (required)
- (void)setTitle:(NSString *)aString
The new title of the menu item. If you do not want a title, use an empty string, not nil.
NSMenuItem.hSets the title of a menu item with a character underlined to denote an access key. (required)
- (void)setTitleWithMnemonic:(NSString *)aString
Mnemonics are not supported in Mac OS X.
NSMenuItem.hSets a help tag for a menu item. (required)
- (void)setToolTip:(NSString *)toolTip
A short string that describes the menu item.
You can invoke this method for any menu item, including items in the main menu bar. This string is not archived in the old nib format.
NSMenuItem.hReturns the state of the receiver. (required)
- (NSInteger)state
A menu-item state can be one of NSOffState (the default), NSOnState, or NSMixedState.
NSMenuItem.hReturns the submenu associated with the receiving menu item, or nil if no submenu is associated with it. (required)
- (NSMenu *)submenu
If the receiver responds YES to hasSubmenu, the submenu is returned.
NSMenuItem.hReturns the receiver’s tag. (required)
- (NSInteger)tag
NSMenuItem.hReturns the receiver’s target. (required)
- (id)target
NSMenuItem.hReturns the receiver’s title. (required)
- (NSString *)title
NSMenuItem.hReturns the help tag for a menu item. (required)
- (NSString *)toolTip
NSMenuItem.hReturns the user-assigned key equivalent for the receiver. (required)
- (NSString *)userKeyEquivalent
NSMenuItem.hReturns the modifier mask for the receiver’s user-assigned key equivalent. (required)
- (NSUInteger)userKeyEquivalentModifierMask
NSMenuItem.hLast updated: 2007-02-08
