Mac Developer Library

Developer

AppKit Framework Reference NSMenuDelegate Protocol Reference

Options
Deployment Target:

On This Page
Language:

NSMenuDelegate

Inheritance


Not Applicable

Import Statement


Swift

import AppKit

Objective-C

@import AppKit;

Availability


Available in OS X v10.6 and later.

The NSMenuDelegate protocol defines the optional methods implemented by delegates of NSMenu objects.

  • Invoked to allow the delegate to return the target and action for a key-down event.

    Declaration

    Swift

    optional func menuHasKeyEquivalent(_ menu: NSMenu, forEvent event: NSEvent, target target: AutoreleasingUnsafeMutablePointer<AnyObject?>, action action: UnsafeMutablePointer<Selector>) -> Bool

    Objective-C

    - (BOOL)menuHasKeyEquivalent:(NSMenu *)menu forEvent:(NSEvent *)event target:(id *)target action:(SEL *)action

    Parameters

    menu

    The menu object sending the delegation message.

    event

    An NSEvent object representing a key-down event.

    target

    Return by reference the target object for the menu item that corresponds to the event. Specify nil to request the menu's target.

    action

    Return by reference the action selector for the menu item that corresponds to the event.

    Return Value

    If there is a valid and enabled menu item that corresponds to this key-down even, return YEStrue after specifying the target and action. Return NOfalse if there are no items with that key equivalent or if the item is disabled.

    Discussion

    If the delegate doesn’t define this method, the menu is populated to find out if any items have a matching key equivalent.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

    Available as part of an informal protocol prior to OS X v10.6.

  • Invoked to let the delegate update a menu item before it is displayed.

    Declaration

    Swift

    optional func menu(_ menu: NSMenu, updateItem item: NSMenuItem, atIndex index: Int, shouldCancel shouldCancel: Bool) -> Bool

    Objective-C

    - (BOOL)menu:(NSMenu *)menu updateItem:(NSMenuItem *)item atIndex:(NSInteger)index shouldCancel:(BOOL)shouldCancel

    Parameters

    menu

    The menu object that owns item.

    item

    The menu-item object that may be updated.

    index

    The integer index of the menu item.

    shouldCancel

    Set to YEStrue if, due to some user action, the menu no longer needs to be displayed before all the menu items have been updated. You can ignore this flag, return YEStrue, and continue; or you can save your work (to save time the next time your delegate is called) and return NOfalse to stop the updating.

    Return Value

    YEStrue to continue the process. If you return NOfalse, your menu:updateItem:atIndex:shouldCancel: is not called again. In that case, it’s your responsibility to trim any extra items from the menu.

    Discussion

    If your numberOfItemsInMenu: delegate method returns a positive value, then your menu:updateItem:atIndex:shouldCancel: method is called for each item in the menu. You can then update the menu title, image, and so forth for each menu item.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

    Available as part of an informal protocol prior to OS X v10.6.

  • Invoked to allow the delegate to specify a display location for the menu.

    Declaration

    Swift

    optional func confinementRectForMenu(_ menu: NSMenu, onScreen screen: NSScreen?) -> NSRect

    Objective-C

    - (NSRect)confinementRectForMenu:(NSMenu *)menu onScreen:(NSScreen *)screen

    Parameters

    menu

    The menu object.

    screen

    The screen the menu will open on.

    Return Value

    The rectangle the menu should be displayed within, in screen coordinates.

    Discussion

    This method is sent to the delegate when a menu is about to be opened on the specified screen.

    If you return NSZeroRect, or if the delegate doesn’t implement this method, the menu will be confined to the bounds appropriate for the given screen. The returned rect may not be honored in all cases, for example, if it would force the menu to be too small.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.6 and later.

  • Invoked to indicate that a menu is about to highlight a given item.

    Declaration

    Swift

    optional func menu(_ menu: NSMenu, willHighlightItem item: NSMenuItem?)

    Objective-C

    - (void)menu:(NSMenu *)menu willHighlightItem:(NSMenuItem *)item

    Parameters

    menu

    The menu object about to highlight an item.

    item

    The item about to be highlighted.

    Discussion

    Only one item per menu can be highlighted at a time. If item is nil, it means that all items in the menu are about to be unhighlighted.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

    Available as part of an informal protocol prior to OS X v10.6.

    See Also

    highlightedItem (NSMenu)

  • Invoked when a menu is about to open.

    Declaration

    Swift

    optional func menuWillOpen(_ menu: NSMenu)

    Objective-C

    - (void)menuWillOpen:(NSMenu *)menu

    Parameters

    menu

    The menu that is about to open.

    Special Considerations

    Don’t modify the structure of the menu or the menu items during this method.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

    Available as part of an informal protocol prior to OS X v10.6.

  • Invoked after a menu closed.

    Declaration

    Swift

    optional func menuDidClose(_ menu: NSMenu)

    Objective-C

    - (void)menuDidClose:(NSMenu *)menu

    Parameters

    menu

    The menu that closed.

    Special Considerations

    Don’t modify the structure of the menu or the menu items during this method.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

    Available as part of an informal protocol prior to OS X v10.6.

  • Invoked when a menu is about to be displayed at the start of a tracking session so the delegate can specify the number of items in the menu.

    Declaration

    Swift

    optional func numberOfItemsInMenu(_ menu: NSMenu) -> Int

    Objective-C

    - (NSInteger)numberOfItemsInMenu:(NSMenu *)menu

    Parameters

    menu

    The menu object about to be displayed.

    Return Value

    The number of menu items in the menu.

    Discussion

    If you return a positive value, the menu is resized by either removing or adding items. Newly created items are blank. After the menu is resized, your menu:updateItem:atIndex:shouldCancel: method is called for each item. If you return a negative value, the number of items is left unchanged and menu:updateItem:atIndex:shouldCancel: is not called. If you can populate the menu quickly, you can implement menuNeedsUpdate: instead of numberOfItemsInMenu: and menu:updateItem:atIndex:shouldCancel:.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

    Available as part of an informal protocol prior to OS X v10.6.

  • Invoked when a menu is about to be displayed at the start of a tracking session.

    Declaration

    Swift

    optional func menuNeedsUpdate(_ menu: NSMenu)

    Objective-C

    - (void)menuNeedsUpdate:(NSMenu *)menu

    Parameters

    menu

    The menu object that is about to be displayed.

    Discussion

    Using this method, the delegate can change the menu by adding, removing, or modifying menu items. If populating the menu will take a long time, implement numberOfItemsInMenu: and menu:updateItem:atIndex:shouldCancel: instead.

    Menu item validation occurs after this method is called. If the menu is updated because the user pressed a command key, only the menu item with the matching command key is validated; if the menu is updated because the user opened it, then every menu item is validated.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

    Available as part of an informal protocol prior to OS X v10.6.