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 Free Software Foundation, Inc.

### Contents -

1. Software documentation for the NSMenu class
2. Software documentation for the NSMenu(GNUstepExtra) category
3. Software documentation for the NSObject(NSMenuActionResponder) informal protocol
4. Software documentation for the NSObject(NSMenuDelegate) informal protocol
5. Software documentation for the NSMenuDelegate protocol
6. Software documentation for the NSMenuValidation protocol
7. Software documentation for the NSMenuView protocol

# Software documentation for the NSMenu class

## NSMenu : NSObject

> Declared in:
>   AppKit/NSMenu.h

> Conforms to:
>   NSCoding
>   NSCopying

Availability: OpenStep

Menus provide the user with a list of actions and/or submenus. Submenus themselves are full fledged menus and so a heirarchical structure of appears.

Every application has one special menu, the so called Application menu. This menu is always visible on the screen when the application is active. This menu normally contains items like, info, services, print, hide and quit.

After the info item normally some submenus follow containing the application specific actions.

On GNUstep the content of the menu is stacked vertically as oppossed to the Windows and Mac world, where they are stacked horizontally. Also because the menus are not part of any normal window they can be dragged around opened and closed independend of the application windows.

This can lead to a few menus being open simultanuously. The collection of open menus is remembered, when the program is started again, all the torn off menus aka detached menus, are displayed at their last known position.

The menu behaviour is richer than in most other environments and bear some explanation. This explanation is aimed at users of Menus but more so at the developer of custom menus.

Application menu
  There alwasy at least one menu present and visible while the application is active. This is the application menu. This window can never be closed.
Attached menu
  Normally when you click in a menu on a submenu item, the submenu is shown directly next to the menu you click in. The submenu is now called an attached menu. It is attached to the menu that was clicked in.
Detached menu
  A menu is detached when it is not attached to its parent menu. A menu can become detached when the user drags a submenu away from its parents. A detached window contains in its title a close button.
Transient menu
  A transient menu is a menu that dissappears as soon as the user stops interacting with the menus. Typically a transient menu is created when a right mouse click appears in an application window. The right mouse click will bring up the Application menu at the place the user clicks. While keeping the mouse button down the user can select items by moving around. When releasing the button, all transient menus will be removed from the screen and the action will be executed.

  It is important to note that it is impossible to click in transient menus.

Attached transient menu
  This is a menu that is attached and transient at the same time.

A single NSMenu instance can be displayed zero or one times when the user is not interaction with the menus. When the user is interaction with the menus it can occur that the same NSMenu is displayed in two locations at the same time. This is only possible when one of the displayed instances is a transient menu.
To understand how the diffent kind of menus are created lets look at some user actions:

- The user clicks on an item which is not a submenu.
  The item is highlighted until the action corresponding with the item is completed. More precisely, the application highlights the menu item, performs the action, and unhighlights the item.
- The user clicks on a submenu item which is not highlighted already
  If the submenu is not a detached menu, the submenu will become an attached menu to the menu that is clicked in. The item that is clicked in will become highlighted and stays highlighted.

  If the submenu is a detached menu, the transient version of the submenu will be shown

- The user clicks on a submenu item which is highlighted
  This means that the submenu is an attached submenu for this menu. After clicking the submenu item will no be no longer highlighted and the submenu will be removed from the screen.
- The user drags over a menu item
  The item will be highlighted, if the item is a submenu item, the submenu will be shown as an attached submenu. This can be transient, or non transient.

Customizing the look of Menus
There are basically three ways of customizing the look of NSMenu

1. Using custom NSMenuItemCell's. This you should do when you want to influence the look of the items displayed in the menu.
2. Using custom NSMenuView. This is the class to modify if you want to change the way the menu is layout on the screen. So if you want to stack the menu items horizontally, you should change this class. This should be rarely needed.
3. Reimplement NSMenu. This you should not do. But, if you implement everything yourself you can achieve anything.

Information for implementing custom NSMenuView class
When implementing a custom NSMenuView class it is important to keep the following information in mind.

