Mac Developer Library

Developer

AppKit Framework Reference NSMenu Class Reference

Options
Deployment Target:

On This Page
Language:

NSMenu

An NSMenu object manages an application’s menus.

  • Returns a Boolean value that indicates whether the menu bar is visible.

    Declaration

    Swift

    class func menuBarVisible() -> Bool

    Objective-C

    + (BOOL)menuBarVisible

    Return Value

    YEStrue if the menu bar is visible and selectable, otherwise NOfalse.

    Availability

    Available in OS X v10.2 and later.

  • Sets whether the menu bar is visible and selectable by the user.

    Declaration

    Swift

    class func setMenuBarVisible(_ visible: Bool)

    Objective-C

    + (void)setMenuBarVisible:(BOOL)visible

    Parameters

    visible

    YEStrue if the menu bar should be visible and selectable, otherwise NOfalse.

    Availability

    Available in OS X v10.2 and later.

  • The menu bar height for the main menu in pixels. (read-only)

    Declaration

    Swift

    var menuBarHeight: CGFloat { get }

    Objective-C

    @property(readonly) CGFloat menuBarHeight

    Discussion

    For the main menu, the value of this property is a value of type GCFloat, indicating the height of the menu bar in pixels. For any other menu, the value of this property is 0.

    This property supersedes the menuBarHeight class method of the NSMenuView class.

    Availability

    Available in OS X v10.4 and later.

  • Initializes and returns a menu having the specified title and with autoenabling of menu items turned on.

    Declaration

    Swift

    init(title aTitle: String)

    Objective-C

    - (instancetype)initWithTitle:(NSString *)aTitle

    Parameters

    aTitle

    The title to assign to the menu.

    Return Value

    The initialized NSMenu object or nil if the object could not be initialized.

    Special Considerations

    This method is the designated initializer for the class.

    Availability

    Available in OS X v10.0 and later.

    See Also

    autoenablesItems

  • Assigns a menu to be a submenu of the menu controlled by a given menu item.

    Declaration

    Swift

    func setSubmenu(_ aMenu: NSMenu?, forItem anItem: NSMenuItem)

    Objective-C

    - (void)setSubmenu:(NSMenu *)aMenu forItem:(NSMenuItem *)anItem

    Parameters

    aMenu

    A menu object that is to be a submenu of the menu.

    anItem

    A menu item (that is, an object conforming to the NSMenuItem protocol) that controls aMenu. The method sets the action of anItem to submenuAction:.

    Availability

    Available in OS X v10.0 and later.

  • The action method assigned to menu items that open submenus.

    Declaration

    Swift

    func submenuAction(_ sender: AnyObject?)

    Objective-C

    - (void)submenuAction:(id)sender

    Discussion

    You may override this method to implement different behavior. Never invoke this method directly.

    Availability

    Available in OS X v10.0 and later.

  • - attachedMenu (OS X v10.2)

    Returns the menu currently attached to the menu.

    Declaration

    Objective-C

    - (NSMenu *)attachedMenu

    Return Value

    The menu currently attached to the menu or nil if there’s no such object.

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.2.

    See Also

    – isAttached

  • - isAttached (OS X v10.2)

    Returns a Boolean value that indicates whether the menu is currently attached to another menu.

    Declaration

    Objective-C

    - (BOOL)isAttached

    Return Value

    YEStrue if the menu is currently attached to another menu, otherwise NOfalse.

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.2.

  • Returns the location in screen coordinates where the given submenu is displayed when opened as a submenu of the menu.

    Declaration

    Objective-C

    - (NSPoint)locationForSubmenu:(NSMenu *)aSubmenu

    Parameters

    aSubmenu

    A menu object that is a submenu of the menu.

    Return Value

    An NSPoint structure describing the location or (0.0, 0.0) if the submenu does not exist in the menu.

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.2.

  • The parent menu that contains the menu as a submenu.

    Declaration

    Swift

    unowned(unsafe) var supermenu: NSMenu?

    Objective-C

    @property(assign) NSMenu *supermenu

    Discussion

    This property contains a value of type NSMenu representing the the parent menu that contains the menu as a submenu. If the menu has no parent menu, then the value of this property is nil.

    You should never invoke the setter method for this property directly. The setter method is called automatically when changes to the parent menu occur. You can, however, override the setter method for this property in order to take action when changes to the parent menu occur.

    Availability

    Available in OS X v10.0 and later.

  • isTornOff tornOff (OS X v10.11) Property

    Indicates whether the menu is offscreen or attached to another menu (or if it’s the main menu). (read-only)

    Declaration

    Swift

    var tornOff: Bool { get }

    Objective-C

    @property(getter=isTornOff, readonly) BOOL tornOff

    Discussion

    This property has a value of NOfalse if the menu is offscreen, is attached to another menu, or is the main menu. Otherwise, this property has a value of YEStrue.

    Special Considerations

    This property has no effect in OS X v10.6 and later.

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.11.

  • Indicates whether the menu automatically enables and disables its menu items.

    Declaration

    Swift

    var autoenablesItems: Bool

    Objective-C

    @property BOOL autoenablesItems

    Discussion

    This property contains a Boolean value, indicating whether the menu automatically enables and disables its menu items. If set to YEStrue, menu items of the menu are automatically enabled and disabled according to rules computed by the NSMenuValidation informal protocol. By default, NSMenu objects autoenable their menu items.

    Availability

    Available in OS X v10.0 and later.

    See Also

    NSMenuValidation

  • Enables or disables the menu items of the menu based on the NSMenuValidation informal protocol and sizes the menu to fit its current menu items if necessary.

    Declaration

    Swift

    func update()

    Objective-C

    - (void)update

    Discussion

    For more information, see NSMenuValidation Protocol Reference.

    Availability

    Available in OS X v10.0 and later.

  • font font Property

    The font of the menu and its submenus.

    Declaration

    Swift

    var font: NSFont!

    Objective-C

    @property(strong) NSFont *font

    Discussion

    This property contains a font object of the menu and its submenus that don’t specify fonts of their own.

    Availability

    Available in OS X v10.6 and later.

  • Causes the application to send the action message of a specified menu item to its target.

    Declaration

    Swift

    func performActionForItemAtIndex(_ index: Int)

    Objective-C

    - (void)performActionForItemAtIndex:(NSInteger)index

    Parameters

    index

    The integer index of a menu item.

    Discussion

    If a target is not specified, the message is sent to the first responder. As a side effect, this method posts NSMenuWillSendActionNotification and NSMenuDidSendActionNotification.

    In OS X v10.6 and later the performActionForItemAtIndex: no longer triggers menu validation. This is because validation is typically done during menu tracking or key equivalent matching, so the subsequent performActionForItemAtIndex: validation was redundant. To trigger validation explicitly, use invoke the update method.

    In OS X v10.6 performActionForItemAtIndex:, when called, now triggers highlighting in the menu bar. It also sends out appropriate accessibility notifications indicating the item was selected.

    Availability

    Available in OS X v10.0 and later.

  • The title of the menu.

    Declaration

    Swift

    var title: String

    Objective-C

    @property(copy) NSString *title

    Discussion

    This property contains a string value indicating the title of the menu. If the menu is a submenu of the application’s main menu, then the title of the menu appears in the menu bar.

    Availability

    Available in OS X v10.0 and later.

  • The minimum width of the menu in screen coordinates.

    Declaration

    Swift

    var minimumWidth: CGFloat

    Objective-C

    @property CGFloat minimumWidth

    Discussion

    This property contains a value of type CGFloat, indicating the minimum width of the menu in screen coordinates.

    The menu will not draw smaller than its minimum width, but may draw larger if it needs more space. The default value for this property is 0.

    Availability

    Available in OS X v10.6 and later.

  • size size Property

    The size of the menu in screen coordinates (read-only)

    Declaration

    Swift

    var size: NSSize { get }

    Objective-C

    @property(readonly) NSSize size

    Discussion

    This property contains a value of type NSSize, indicating the size of the menu in screen coordinates.

    The menu may draw at a smaller size when shown, depending on its positioning and display configuration.

    Availability

    Available in OS X v10.6 and later.

  • - sizeToFit (OS X v10.2)

    Resizes the menu to exactly fit its items.

    Declaration

    Objective-C

    - (void)sizeToFit

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.2.

  • The available properties for the menu. (read-only)

    Declaration

    Swift

    var propertiesToUpdate: NSMenuProperties { get }

    Objective-C

    @property(readonly) NSMenuProperties propertiesToUpdate

    Discussion

    This property contains a bitwise-C OR set of NSMenuProperties values that are applicable to the menu.

    This property may be queried from specific callbacks to determine which menu properties are defined, and whether or not they are relevant to changes you need to make to the menu. This property is intended to allow for more efficient updating of the menu in certain circumstances.

    For example, if the NSMenuPropertyItemImage property isn’t set, your delegate doesn’t need to spend time updating the images of the menu items, because the images aren’t needed (for example, during key-equivalent matching).

    You have to update a menu property only if it has changed since you last set it, even if the corresponding bit is 1. For example, if the title of a menu item never changes, you have to set it only once.

    Accessing this property is optional; it is always acceptable to fully update all properties of the menu.

    Availability

    Available in OS X v10.6 and later.

  • Indicates whether messages are sent to the application’s windows each time the menu changes.

    Declaration

    Swift

    var menuChangedMessagesEnabled: Bool

    Objective-C

    @property BOOL menuChangedMessagesEnabled

    Discussion

    This property indicates whether messages are sent to the application’s windows each time the menu changes.

    To avoid the “flickering” effect of many successive menu changes, set the value of this property to NOfalse, make changes to the menu, and then set the value of this property to YEStrue. This approach has the effect of batching changes and applying them all at once.

    Special Considerations

    On OS X v10.6 and later this property has no effect.

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.11.

  • Indicates whether the pop-up menu allows appending of contextual menu plug-in items.

    Declaration

    Swift

    var allowsContextMenuPlugIns: Bool

    Objective-C

    @property BOOL allowsContextMenuPlugIns

    Discussion

    This property contains a Boolean value indicating whether the pop-up menu allows appending of contextual menu plug-in items.

    Contextual menu plug-ins are system-wide services provided by other applications. For example, a contextual menu plug-in might provide an “Open URL...” service. If you enable context menu plug-ins, your application’s contextual menu will display the appropriate items for the currently selected data type.

    The default value for this property is YEStrue.

    See Services Implementation Guide for more information on contextual menu plug-ins.

    Availability

    Available in OS X v10.6 and later.

  • Displays a contextual menu over a view for an event.

    Declaration

    Swift

    class func popUpContextMenu(_ menu: NSMenu, withEvent event: NSEvent, forView view: NSView)

    Objective-C

    + (void)popUpContextMenu:(NSMenu *)menu withEvent:(NSEvent *)event forView:(NSView *)view

    Parameters

    menu

    The menu object to use for the contextual menu.

    event

    An NSEvent object representing the event.

    view

    The view object over which to display the contextual menu.

    Availability

    Available in OS X v10.0 and later.

  • Displays a contextual menu over a view for an event using a specified font.

    Declaration

    Swift

    class func popUpContextMenu(_ menu: NSMenu, withEvent event: NSEvent, forView view: NSView, withFont font: NSFont?)

    Objective-C

    + (void)popUpContextMenu:(NSMenu *)menu withEvent:(NSEvent *)event forView:(NSView *)view withFont:(NSFont *)font

    Parameters

    menu

    The menu object to use for the contextual menu.

    event

    An NSEvent object representing the event.

    view

    The view object over which to display the contextual menu.

    font

    An NSFont object representing the font for the contextual menu. If you pass in nil for the font, the method uses the default font for menu.

    Discussion

    Specifying a font using the font parameter is discouraged. Instead, set the menu’s font using the font property, then pass nil for the font parameter.

    Availability

    Available in OS X v10.3 and later.

  • Overridden by subclasses to implement specialized context-sensitive help behavior.

    Declaration

    Swift

    func helpRequested(_ eventPtr: NSEvent)

    Objective-C

    - (void)helpRequested:(NSEvent *)event

    Parameters

    event

    An NSEvent object representing the event associated with the help request.

    Discussion

    Subclasses in their implementation of this method should cause the Help Manager (NSHelpManager) to display the help associated with the menu. Never invoke this method directly.

    Special Considerations

    On OS X v10.6 and later this method has no effect. This method may be deprecated in a future release.

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.11.

    See Also

    showContextHelpForObject:locationHint: (NSHelpManager)

  • Pops up the menu at the specified location.

    Declaration

    Swift

    func popUpMenuPositioningItem(_ item: NSMenuItem?, atLocation location: NSPoint, inView view: NSView?) -> Bool

    Objective-C

    - (BOOL)popUpMenuPositioningItem:(NSMenuItem *)item atLocation:(NSPoint)location inView:(NSView *)view

    Parameters

    item

    The menu item to be positioned at the specified location in the view.

    location

    The location in the view coordinate system to display the menu item.

    view

    The view to display the menu item over.

    Return Value

    YEStrue if menu tracking ended because an item was selected, and NOfalse if menu tracking was cancelled for any reason.

    Discussion

    Displays the menu as a pop-up menu. The top left corner of the specified item (if specified, item must be present in the menu) is positioned at the specified location in the specified view, interpreted in the view's own coordinate system.

    If item is nil, the menu is positioned such that the top left of the menu content frame is at the given location.

    If view is nil, the location is interpreted in the screen coordinate system. This allows you to pop up a menu disconnected from any window.

    Availability

    Available in OS X v10.6 and later.

  • Indicates whether the menu displays the state column.

    Declaration

    Swift

    var showsStateColumn: Bool

    Objective-C

    @property BOOL showsStateColumn

    Discussion

    This property contains a Boolean value indicating whether the menu displays the state column. The default value for this property is YEStrue.

    Availability

    Available in OS X v10.5 and later.

  • Returns the zone from which NSMenu objects should be allocated.

    Declaration

    Swift

    class func menuZone() -> NSZone

    Objective-C

    + (NSZone *)menuZone

    Return Value

    The zone from which NSMenu objects should be allocated.

    Special Considerations

    This is left in for compatibility and always returns NSDefaultMallocZone. It is not necessary to use this.

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.11.

  • + setMenuZone: (OS X v10.2)

    Sets the zone from which NSMenu objects should be allocated

    Declaration

    Objective-C

    + (void)setMenuZone:(NSZone *)zone

    Parameters

    zone

    The memory zone to set.

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.2.

  • Indicates the currently highlighted item in the menu. (read-only)

    Declaration

    Swift

    var highlightedItem: NSMenuItem? { get }

    Objective-C

    @property(readonly, strong) NSMenuItem *highlightedItem

    Discussion

    This property indicates the currently highlighted item in the menu. If no menu is highlighted, this property has a value of nil.

    Availability

    Available in OS X v10.5 and later.

  • The delegate of the menu.

    Declaration

    Swift

    unowned(unsafe) var delegate: NSMenuDelegate?

    Objective-C

    @property(assign) id< NSMenuDelegate > delegate

    Discussion

    This property indicates the delegate of the menu.

    You can use the delegate to populate a menu just before it is drawn and to check for key equivalents without creating a menu item.

    Availability

    Available in OS X v10.3 and later.

  • Deprecated.

    Deprecation Statement

    OS X does not use menu representations to draw menus.

    Declaration

    Objective-C

    - (id)contextMenuRepresentation

    Return Value

    nil.

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.2.

  • Deprecated.

    Deprecation Statement

    OS X does not use menu representations to draw menus.

    Declaration

    Objective-C

    - (void)setContextMenuRepresentation:(id)menuRep

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.2.

  • Deprecated.

    Deprecation Statement

    OS X does not use menu representations to draw menus.

    Declaration

    Objective-C

    - (id)tearOffMenuRepresentation

    Return Value

    nil.

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.2.

  • Deprecated.

    Deprecation Statement

    OS X does not use menu representations to draw menus.

    Declaration

    Objective-C

    - (void)setTearOffMenuRepresentation:(id)menuRep

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.2.

  • Deprecated.

    Deprecation Statement

    OS X does not use menu representations to draw menus.

    Declaration

    Objective-C

    - (void)setMenuRepresentation:(id)menuRep

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.2.

  • Deprecated.

    Deprecation Statement

    OS X does not use menu representations to draw menus.

    Declaration

    Objective-C

    - (id)menuRepresentation

    Return Value

    nil.

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.2.

  • These constants are used as a bitmask for specifying a set of menu or menu item properties, and are contained by the propertiesToUpdate property.

    Declaration

    Swift

    struct NSMenuProperties : OptionSetType { init(rawValue rawValue: UInt) static var PropertyItemTitle: NSMenuProperties { get } static var PropertyItemAttributedTitle: NSMenuProperties { get } static var PropertyItemKeyEquivalent: NSMenuProperties { get } static var PropertyItemImage: NSMenuProperties { get } static var PropertyItemEnabled: NSMenuProperties { get } static var PropertyItemAccessibilityDescription: NSMenuProperties { get } }

    Objective-C

    enum { NSMenuPropertyItemTitle = 1 << 0, NSMenuPropertyItemAttributedTitle = 1 << 1 NSMenuPropertyItemKeyEquivalent = 1 << 2, NSMenuPropertyItemImage = 1 << 3, NSMenuPropertyItemEnabled = 1 << 4, NSMenuPropertyItemAccessibilityDescription = 1 << 5 }; typedef NSUInteger NSMenuProperties;

    Constants

    • propertyItemTitle

      NSMenuPropertyItemTitle

      The menu item’s title.

      Available in OS X v10.6 and later.

    • propertyItemAttributedTitle

      NSMenuPropertyItemAttributedTitle

      The menu item’s attributed string title.

      Available in OS X v10.6 and later.

    • propertyItemKeyEquivalent

      NSMenuPropertyItemKeyEquivalent

      The menu item’s key equivalent.

      Available in OS X v10.6 and later.

    • propertyItemImage

      NSMenuPropertyItemImage

      The menu image.

      Available in OS X v10.6 and later.

    • propertyItemEnabled

      NSMenuPropertyItemEnabled

      Whether the menu item is enabled or disabled.

      Available in OS X v10.6 and later.

    • propertyItemAccessibilityDescription

      NSMenuPropertyItemAccessibilityDescription

      The menu item’s accessibility description.

      Available in OS X v10.6 and later.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.6 and later.

  • Posted after a menu item is added to the menu. The notification object is the instance of NSMenu that just added the new menu item. The userInfo dictionary contains the following information.

    Key

    Value

    @"NSMenuItemIndex"

    An NSNumber object containing the integer index of the menu item that was added.

    Declaration

    Swift

    let NSMenuDidAddItemNotification: String

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Posted after a menu item in the menu changes appearance. Changes include enabling/disabling, changes in state, and changes to title. The notification object is the instance of NSMenu with the menu item that changed. The userInfo dictionary contains the following information.

    Key

    Value

    @"NSMenuItemIndex"

    An NSNumber object containing the integer index of the menu item that changed.

    Declaration

    Swift

    let NSMenuDidChangeItemNotification: String

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Posted when menu tracking begins. The notification object is the main menu bar ([NSApp mainMenu]) or the root menu of a popup button. This notification does not contain a userInfo dictionary.

    Declaration

    Swift

    let NSMenuDidBeginTrackingNotification: String

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Posted when menu tracking ends, even if no action is sent. The notification object is the main menu bar ([NSApp mainMenu]) or the root menu of a popup button. This notification does not contain a userInfo dictionary.

    Declaration

    Swift

    let NSMenuDidEndTrackingNotification: String

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • Posted after a menu item is removed from the menu. The notification object is the instance of NSMenu that just removed the menu item. The userInfo dictionary contains the following information.

    Key

    Value

    @"NSMenuItemIndex"

    An NSNumber object containing the integer index of the menu item that was removed. Note that this index may no longer be valid and in any event no longer points to the menu item that was removed.

    Declaration

    Swift

    let NSMenuDidRemoveItemNotification: String

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Posted just after the application dispatches a menu item’s action method to the menu item’s target. The notification object is the instance of NSMenu containing the chosen menu item. The userInfo dictionary contains the following information.

    Key

    Value

    @"MenuItem"

    The menu item that was chosen.

    Declaration

    Swift

    let NSMenuDidSendActionNotification: String

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Posted just before the application dispatches a menu item’s action method to the menu item’s target. The notification object is the instance of NSMenu containing the chosen menu item. The userInfo dictionary contains the following information.

    Key

    Value

    @"MenuItem"

    The menu item that was chosen.

    Declaration

    Swift

    let NSMenuWillSendActionNotification: String

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.