Mac Developer Library

Developer

AppKit Framework Reference NSMenuItem Class Reference

Options
Deployment Target:

On This Page
Language:

NSMenuItem

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 fact, you cannot replace the NSMenuItem class with a different class. You may, however, subclass NSMenuItem if necessary.

Prior to OS X v10.5, NSMenuItem conformed to the following protocols: NSCopying (see NSCopying Protocol Reference), NSCoding (see NSCoding Protocol Reference), and NSValidatedUserInterfaceItem (see NSValidatedUserInterfaceItem Protocol Reference).

  • Returns an initialized instance of an NSMenuItem.

    Declaration

    Swift

    init(title aString: String, action aSelector: Selector, keyEquivalent charCode: String)

    Objective-C

    - (instancetype)initWithTitle:(NSString *)itemName action:(SEL)anAction keyEquivalent:(NSString *)charCode

    Parameters

    itemName

    The title of the menu item. This value must not be nil (if there is no title, specify an empty NSString).

    anAction

    The action selector to be associated with the menu item. This value must be a valid selector or NULL.

    charCode

    A string representing a keyboard key to be used as the key equivalent. This value must not be nil (if there is no key equivalent, specify an empty NSString).

    Return Value

    An instance of NSMenuItem, or nil if the object couldn't be created.

    Discussion

    For instances of the NSMenuItem class, the default initial state is NSOffState, the default on-state image is a check mark, and the default mixed-state image is a dash.

    Availability

    Available in OS X v10.0 and later.

  • A boolean that shows whether the receiver is enabled.

    Declaration

    Swift

    var enabled: Bool

    Objective-C

    @property(getter=isEnabled) BOOL enabled

    Discussion

    This property has no effect unless the menu in which the item will be added or is already a part of has been sent setAutoenablesItems:NO. If a menu item is disabled, its keyboard equivalent is also disabled. See the NSMenuValidation informal protocol specification for cautions regarding this method.

    Availability

    Available in OS X v10.0 and later.

  • A boolean that indicates whether the receiver is hidden.

    Declaration

    Swift

    var hidden: Bool

    Objective-C

    @property(getter=isHidden) BOOL hidden

    Discussion

    Hidden menu items (or items with a hidden superitem) do not appear in a menu and do not participate in command key matching.

    Availability

    Available in OS X v10.5 and later.

  • A Boolean value that indicates whether the receiver or any of its superitems is hidden. (read-only)

    Declaration

    Swift

    var hiddenOrHasHiddenAncestor: Bool { get }

    Objective-C

    @property(getter=isHiddenOrHasHiddenAncestor, readonly) BOOL hiddenOrHasHiddenAncestor

    Availability

    Available in OS X v10.5 and later.

    See Also

    hidden

  • The receiver’s target.

    Declaration

    Swift

    weak var target: AnyObject?

    Objective-C

    @property(weak) id target

    Availability

    Available in OS X v10.0 and later.

    See Also

    action

  • The receiver’s action-method selector.

    Declaration

    Swift

    var action: Selector

    Objective-C

    @property SEL action

    Availability

    Available in OS X v10.0 and later.

    See Also

    target

  • The receiver’s image.

    Declaration

    Swift

    var image: NSImage?

    Objective-C

    @property(strong) NSImage *image

    Discussion

    The menu item's image is not affected by changes in its state.

    Availability

    Available in OS X v10.0 and later.

  • The image of the receiver that indicates an “on” state.

    Declaration

    Swift

    var onStateImage: NSImage!

    Objective-C

    @property(strong) NSImage *onStateImage

    Availability

    Available in OS X v10.0 and later.

  • The image of the receiver that indicates an “off” state.

    Declaration

    Swift

    var offStateImage: NSImage!

    Objective-C

    @property(strong) NSImage *offStateImage

    Discussion

    By default there is no off-state image.

    Availability

    Available in OS X v10.0 and later.

  • The image of the receiver that indicates a “mixed” state, that is, a state neither “on” nor “off.”

    Declaration

    Swift

    var mixedStateImage: NSImage!

    Objective-C

    @property(strong) NSImage *mixedStateImage

    Discussion

    A mixed state is useful for indicating a mix of “off” and “on” attribute values in a group of selected objects, such as a selection of text containing boldface and plain (non-boldface) words. By default this is a horizontal line.

    Availability

    Available in OS X v10.0 and later.

  • The submenu of the receiver.

    Declaration

    Swift

    var submenu: NSMenu?

    Objective-C

    @property(strong) NSMenu *submenu

    Discussion

    The default implementation of the NSMenuItem class raises an exception if aSubmenu already has a supermenu.

    Availability

    Available in OS X v10.0 and later.

    See Also

    hasSubmenu

  • A Boolean value that indicates whether the receiver has a submenu. (read-only)

    Declaration

    Swift

    var hasSubmenu: Bool { get }

    Objective-C

    @property(readonly) BOOL hasSubmenu

    Availability

    Available in OS X v10.0 and later.

  • The menu item whose submenu contains the receiver. (read-only)

    Declaration

    Swift

    unowned(unsafe) var parentItem: NSMenuItem? { get }

    Objective-C

    @property(readonly, assign) NSMenuItem *parentItem

    Availability

    Available in OS X v10.6 and later.

  • A menu item that is used to separate logical groups of menu commands. (read-only)

    Declaration

    Swift

    var separatorItem: Bool { get }

    Objective-C

    @property(getter=isSeparatorItem, readonly) BOOL separatorItem

    Discussion

    This menu item is disabled. The default separator item is blank space.

    Availability

    Available in OS X v10.0 and later.

  • Returns a menu item that is used to separate logical groups of menu commands.

    Declaration

    Swift

    class func separatorItem() -> NSMenuItem

    Objective-C

    + (NSMenuItem *)separatorItem

    Return Value

    A menu item that is used to separate logical groups of menu commands.

    Discussion

    This menu item is disabled. The default separator item is blank space.

    Availability

    Available in OS X v10.0 and later.

    See Also

    enabled

  • menu menu Property

    The receiver’s menu.

    Declaration

    Swift

    unowned(unsafe) var menu: NSMenu?

    Objective-C

    @property(assign) NSMenu *menu

    Availability

    Available in OS X v10.0 and later.

  • The receiver’s unmodified key equivalent.

    Declaration

    Swift

    var keyEquivalent: String

    Objective-C

    @property(copy) NSString *keyEquivalent

    Discussion

    If you want to specify the Backspace key as the key equivalent for a menu item, use a single character string with NSBackspaceCharacter (defined in NSText.h as 0x08) and for the Forward Delete key, use NSDeleteCharacter (defined in NSText.h as 0x7F). Note that these are not the same characters you get from an NSEvent key-down event when pressing those keys.

    Availability

    Available in OS X v10.0 and later.

  • The receiver’s keyboard equivalent modifiers.

    Declaration

    Swift

    var keyEquivalentModifierMask: Int

    Objective-C

    @property NSUInteger keyEquivalentModifierMask

    Discussion

    NSShiftKeyMask is a valid modifier for any key equivalent in mask. This allows you to specify key-equivalents such as Command-Shift-1 that are consistent across all keyboards. However, with a few exceptions (such as the German “ß” character), a lowercase character with NSShiftKeyMask is interpreted the same as the uppercase character without that mask. For example, Command-Shift-c and Command-C are considered to be identical key equivalents.

    See the NSEvent class specification for more information about modifier mask values.

    Availability

    Available in OS X v10.0 and later.

  • Deprecated. Sets the character of the menu item title at location that is to be underlined.

    Declaration

    Objective-C

    - (void)setMnemonicLocation:(NSUInteger)location

    Parameters

    location

    An integer index into the character array of the title. location must be from 0 to 254.

    Discussion

    This character identifies the access key by which users can access the menu item.

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Deprecated. Returns the position of the underlined character in the menu item title used as a mnemonic.

    Declaration

    Objective-C

    - (NSUInteger)mnemonicLocation

    Discussion

    The position is the zero-based index of that character in the title string. If the receiver has no mnemonic character, returns NSNotFound.

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Deprecated. Sets the title of a menu item with a character denoting an access key.

    Declaration

    Swift

    func setTitleWithMnemonic(_ stringWithAmpersand: String)

    Objective-C

    - (void)setTitleWithMnemonic:(NSString *)stringWithAmpersand

    Discussion

    Use an ampersand character to mark the character (the one following the ampersand) to be designated.

    Availability

    Available in OS X v10.0 and later.

  • - mnemonic (OS X v10.6)

    Deprecated. Returns the character in the menu item title that appears underlined for use as a mnemonic.

    Declaration

    Objective-C

    - (NSString *)mnemonic

    Discussion

    If there is no mnemonic character, returns an empty string.

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • A boolean value that marks the receiver as an alternate to the previous menu item.

    Declaration

    Swift

    var alternate: Bool

    Objective-C

    @property(getter=isAlternate) BOOL alternate

    Availability

    Available in OS X v10.3 and later.

  • The menu item indentation level for the receiver.

    Declaration

    Swift

    var indentationLevel: Int

    Objective-C

    @property NSInteger indentationLevel

    Discussion

    The indentationLevel value is archived.

    Value is from 0 to 15. The default indentation level is 0.

    Availability

    Available in OS X v10.3 and later.

  • A help tag for a menu item.

    Declaration

    Swift

    var toolTip: String?

    Objective-C

    @property(copy) NSString *toolTip

    Availability

    Available in OS X v10.3 and later.

  • The object represented by the receiver.

    Declaration

    Swift

    var representedObject: AnyObject?

    Objective-C

    @property(strong) id representedObject

    Discussion

    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.

    Availability

    Available in OS X v10.0 and later.

    See Also

    tag

  • view view Property

    The content view for the receiver.

    Declaration

    Swift

    var view: NSView?

    Objective-C

    @property(strong) NSView *view

    Discussion

    A menu item with a view does not draw its title, state, font, or other standard drawing attributes, and assigns drawing responsibility entirely to the view. Keyboard equivalents and type-select continue to use the key equivalent and title as normal. For more details, see Application Menu and Pop-up List Programming Topics

    By default, a menu item has a nil view.

    Availability

    Available in OS X v10.5 and later.

  • A Boolean value that indicates whether the receiver should be drawn highlighted. (read-only)

    Declaration

    Swift

    var highlighted: Bool { get }

    Objective-C

    @property(getter=isHighlighted, readonly) BOOL highlighted

    Availability

    Available in OS X v10.5 and later.