Inherits from: NSObject
Conforms to: NSCoding
NSCopying
NSObject (NSObject)
Declared in: AppKit/NSMenu.h
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.
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.
- 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:
+ (NSZone *)menuZone
+ (void)setMenuZone:(NSZone
*)zone
- (void)addItem:(id
<NSMenuItem>)newItem
- (id <NSMenuItem>)addItemWithTitle:(NSString
*)aString
action:(SEL)aSelector
keyEquivalent:(NSString
*)keyEquiv
nil
.- (NSMenu *)attachedMenu
nil
if
there's no such object.- (BOOL)autoenablesItems
See Also: - setAutoenablesItems:
- (id)contextMenuRepresentation
- (void)helpRequested:(NSEvent
*)event
See Also: - showContextHelpForObject:locationHint: (NSHelpManager)
- (int)indexOfItem:(id
<NSMenuItem>)anObject
See Also: - insertItem:atIndex:, - itemAtIndex:
- (int)indexOfItemWithRepresentedObject:(id)anObject
See Also: - insertItem:atIndex:, - itemAtIndex:
- (int)indexOfItemWithSubmenu:(NSMenu
*)anObject
See Also: - insertItem:atIndex:, - itemAtIndex:
- (int)indexOfItemWithTag:(int)aTag
See Also: - insertItem:atIndex:, - itemAtIndex:
- (int)indexOfItemWithTarget:(id)anObject andAction:(SEL)actionSelector
nil
,
the first menu item in the receiver that has target anObject is
returned. If no menu item matching these criteria is in the menu,
the method returns -1.See Also: - insertItem:atIndex:, - itemAtIndex:
- (int)indexOfItemWithTitle:(NSString
*)aTitle
See Also: - insertItem:atIndex:, - itemAtIndex:
- (id)initWithTitle:(NSString
*)aTitle
See Also: - setAutoenablesItems:
- (void)insertItem:(id
<NSMenuItem>)newItem atIndex:(int)index
See Also: - addItem:, - itemAtIndex:, - removeItem:
- (id <NSMenuItem>)insertItemWithTitle:(NSString
*)aString
action:(SEL)aSelector
keyEquivalent:(NSString
*)keyEquiv
atIndex:(unsigned int)index
nil
.- (BOOL)isAttached
YES
if
the receiver is currently attached to another menu, NO otherwise. This
method always returns NO
on Microsoft
Windows.- (BOOL)isTornOff
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.- (NSArray *)itemArray
See Also: - numberOfItems
- (id <NSMenuItem>)itemAtIndex:(int)index
- (void)itemChanged:(id
<NSMenuItem>)anObject
- (id <NSMenuItem>)itemWithTag:(int)aTag
- (id <NSMenuItem>)itemWithTitle:(NSString
*)aString
- (NSPoint)locationForSubmenu:(NSMenu
*)aSubmenu
- (BOOL)menuChangedMessagesEnabled
YES
if
messages are being sent to the application's windows upon each change
to the menu, NO
otherwise.See Also: - setMenuChangedMessagesEnabled:
- (id)menuRepresentation
See Also: - setMenuRepresentation:
- (int)numberOfItems
See Also: - itemArray
- (void)performActionForItemAtIndex:(int)index
- (BOOL)performKeyEquivalent:(NSEvent
*)theEvent
- (void)removeItem:(id
<NSMenuItem>)anItem
- (void)removeItemAtIndex:(int)index
- (void)setAutoenablesItems:(BOOL)flag
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
- (void)setContextMenuRepresentation:(id)menuRep
- (void)setMenuChangedMessagesEnabled:(BOOL)flag
NO
, make
changes to the menu, and invoke the method again with YES
.
This has the effect of batching changes and applying them all at
once.See Also: - menuChangedMessagesEnabled
- (void)setMenuRepresentation:(id)menuRep
See Also: - menuRepresentation
- (void)setSubmenu:(NSMenu
*)aMenu forItem:(id <NSMenuItem>) anItem
- (void)setSupermenu:(NSMenu
*)supermenu
See Also: - supermenu
- (void)setTearOffMenuRepresentation:(id)menuRep
- (void)setTitle:(NSString
*)aString
See Also: - title
- (void)sizeToFit
- (void)submenuAction:(id)sender
- (NSMenu *)supermenu
nil
if it has none.- (id)tearOffMenuRepresentation
- (NSString *)title
See Also: - setTitle:
- (void)update
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.
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.