- The menus (or the menu items) form a tree. Navigating through this tree is done with the methods [NSMenu -supermenu] , which returns the parent menu of the receiver, and with [NSMenu -itemAtIndex:] which returns a NSMenuItem on which we can call [<NSMenuItem>-submenu] for a child menu.
- The menus as displayed on the screen do NOT form a tree. This because detached and transient menus lead to duplicate menus on the screen.

The displayed menus on the screen have the following structure:

1. The ordered graph of displayed menus (note, NOT the set of NSMenus) form a collection of line graphs.
2. The attached menus are precisely the non root vertices in this graph.
3. An attached menu of a transient menu is itself a transient menu.
4. The collection of transient menus form connect subgraph of the menu graph.

Instance Variables
Method summary

- -_ownedByPopUp
- -_owningPopUp
- -_setOwnedByPopUp:
- -close
- -closeTransient
- -display
- -displayTransient
- -isPartlyOffScreen
- -isTransient
- -nestedSetFrameOrigin:
- -setMain:
- -setTornOff:
- -shiftOnScreen
- -window
- +menuBarVisible
- +menuZone
- +popUpContextMenu:withEvent:forView:
- +popUpContextMenu:withEvent:forView:withFont:
- +setMenuBarVisible:
- +setMenuZone:
- -addItem:
- -addItemWithTitle:action:keyEquivalent:
- -attachedMenu
- -autoenablesItems
- -contextMenuRepresentation
- -delegate
- -helpRequested:
- -indexOfItem:
- -indexOfItemWithRepresentedObject:
- -indexOfItemWithSubmenu:
- -indexOfItemWithTag:
- -indexOfItemWithTarget:andAction:
- -indexOfItemWithTitle:
- -initWithTitle:
- -insertItem:atIndex:
- -insertItemWithTitle:action:keyEquivalent:atIndex:
- -isAttached
- -isTornOff
- -itemArray
- -itemAtIndex:
- -itemChanged:
- -itemWithTag:
- -itemWithTitle:
- -locationForSubmenu:
- -menuBarHeight
- -menuChangedMessagesEnabled
- -menuRepresentation
- -numberOfItems
- -performActionForItemAtIndex:
- -performKeyEquivalent:
- -removeItem:
- -removeItemAtIndex:
- -setAutoenablesItems:
- -setContextMenuRepresentation:
- -setDelegate:
- -setMenuChangedMessagesEnabled:
- -setMenuRepresentation:
- -setSubmenu:forItem:
- -setSupermenu:
- -setTearOffMenuRepresentation:
- -setTitle:
- -sizeToFit
- -submenuAction:
- -supermenu
- -tearOffMenuRepresentation
- -title
- -update

### menuBarVisible

+ (BOOL) menuBarVisible;
Availability: MacOS-X 10.2.0
Description forthcoming.

### menuZone

+ (NSZone*) menuZone;
Availability: OpenStep
Returns the memory allocation zone used to create instances of this class.

### popUpContextMenu: withEvent: forView:

+ (void) popUpContextMenu: (NSMenu*)menu withEvent: (NSEvent*)event forView: (NSView*)view;
Availability: OpenStep
Description forthcoming.

### popUpContextMenu: withEvent: forView: withFont:

+ (void) popUpContextMenu: (NSMenu*)menu withEvent: (NSEvent*)event forView: (NSView*)view withFont: (NSFont*)font;
Availability: MacOS-X 10.3.0
Description forthcoming.

### setMenuBarVisible:

+ (void) setMenuBarVisible: (BOOL)flag;
Availability: MacOS-X 10.2.0
Description forthcoming.

### setMenuZone:

+ (void) setMenuZone: (NSZone*)zone;
Availability: OpenStep
Specifies the memory allocation zone used to create instances of this class.

### addItem:

- (void) addItem: (id<NSMenuItem>)newItem;
Availability: OpenStep
Add newItem to the menu.

### addItemWithTitle: action: keyEquivalent:

- (id<NSMenuItem>) addItemWithTitle: (NSString*)aString action: (SEL)aSelector keyEquivalent: (NSString*)keyEquiv;
Availability: OpenStep
Prefered method for inserting a menu item. This method calls [NSMenu-insertItemWithTitle:-action:-keyEquivalent:-atIndex:]

aString
  The title of the specific menu item.
