[TOC] [Prev] [Next]

NSMenu

Inherits From:
NSObject

Conforms To:
NSCoding
NSCopying
NSObject (NSObject)

Declared In:
AppKit/NSMenu.h

Class Description

This class defines an object that manages an application's menus. An NSMenu object displays a list of items that a user can choose from. When an item is clicked, the NSMenu object may either issue a command directly (by sending an action message to a target object) or bring up another menu (a submenu) that offers further choices. An NSMenu object's choices are implemented with NSMenuItem objects. Each menu item can be configured either to send its action message to a target or to open a submenu.

It's typically more convenient to use Interface Builder to construct your application's menus-see Interface Builder's Help for more information about using this application. NSMenu and NSMenuItem provide you with additional flexibility to contruct or modify your application's menus dynamically at run time.

Exactly one NSMenu created by the application is designated as the main menu for the application (with NSApplication's setMainMenu: method). Depending on the user interface of the host system, the main menu displays itself as a free-standing window with a title bar and a list of menu items, as a menu bar with no title, or in some other form. The form a menu takes in the user interface may limit which methods in the class's interface actually have an effect; for example, on Microsoft Windows submenus can't be detached. In all cases, however, methods return values that reflect the NSMenu object's actual state or ability (isTornOff always returns NO on Microsoft Windows, for example).

On Mach, a free-standing main menu is displayed on top of all other windows whenever the application is active; the user can move it by dragging its title bar. When a submenu is opened, it appears attached to the right of its supermenu with a title bar, allowing the user to drag it away from its supermenu so that it remains on the screen. A detached submenu displays a close button to allow the user to dismiss it (the main menu, of course, never displays a close button). If the user moves a menu window while a submenu is attached, the submenu follows its supermenu. If a menu window lies partly off-screen, when the user tracks the mouse pointer to the edge of the screen, by holding down the mouse button and dragging the mouse pointer, the menu temporarily shifts onto the screen (along with any attached super- or submenus), allowing the user to access all of its items.

Where the main menu appears as a menu bar (Windows, for example), the menu doesn't display a title, nor do its submenus. The submenus of a menu bar are typical drop-down menus, and submenus of these appear to the right or left, depending on the available screen space.

NSMenu supports the assignment of keyboard equivalents (command-key accelerators) to its menu items. On Microsoft Windows, the class also supports the assignment of mnemonics to menu items. Any menu item, except those that open submenus, can have a key equivalent, but whether they should have one depends on the user interface guidelines of the host system's. Unlike keyboard equivalents, mnemonics only function when their menu is active, and they can be assigned to menu items which open submenus.

The items that appear on menus belong to the NSMenuItem class, which simply adopts the NSMenuItem protocol and adds little other behavior. See the specifications of the NSMenuItem and NSMenuValidation protocols for more information.

Menu Autoenabling

By default, menus are autoenabled. "Autoenabling" refers to the ability of a menu to enable or disable its items after a user event by querying other objects in an application for the appropriate state. (A disabled menu item has a gray title and does not respond to mouse clicks or key equivalents.) For instance, if the user selects some text in a scroll view, the object responsible for managing that text could receive-as the target of menu items such as Cut, Copy, and Paste-the message validateMenuItem: for each of those items (see informal protocol NSMenuValidation). It would implement this message to evaluate the current context and return whether the menu item should be enabled.

An NSMenu object locates the "validator" object for a menu item by testing for the existence of the following objects, in the given order:

By following these steps, the NSMenu ensures that the object receiving the action message is asked to validate the menu state.

If the NSMenu object cannot locate a "validator," it disables the menu item. If the validator responds to validateMenuItem:, NSMenu asks it for the enabled state. If the validator does not respond to the message, NSMenu enables the menu item.

You can turn off autoenabling by sending setAutoenablesItems: to the NSMenu object with an argument of NO. You should do this if your application explicitly controls the state of each of its menu items (see the NSMenuItem protocol method setEnabled:). Although autoenabling occurs automatically upon each user event, you can request it for other purposes with the update method.


Method Types

Controlling allocation zones + menuZone
+ setMenuZone:
Creating an NSMenu
- initWithTitle:
Setting up menu commands
- insertItem:atIndex:
- insertItemWithTitle:action:keyEquivalent:atIndex:
- addItem:
- addItemWithTitle:action:keyEquivalent:
- removeItem:
- removeItemAtIndex:
- itemChanged:
Finding menu items
- itemWithTag:
- itemWithTitle:
- itemAtIndex:
- numberOfItems
- itemArray
Finding indices of menu items
- indexOfItem:
- indexOfItemWithTitle:
- indexOfItemWithTag:
- indexOfItemWithTarget:andAction:
- indexOfItemWithRepresentedObject:
- indexOfItemWithSubmenu:
Managing submenus
- setSubmenu:forItem:
- submenuAction:
- attachedMenu
- isAttached
- isTornOff
- locationForSubmenu:
- supermenu
- setSupermenu:
Enabling and disabling menu items
- autoenablesItems
- setAutoenablesItems:
- update
Handling keyboard equivalents
- performKeyEquivalent:
Simulating mouse clicks
- performActionForItemAtIndex:
Setting the title
- setTitle:
- title
Setting the representing object
- setMenuRepresentation:
- menuRepresentation
Updating menu layout
- menuChangedMessagesEnabled
- setMenuChangedMessagesEnabled:
- sizeToFit
Displaying context-sensitive help
- helpRequested:

Class Methods

menuZone

+ (NSZone *)menuZone

Returns the zone from which NSMenus should be allocated, creating it if necessary.


setMenuZone:

+ (void)setMenuZone:(NSZone *)zone

Sets the zone from which NSMenus should be allocated to zone.


Instance Methods

addItem:

- (void)addItem:(id <NSMenuItem>)newItem

Adds the menu item newItem to the end of the receiving NSMenu. In its implementation this method invokes insertItem:atIndex:. Thus, the menu does not accept the menu item if it already belongs to another menu. After adding the menu item, the menu updates itself.


addItemWithTitle:action:keyEquivalent:

- (id <NSMenuItem>)addItemWithTitle:(NSString *)aString
action:(SEL)aSelector
keyEquivalent:(NSString *)keyEquiv

Adds a new item with title aString, action aSelector, and key equivalent keyEquiv to the end of the menu. Returns the new menu item. If you do not want the menu item to have a key equivalent, keyEquiv should be an empty string (@"") and not nil.


attachedMenu

- (NSMenu *)attachedMenu

Returns the menu currently attached to the receiver or nil if there's no such object.


autoenablesItems

- (BOOL)autoenablesItems

Returns whether the receiver automatically enables and disables its menu items based on the NSMenuValidation informal protocol. By default NSMenus do autoenable their menu items. See that protocol specification for more information.

See also: - setAutoenablesItems:


helpRequested:

- (void)helpRequested:(NSEvent *)event

Overridden by subclasses to implement specialized context-sensitive help behavior by causing the Help manager to display the help associated with the receiver. Never invoke this method directly.

See also: - showContextHelpForObject:locationHint: (NSHelpManager)


indexOfItem:

- (int)indexOfItem:(id <NSMenuItem>)anObject

Returns the index identifying the location of menu item anObject in the receiver. If no such menu item is in the menu, the method returns -1.

See also: - insertItem:atIndex:, - itemAtIndex:


indexOfItemWithRepresentedObject:

- (int)indexOfItemWithRepresentedObject:(id)anObject

Returns the index of the first menu item in the receiver that has anObject as its represented object. If no such menu item is in the menu, the method returns -1.

See also: - insertItem:atIndex:, - itemAtIndex:


indexOfItemWithSubmenu:

- (int)indexOfItemWithSubmenu:(NSMenu *)anObject

Returns the index of the menu item in the receiver that has submenu anObject. If no such menu item is in the menu, the method returns -1.

See also: - insertItem:atIndex:, - itemAtIndex:


indexOfItemWithTag:

- (int)indexOfItemWithTag:(int)aTag

Returns the index of the first menu item in the receiver identified by tag aTag. If no such menu item is in the menu, the method returns -1.

See also: - insertItem:atIndex:, - itemAtIndex:


indexOfItemWithTarget:andAction:

- (int)indexOfItemWithTarget:(id)anObject andAction:(SEL)actionSelector

Returns the index of the first menu item in the receiver that has a target of anObject and an action of actionSelector. If actionSelector is NULL, the first menu item in the receiver that has a target of anObject is returned. If no menu item matching these criteria is in the menu, the method returns -1.

See also: - insertItem:atIndex:, - itemAtIndex:


indexOfItemWithTitle:

- (int)indexOfItemWithTitle:(NSString *)aTitle

Returns the index of the first menu item in the receiver that has the title aTitle. If no such menu item is in the menu, the method returns -1.

See also: - insertItem:atIndex:, - itemAtIndex:


initWithTitle:

- (id)initWithTitle:(NSString *)aTitle

Initializes and returns a new menu using aTitle for its title and with autoenabling of menu items turned on. This method is the designated initializer for the class. Returns self.

See also: - setAutoenablesItems:


insertItem:atIndex:

- (void)insertItem:(id <NSMenuItem>)newItem atIndex:(int)index

Inserts the menu item newItem in the receiving NSMenu at location index. If the menu item already exists in another menu, it is not inserted. The method informs the object implementing the platform-specific look and behavior of the menu (the "menu representation") that the item has been inserted. It also causes the menu to update itself. This is a primitive method; if you create a subclass of NSMenu, this method must be overriden.

See also: - addItem:, - itemAtIndex:, - removeItem:


insertItemWithTitle:action:keyEquivalent:atIndex:

- (id <NSMenuItem>)insertItemWithTitle:(NSString *)aString
action:(SEL)aSelector
keyEquivalent:(NSString *)keyEquiv
atIndex:(unsigned int)index

Adds a new item at the location index in the menu that has the title aString, action aSelector, and key equivalent keyEquiv. Returns the new menu item. If you do not want the menu item to have a key equivalent, keyEquiv should be an empty string (@"") and not nil.


isAttached

- (BOOL)isAttached

Returns YES if the receiver is currently attached to another menu, NO otherwise. This method always returns NO on Microsoft Windows.


isTornOff

- (BOOL)isTornOff

Returns NO if the receiver is off-screen or attached to another menu (or if it's the main menu), YES otherwise. This method always returns NO on Microsoft Windows.


itemArray

- (NSArray *)itemArray

Returns the receiver's menu items.

See also: - numberOfItems


itemAtIndex:

- (id <NSMenuItem>)itemAtIndex:(int)index

Returns the menu item at location index of the receiver. It raises an exception if index is out of bounds.


itemChanged:

- (void)itemChanged:(id <NSMenuItem>)anObject

Invoked when menu item anObject is modified (for example, its title changes). The default implementation informs the "menu representation" object and causes the menu to update itself.


itemWithTag:

- (id <NSMenuItem>)itemWithTag:(int)aTag

Returns the first menu item in the receiver that has aTag as its tag.


itemWithTitle:

- (id <NSMenuItem>)itemWithTitle:(NSString *)aString

Returns the first menu item in the receiver that has aString as its title.


locationForSubmenu:

- (NSPoint)locationForSubmenu:(NSMenu *)aSubmenu

On Mach, returns the screen coordinates where aSubmenu will be displayed when it's opened as a submenu of the receiver (regardless of its current location). On Microsoft Windows, the coordinates that are reutrned are not meaningful.


menuChangedMessagesEnabled

- (BOOL)menuChangedMessagesEnabled

Returns YES if messages are being sent to the application's windows upon each change to the menu, NO otherwise.

See also: - setMenuChangedMessagesEnabled:


menuRepresentation

- (id)menuRepresentation

Returns the object that implements the "look and feel" of the menu for a particular platform. For Macintosh and Mach platforms, this object is NSMenuView.

See also: - setMenuRepresentation:


numberOfItems

- (int)numberOfItems

Returns the number of menu items in the receiver, including separator items.

See also: - itemArray


performActionForItemAtIndex:

- (void)performActionForItemAtIndex:(int)index

Causes the application to send the action message of the menu item at index to it's target. If a target is not specified, the message is sent to the first responder. As a side effect, this method posts NSMenuWillSendActionNotification and NSMenuDidSendActionNotification.


performKeyEquivalent:

- (BOOL)performKeyEquivalent:(NSEvent *)theEvent

Searches for a menu item in the receiver, or on Microsoft Windows in any of its submenus as well, whose key equivalent exactly matches the character, or character sequence, of the keyboard event theEvent and whose modifier flags match the key-equivalent modifier mask in theEvent, and causes that item to send its action message.


removeItem:

- (void)removeItem:(id <NSMenuItem>)anItem

Removes anItem from the receiver.


removeItemAtIndex:

- (void)removeItemAtIndex:(int)index

Removes the menu item at location index.


setAutoenablesItems:

- (void)setAutoenablesItems:(BOOL)flag

Controls whether the receiver automatically enables and disables its menu items based on delegates implementing the NSMenuValidation informal protocol. If flag is YES, menu items are automatically enabled and disabled. If flag is NO, menu items are not automatically enabled or disabled. See the NSMenuValidation protocol specification for more information.

See also: - autoenablesItems


setMenuChangedMessagesEnabled:

- (void)setMenuChangedMessagesEnabled:(BOOL)flag

Controls whether the receiver sends messages to the application's windows upon each menu change. To avoid the "flickering" effect of many successive menu changes, invoke this method with NO as flag, make changes to the menu, and invoke the method again with YES as flag. This has the effect of batching changes and having them applied all at once.

See also: - menuChangedMessagesEnabled


setMenuRepresentation:

- (void)setMenuRepresentation:(id)menuRep

Sets the object that implements the "look and feel" of the menu for a particular platform. For Macintosh and Mach platforms, this object is NSMenuView. On any supported platform except Windows, you can set your own NSMenuView subclass as the menu representation.

See also: - menuRepresentation


setSubmenu:forItem:

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

Makes aMenu a submenu controlled by anItem, automatically setting anItem's action to submenuAction:.


setSupermenu:

- (void)setSupermenu:(NSMenu *)supermenu

Sets the receiver's supermenu (which obviously must be a submenu) to supermenu. You should never invoke this method directly, although you may override it.

See also: - supermenu


setTitle:

- (void)setTitle:(NSString *)aString

Sets the receiver's title to aString.

See also: - title


sizeToFit

- (void)sizeToFit

Resizes the receiver to exactly fit its items. On Microsoft Windows, this method has no effect.


submenuAction:

- (void)submenuAction:(id)sender

This is the action method assigned to menu items that open submenus. Never invoke this method directly.


supermenu

- (NSMenu *)supermenu

Returns the receiver's supermenu or nil if it has none.


title

- (NSString *)title

Returns the receiver's title.

See also: - setTitle:


update

- (void)update

Enables or disables the receiver's menu items based on the NSMenuValidation informal protocol and sizes the menu to fit its current menu items if necessary. See the NSMenuValidation protocol specification for more information.

NSMenuDidSendActionNotification

This notification contains a notification object and a userInfo dictionary. The notification object is the NSMenu containing the chosen menu item. The userInfo dictionary contains these keys and values:

Key Value
@"MenuItem" The menu item that was chosen.

This notification is posted just after the application invokes the action method (carried as instance data by the menu item) in the menu item's target object or, if no target is specified, in the first object in the responder chain that implements the action method.


NSMenuWillSendActionNotification

This notification contains a notification object and a userInfo dictionary. The notification object is the NSMenu containing the chosen menu item. The userInfo dictionary contains these keys and values:

Key Value
@"MenuItem" The menu item that was chosen.

This notification is posted just after the application invokes the action method (carried as instance data by the menu item) in the menu item's target object or, if no target is specified, in the first object in the responder chain that implements the action method.



[TOC] [Prev] [Next]

Copyright © 1997, Apple Computer, Inc. All rights reserved.