Up

NSMenu

Authors

Fred Kiefer (FredKiefer@gmx.de)
David Lazaro Saz (khelekir@encomix.es)
Michael Hanni (mhanni@sprintmail.com)
Felipe A. Rodriguez (far@ix.netcom.com)
Ovidiu Predescu (ovidiu@net-community.com)

Copyright: (C) 1999,2016 Free Software Foundation, Inc.


Contents -

  1. Software documentation for the NSMenuDelegate protocol
  2. Software documentation for the NSMenuView protocol

Software documentation for the NSMenuDelegate protocol

NSMenuDelegate

Declared in:
AppKit/NSMenu.h
Conforms to:
NSObject
Availability: OpenStep

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

confinementRectForMenu: onScreen: 

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

Specify a display location for the menu

menu: updateItem: atIndex: shouldCancel: 

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

Invoked to allow the delegate to update an item before it is displayed.

menu: willHighlightItem: 

- (void) menu: (NSMenu*)menu willHighlightItem: (NSMenuItem*)item;
Availability: OpenStep

Invoked too notify the delegate that the item will be highlighted.

menuDidClose: 

- (void) menuDidClose: (NSMenu*)menu;
Availability: OpenStep

Invoked to inform the delegate that the menu did close.

menuHasKeyEquivalent: forEvent: target: action: 

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

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

menuNeedsUpdate: 

- (void) menuNeedsUpdate: (NSMenu*)menu;
Availability: OpenStep

Invoked to indicate that the menu is about to be updated.

menuWillOpen: 

- (void) menuWillOpen: (NSMenu*)menu;
Availability: OpenStep

Invoked on the delegate to allow changes before the menu opens.

numberOfItemsInMenu: 

- (NSInteger) numberOfItemsInMenu: (NSMenu*)menu;
Availability: OpenStep

Invoked when the menu is about to be displayed.

Software documentation for the NSMenuView protocol

NSMenuView

Declared in:
AppKit/NSMenu.h
Availability: OpenStep

Description forthcoming.
Method summary

detachSubmenu 

- (void) detachSubmenu;
Availability: OpenStep

This should ensure that if there is an attached submenu this submenu will be detached. Detaching means that this particular menu representation should be removed from the screen. It should implement a deep detach, that is, all attached submenus of this menu should also be detached.

highlightedItemIndex 

- (NSInteger) highlightedItemIndex;
Availability: OpenStep

Returns the currently highlighted item. Returns -1 if no item is highlighted.

imageAndTitleOffset 

- (float) imageAndTitleOffset;
Availability: OpenStep

Method used by NSMenuItemCell to draw itself correctly and nicely lined up with the other menu items

imageAndTitleWidth 

- (float) imageAndTitleWidth;
Availability: OpenStep

Methos used by NSMenuItemCell to draw itself correctly and nicely lined up with the other menu items.

keyEquivalentOffset 

- (float) keyEquivalentOffset;
Availability: OpenStep

Methos used by NSMenuItemCell to draw itself correctly and nicely lined up with the other menu items.

keyEquivalentWidth 

- (float) keyEquivalentWidth;
Availability: OpenStep

Used by NSItemCell to...

locationForSubmenu: 

- (NSPoint) locationForSubmenu: (NSMenu*)aSubmenu;
Availability: OpenStep

Used by the NSMenu to determine where to position a submenu.

performActionWithHighlightingForItemAtIndex: 

- (void) performActionWithHighlightingForItemAtIndex: (NSInteger)index;
Availability: OpenStep

Description forthcoming.

setHighlightedItemIndex: 

- (void) setHighlightedItemIndex: (NSInteger)index;
Availability: OpenStep

Set the currently highlighted item. This is used by the NSMenu class to restore the selected item when it is temporary set to another item. This happens when both the regular version and the transient version are on the screen. A value of -1 means that no item will be highlighted.

setMenu: 

- (void) setMenu: (NSMenu*)menu;
Availability: OpenStep

Set the menu that this view object will be drawing. This method will NOT retain the menu. In normal usage an instance of NSMenu will use this method to supply the NSMenuView with reference to itself. The NSMenu will retain the NSMenuView.

sizeToFit 

- (void) sizeToFit;
Availability: OpenStep

Hm, why is this method needed? Shouldn't this be done by the update method?

stateImageWidth 

- (float) stateImageWidth;
Availability: OpenStep

Method used by NSMenuItemCell to draw itself correctly and nicely lined up with the other menu items.

trackWithEvent: 

- (BOOL) trackWithEvent: (NSEvent*)event;
Availability: OpenStep

This is method is responsible for handling all events while the user is interacting with this menu. It should pass on this call to another menurepresentation when the user moves the mouse cursor over either a submenu or over the supermenu.

The method returns when the interaction from the user with the menu system is over.

The method returns NO when the user releases the mouse button above a submenu item and YES in all other cases.

This return value can be used to determine if submenus should be removed from the screen or that they are supposed to stay.

The implementation should roughly follow the following logic:

{while (have not released mouse button) {if (mouse hovers over submenu, or supermenu) {if ([(menurepresentation under mouse) trackWithEvent: the event]) { [self detachSubmenu]; return YES;} return NO;} //highlight item under mouse if (highlighting submenu item) {[self attachSubmenuAtIndex:..];} else {[self detachSubmenu];} get next event.} execute the menu action if applicable; return YES | NO depending on the situation;} Note that actual implementations tend to be more complicated because because of all kind of useability issues. Useabilities issues to look out for are:

  • Menus that are only partly on the screen. Those need to be moved while navigation the menu.
  • Submenus that are hard to reach. If the natural route to the content of a submenu travels through other menu items you do not want to remove the submenu immediately.
  • Transient menus require slightly different behaviour from the normal menus. For example, when selecting a action from a transient menu that brings up a modal panel you would expect the transient menu to dissappear. However in the normal menu system you want it to stay, so you still have feedback on which menu action triggered the modal panel.

update 

- (void) update;
Availability: OpenStep

This will relayout the NSMenuView. It should be called when the menu changes. Changes include becoming detached, adding or removing submenu items etcetera. However, normally it does not need to be called directly because Because the NSMenuView is supposed to listen to the NSMenu notifications for the item added, removed and change notifications. It should be called explicitly when other changes occur, such as becoming detached or changing the title.


Up