aSelector
  The action taken by selecting this menu item, or NULL.
keyEquiv
  The shortcut key for this menu item. If none is needed, specify and empty NSString, ie: @"".

See Also: -insertItemWithTitle:-action:-keyEquivalent:-atIndex

### attachedMenu

- (NSMenu*) attachedMenu;
Availability: OpenStep
Returns the menu that is attached to this menu.

If two instances of this menu are visible, return the attached window of the transient version of this menu.

If no menu is attached return `nil`.

### autoenablesItems

- (BOOL) autoenablesItems;
Availability: OpenStep
Returns `YES` if item does autoenable (default value) and `NO` otherwise.

See Also:

- -setAutoenablesItems:

### contextMenuRepresentation

- (id) contextMenuRepresentation;
Availability: Not in OpenStep/MacOS-X removed at MacOS-X 10.1.0
Description forthcoming.

### delegate

- (id) delegate;
Availability: MacOS-X 10.3.0
Description forthcoming.

### helpRequested:

- (void) helpRequested: (NSEvent*)event;
Availability: OpenStep
Description forthcoming.

### indexOfItem:

- (NSInteger) indexOfItem: (id<NSMenuItem>)anObject;
Availability: OpenStep
Returns the index of item anObject.

### indexOfItemWithRepresentedObject:

- (NSInteger) indexOfItemWithRepresentedObject: (id)anObject;
Availability: OpenStep
Returns the index of an item with the represented object anObject.

### indexOfItemWithSubmenu:

- (NSInteger) indexOfItemWithSubmenu: (NSMenu*)anObject;
Availability: OpenStep
Returns the index of an item with the submenu anObject.

### indexOfItemWithTag:

- (NSInteger) indexOfItemWithTag: (NSInteger)aTag;
Availability: OpenStep
Returns the index of an item with the tag aTag.

### indexOfItemWithTarget: andAction:

- (NSInteger) indexOfItemWithTarget: (id)anObject andAction: (SEL)actionSelector;
Availability: OpenStep
Returns the index of an item with the target anObject and the actionSelector .

### indexOfItemWithTitle:

- (NSInteger) indexOfItemWithTitle: (NSString*)aTitle;
Availability: OpenStep
Returns the index of an item with the title aTitle.

### initWithTitle:

- (id) initWithTitle: (NSString*)aTitle;
Availability: OpenStep
This is a designated initialiser for the class.
Description forthcoming.

### insertItem: atIndex:

- (void) insertItem: (id<NSMenuItem>)newItem atIndex: (NSInteger)index;
Availability: OpenStep
Insert newItem at position index.

### insertItemWithTitle: action: keyEquivalent: atIndex:

- (id<NSMenuItem>) insertItemWithTitle: (NSString*)aString action: (SEL)aSelector keyEquivalent: (NSString*)charCode atIndex: (NSInteger)index;
Availability: OpenStep
Inserts a new menu item at position index.

See Also:

- -addItemWithTitle:-action:-keyEquivalent-atIndex:

### isAttached

- (BOOL) isAttached;
Availability: OpenStep
Returns if this menu is attached to its supermenu, return `nil` if it does not have a parent menu.

If two instances of this menu are visible, return the outcome of the check for the transient version of the menu.

Look for the semantics in the header. Note that this implementation works because there are... cases:

1. This menu is transient, its supermenu is also transient. In this case we just do the check between the transient windows and everything is fine
2. The menu is transient, its supermenu is not transient. This can go WRONG

### isTornOff

- (BOOL) isTornOff;
Availability: OpenStep
If there are two instances of this menu visible, return `NO`. Otherwise, return `YES` if we are a detached menu and visible.

### itemArray

- (NSArray*) itemArray;
Availability: OpenStep
Returns an array containing all menu items in this menu.

### itemAtIndex:

- (id<NSMenuItem>) itemAtIndex: (NSInteger)index;
Availability: OpenStep
Returns an item located at index.

### itemChanged:

- (void) itemChanged: (id<NSMenuItem>)anObject;
Availability: OpenStep
Informs the menu that the specified item has changed.

### itemWithTag:

