NSMenuDelegate Protocol Reference

Conforms to
NSObject
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.6 and later.
Companion guide
Application Menu and Pop-up List Programming Topics
Declared in
NSMenu.h
Related sample code

Overview

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

Tasks

Handling Keyboard Equivalents

Updating Menu Layout

Handling Highlighting

Handling Open and Close Events

Handling Tracking

Instance Methods

confinementRectForMenu:onScreen:

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

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

The menu object.

screen

The screen the menu will open on.

Return Value

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

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 does not 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.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSMenu.h

menu:updateItem:atIndex:shouldCancel:

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

- (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 YES 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 YES, and continue; or you can save your work (to save time the next time your delegate is called) and return NO to stop the updating.

Return Value

YES to continue the process. If you return NO, your menu:updateItem:atIndex:shouldCancel: is not called again. In that case, it is 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.

Availability
  • Available in OS X v10.3 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSMenu.h

menu:willHighlightItem:

Invoked to indicates that a menu is about to highlight a given item.

- (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

Availability
  • Available in OS X v10.5 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
See Also
Declared In
NSMenu.h

menuDidClose:

Invoked after a menu closed.

- (void)menuDidClose:(NSMenu *)menu
Parameters
menu

The menu that closed.

Special Considerations

Do not modify the structure of the menu or the menu items during this method.

Availability
  • Available in OS X v10.5 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
See Also
Declared In
NSMenu.h

menuHasKeyEquivalent:forEvent:target:action:

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

- (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 requests 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 YES after specifying the target and action. Return NO if there are no items with that key equivalent or if the item is disabled.

Discussion

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

Availability
  • Available in OS X v10.3 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
See Also
Declared In
NSMenu.h

menuNeedsUpdate:

Invoked when a menu is about to be displayed at the start of a tracking session so the delegate can modify the menu.

- (void)menuNeedsUpdate:(NSMenu *)menu
Parameters
menu

The menu object that is about to be displayed.

Discussion

You can change the menu by adding, removing or modifying menu items. Be sure to set the proper enable state for any new menu items. If populating the menu will take a long time, implement numberOfItemsInMenu: and menu:updateItem:atIndex:shouldCancel: instead.

Availability
  • Available in OS X v10.3 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSMenu.h

menuWillOpen:

Invoked when a menu is about to open.

- (void)menuWillOpen:(NSMenu *)menu
Parameters
menu

The menu that is about to open.

Special Considerations

Do not modify the structure of the menu or the menu items during this method.

Availability
  • Available in OS X v10.5 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
See Also
Declared In
NSMenu.h

numberOfItemsInMenu:

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.

- (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:.

Availability
  • Available in OS X v10.3 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSMenu.h


© 2009 Apple Inc. All Rights Reserved. (Last updated: 2009-11-12)

Did this document help you? Yes It's good, but... Not helpful...