- (id<NSMenuItem>) itemWithTag: (NSInteger)aTag;
Availability: OpenStep
Retuns an item referenced by aTag.

See Also:

- -indexOfItemWithTag:
- [<NSMenuItem>-tag]

### itemWithTitle:

- (id<NSMenuItem>) itemWithTitle: (NSString*)aString;
Availability: OpenStep
Returns an item with aString as its title.

### locationForSubmenu:

- (NSPoint) locationForSubmenu: (NSMenu*)aSubmenu;
Availability: OpenStep
Returns the position where submenu will be displayed when it will be displayed as an attached menu of this menu. The result is undefined when aSubmenu is not actually a submenu of this menu.

### menuBarHeight

- (float) menuBarHeight;
Availability: MacOS-X 10.4.0
Description forthcoming.

### menuChangedMessagesEnabled

- (BOOL) menuChangedMessagesEnabled;
Availability: OpenStep
Description forthcoming.

### menuRepresentation

- (id) menuRepresentation;
Availability: OpenStep
Return the NSView that is used for drawing the menu. It is the view set with [NSMenu -setMenuRepresentation:] and therefore it should be safe to assume it is an NSView implementing the NSMenuView protocol.

### numberOfItems

- (NSInteger) numberOfItems;
Availability: OpenStep
Returns the numbers of items on the menu

### performActionForItemAtIndex:

- (void) performActionForItemAtIndex: (NSInteger)index;
Availability: OpenStep
Simulates a mouse click on item located at index.

See Also:

- -indexOfItem:
- -indexOfItemWithTitle:

### performKeyEquivalent:

- (BOOL) performKeyEquivalent: (NSEvent*)theEvent;
Availability: OpenStep
Looks for a menu item that responds to theEvent on the receiver. If the receiver is a submenu, the method is performed on it.

### removeItem:

- (void) removeItem: (id<NSMenuItem>)anItem;
Availability: OpenStep
Calls -removeItemAtIndex: for anItem.

### removeItemAtIndex:

- (void) removeItemAtIndex: (NSInteger)index;
Availability: OpenStep
Removes item at position index.

### setAutoenablesItems:

- (void) setAutoenablesItems: (BOOL)flag;
Availability: OpenStep
Sets if a menu does autoenable.

### setContextMenuRepresentation:

- (void) setContextMenuRepresentation: (id)representation;
Availability: Not in OpenStep/MacOS-X removed at MacOS-X 10.1.0
Description forthcoming.

### setDelegate:

- (void) setDelegate: (id)delegate;
Availability: MacOS-X 10.3.0
Description forthcoming.

### setMenuChangedMessagesEnabled:

- (void) setMenuChangedMessagesEnabled: (BOOL)flag;
Availability: OpenStep
Description forthcoming.

### setMenuRepresentation:

- (void) setMenuRepresentation: (id)menuRep;
Availability: OpenStep
Set the View that should be used to display the menu.

The default is NSMenuView, but a user can supply its own NSView object as long as it

- Inherits from NSView
- Implements NSMenuView protocol

### setSubmenu: forItem:

- (void) setSubmenu: (NSMenu*)aMenu forItem: (id<NSMenuItem>)anItem;
Availability: OpenStep
Set a submenu of a menu.

aMenu
  The submenu to be inserted.
anItem
  Item to be turned into a submenu.

See Also:

- [<NSMenuItem>-setSubmenu:]

### setSupermenu:

- (void) setSupermenu: (NSMenu*)supermenu;
Availability: OpenStep
Set the supermenu of this menu. TODO: add explanation if this will change remove this menu from the old supermenu or if it does not.

### setTearOffMenuRepresentation:

- (void) setTearOffMenuRepresentation: (id)representation;
Availability: Not in OpenStep/MacOS-X removed at MacOS-X 10.1.0
Description forthcoming.

### setTitle:

- (void) setTitle: (NSString*)aTitle;
Availability: OpenStep
Change the title of the menu.

### sizeToFit

- (void) sizeToFit;
Availability: OpenStep
Description forthcoming.

### submenuAction:

- (void) submenuAction: (id)sender;
Availability: OpenStep
Description forthcoming.

### supermenu

- (NSMenu*) supermenu;
Availability: OpenStep
Returns the supermenu of this menu. Return `nil` if this is the application menu.

### tearOffMenuRepresentation

- (id) tearOffMenuRepresentation;
Availability: Not in OpenStep/MacOS-X removed at MacOS-X 10.1.0
Description forthcoming.

### title

- (NSString*) title;
Availability: OpenStep
Returns the current title.

### update

- (void) update;
Availability: OpenStep
Description forthcoming.

## Instance Variables for NSMenu Class

### _attachedMenu

@protected NSMenu* _attachedMenu;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _delegate

@protected id _delegate;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _items

@protected NSMutableArray* _items;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _notifications

@protected NSMutableArray* _notifications;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _popUpButtonCell

@protected NSPopUpButtonCell* _popUpButtonCell;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _superMenu

@protected NSMenu* _superMenu;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _title

@protected NSString* _title;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _view

@protected NSView* _view;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### struct GSMenuFlags

@protected struct GSMenuFlags struct GSMenuFlags;
Availability: OpenStep
Description forthcoming.

# Software documentation for the NSMenu(GNUstepExtra) category

## NSMenu(GNUstepExtra)

> Declared in:
>   AppKit/NSMenu.h

Availability: Not in OpenStep/MacOS-X
This interface exist contains methods that are meant for the NSMenuView. If you write your own implementation of the NSMenuView interface you can use these methods to popup other menus or close them.
Method summary

- -_ownedByPopUp
- -_owningPopUp
- -_setOwnedByPopUp:
- -close
- -closeTransient
- -display
- -displayTransient
- -isPartlyOffScreen
- -isTransient
- -nestedSetFrameOrigin:
- -setMain:
- -setTornOff:
- -shiftOnScreen
- -window

### _ownedByPopUp

- (BOOL) _ownedByPopUp;
Availability: Not in OpenStep/MacOS-X
Warning the underscore at the start of the name of this method indicates that it is private, for internal use only, and you should not use the method in your code.

### _owningPopUp

- (NSPopUpButtonCell*) _owningPopUp;
Availability: Not in OpenStep/MacOS-X
Warning the underscore at the start of the name of this method indicates that it is private, for internal use only, and you should not use the method in your code.

### _setOwnedByPopUp:

- (void) _setOwnedByPopUp: (NSPopUpButtonCell*)popUp;
Availability: Not in OpenStep/MacOS-X
Warning the underscore at the start of the name of this method indicates that it is private, for internal use only, and you should not use the method in your code.

### close

- (void) close;
Availability: Not in OpenStep/MacOS-X
Remove the window from the screen. This method can/should be used by the menurepresentation to remove a submenu from the screen.

### closeTransient

- (void) closeTransient;
Availability: Not in OpenStep/MacOS-X
Remove the transient version of the window from the screen. This method is used by NSMenuView implementations that need to open/close transient menus.

### display

- (void) display;
Availability: Not in OpenStep/MacOS-X
Show menu on the screen. This method can/should be used by the menurepresentation to display a submenu on the screen.

### displayTransient

- (void) displayTransient;
Availability: Not in OpenStep/MacOS-X
Display the transient version of the menu.

### isPartlyOffScreen

- (BOOL) isPartlyOffScreen;
Availability: Not in OpenStep/MacOS-X
Description forthcoming.

### isTransient

- (BOOL) isTransient;
Availability: Not in OpenStep/MacOS-X
Returns `YES` if there is a transient version of this menu displayed on the screen.

### nestedSetFrameOrigin:

- (void) nestedSetFrameOrigin: (NSPoint)aPoint;
Availability: Not in OpenStep/MacOS-X
Set the frame origin of the receiver to aPoint. If a submenu of the receiver is attached. The frame origin of the submenu is set appropriately.

### setMain:

- (void) setMain: (BOOL)isMain;
Availability: Not in OpenStep/MacOS-X
Flag this menu to be the main menu of the application, when isMain is `YES`. Flag it as no longer being the main menu when `NO` is handed in.

This method also checks the user defaults to determine how the menu is to be displayed (eg vertical or horizontal) and can therefore be used to change window geometry.

### setTornOff:

- (void) setTornOff: (BOOL)flag;
Availability: Not in OpenStep/MacOS-X
When the flag is `YES` this method will detach the receiver from its parent and update the menurepresentation so it will display a close button if appropriate.

If the flag is `NO` this method will update the menurepresentation so it will be able to remove the close button if needed. Note that it will not reattach to its parent menu.

### shiftOnScreen

- (void) shiftOnScreen;
Availability: Not in OpenStep/MacOS-X
Description forthcoming.

### window

- (NSWindow*) window;
Availability: Not in OpenStep/MacOS-X
Returns the window in which this menu is displayed. If there is a transient version it will return the window in which the transient version is displayed. If the Menu is not displayed at all the result is meaningless.

# Software documentation for the NSObject(NSMenuActionResponder) informal protocol

## NSObject(NSMenuActionResponder)

> Declared in:
>   AppKit/NSMenu.h

Availability: Not in OpenStep/MacOS-X
Description forthcoming.
Method summary

- -validateMenuItem:

### validateMenuItem:

- (BOOL) validateMenuItem: (id<NSMenuItem>)aMenuItem;
Availability: Not in OpenStep/MacOS-X
Description forthcoming.

# Software documentation for the NSObject(NSMenuDelegate) informal protocol

## NSObject(NSMenuDelegate)

> Declared in:
>   AppKit/NSMenu.h

Availability: MacOS-X 10.3.0
Description forthcoming.
Method summary

- -menu:updateItem:atIndex:shouldCancel:
- -menuHasKeyEquivalent:forEvent:target:action:
- -menuNeedsUpdate:
- -numberOfItemsInMenu:

### menu: updateItem: atIndex: shouldCancel:

- (BOOL) menu: (NSMenu*)menu updateItem: (NSMenuItem*)item atIndex: (NSInteger)index shouldCancel: (BOOL)shouldCancel;
Availability: MacOS-X 10.3.0
Description forthcoming.

### menuHasKeyEquivalent: forEvent: target: action:

- (BOOL) menuHasKeyEquivalent: (NSMenu*)menu forEvent: (NSEvent*)event target: (id*)target action: (SEL*)action;
Availability: MacOS-X 10.3.0
Description forthcoming.

### menuNeedsUpdate:

- (void) menuNeedsUpdate: (NSMenu*)menu;
Availability: MacOS-X 10.3.0
Description forthcoming.

### numberOfItemsInMenu:

- (NSInteger) numberOfItemsInMenu: (NSMenu*)menu;
Availability: MacOS-X 10.3.0
Description forthcoming.

# 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:
- -menu:updateItem:atIndex:shouldCancel:
- -menu:willHighlightItem:
- -menuDidClose:
- -menuHasKeyEquivalent:forEvent:target:action:
- -menuNeedsUpdate:
- -menuWillOpen:
- -numberOfItemsInMenu:

### 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 NSMenuValidation protocol

## NSMenuValidation

> Declared in:
>   AppKit/NSMenu.h

Availability: OpenStep
Specifies the protocol to which an object must confirm if it is to be used to validate menu items (in order to implement automatic enabling and disabling of menu items).
Method summary

- -validateMenuItem:

### validateMenuItem:

- (BOOL) validateMenuItem: (id<NSMenuItem>)menuItem;
Availability: OpenStep

The receiver should return `YES` if the menuItem is valid... and should be enabled in the menu, `NO` if it is invalid and the user should not be able to select it.

This method is invoked automatically to determine whether menu items should be enabled or disabled automatically whenever [NSMenu -update] is invoked (usually by the applications event loop).

# Software documentation for the NSMenuView protocol

## NSMenuView

> Declared in:
>   AppKit/NSMenu.h

Availability: OpenStep
Description forthcoming.
Method summary

- -detachSubmenu
- -highlightedItemIndex
- -imageAndTitleOffset
- -imageAndTitleWidth
- -keyEquivalentOffset
- -keyEquivalentWidth
- -locationForSubmenu:
- -performActionWithHighlightingForItemAtIndex:
- -setHighlightedItemIndex:
- -setMenu:
- -sizeToFit
- -stateImageWidth
- -trackWithEvent:
- -update

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