| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/AppKit.framework |
| Availability | Available in Mac OS X v10.0 and later. |
| Companion guide | |
| Declared in | NSMenu.h |
| Related sample code |
– insertItem:atIndex:
– insertItemWithTitle:action:keyEquivalent:atIndex:
– addItem:
– addItemWithTitle:action:keyEquivalent:
– removeItem:
– removeItemAtIndex:
– itemChanged:
– removeAllItems
– indexOfItem:
– indexOfItemWithTitle:
– indexOfItemWithTag:
– indexOfItemWithTarget:andAction:
– indexOfItemWithRepresentedObject:
– indexOfItemWithSubmenu:
– setSubmenu:forItem:
– submenuAction:
– supermenu
– setSupermenu:
– isTornOff
– attachedMenu Deprecated in Mac OS X v10.2
– isAttached Deprecated in Mac OS X v10.2
– locationForSubmenu: Deprecated in Mac OS X v10.2
– minimumWidth
– setMinimumWidth:
– size
– sizeToFit Deprecated in Mac OS X v10.2
+ popUpContextMenu:withEvent:forView:
+ popUpContextMenu:withEvent:forView:withFont:
– helpRequested:
– popUpMenuPositioningItem:atLocation:inView:
+ menuZone
+ setMenuZone: Deprecated in Mac OS X v10.2
– contextMenuRepresentation Deprecated in Mac OS X v10.2
– menuRepresentation Deprecated in Mac OS X v10.2
– setContextMenuRepresentation: Deprecated in Mac OS X v10.2
– setMenuRepresentation: Deprecated in Mac OS X v10.2
– setTearOffMenuRepresentation: Deprecated in Mac OS X v10.2
– tearOffMenuRepresentation Deprecated in Mac OS X v10.2
Returns a Boolean value that indicates whether the menu bar is visible.
+ (BOOL)menuBarVisible
YES if the menu bar is visible, otherwise NO.
NSMenu.hReturns the zone from which NSMenu objects should be allocated.
+ (NSZone *)menuZone
The zone from which NSMenu objects should be allocated.
The zone is created if necessary.
NSMenu.hDisplays a contextual menu over a view for an event.
+ (void)popUpContextMenu:(NSMenu *)menu withEvent:(NSEvent *)event forView:(NSView *)view
The menu object to use for the contextual menu.
An NSEvent object representing the event.
The view object over which to display the contextual menu.
NSMenu.hDisplays a contextual menu over a view for an event using a specified font.
+ (void)popUpContextMenu:(NSMenu *)menu withEvent:(NSEvent *)event forView:(NSView *)view withFont:(NSFont *)font
The menu object to use for the contextual menu.
An NSEvent object representing the event.
The view object over which to display the contextual menu.
An NSFont object representing the font for the contextual menu. If you pass in nil for the font, the method uses the default font for menu.
Specifying a font using the font parameter is discouraged. Instead set the menu’s font using the setFont: method and pass nil for the font parameter.
NSMenu.hSets whether the menu bar is visible and selectable by the user.
+ (void)setMenuBarVisible:(BOOL)visible
YES if menu bar is to be visible, otherwise NO.
NSMenu.hAdds a menu item to the end of the receiver.
- (void)addItem:(NSMenuItem *)newItem
The menu item (an object conforming to the NSMenuItem protocol) to add to the menu.
This method invokes insertItem:atIndex:. Thus, the receiver does not accept the menu item if it already belongs to another menu. After adding the menu item, the receiver updates itself.
NSMenu.hCreates a new menu item and adds it to the end of the receiver.
- (NSMenuItem *)addItemWithTitle:(NSString *)aString action:(SEL)aSelector keyEquivalent:(NSString *)keyEquiv
A string to be made the title of the menu item.
The action-message selector to assign to the menu item.
A string identifying the key to use as a key equivalent for the menu item. If you do not want the menu item to have a key equivalent, keyEquiv should be an empty string (@"") and not nil.
The created menu item (an object conforming to the NSMenuItem protocol) or nil if the object couldn't be created.
NSMenu.hReturns whether the popup menu allows appending of contextual menu plugin items.
- (BOOL)allowsContextMenuPlugIns
YES if the popup menu allows appending of contextual menu plugin items, otherwise NO.
NSMenu.hReturns a Boolean value that indicates whether the receiver automatically enables and disables its menu items.
- (BOOL)autoenablesItems
YES if the receiver automatically enables and disables its menu items (based on the NSMenuValidation informal protocol), otherwise NO.
By default, NSMenu objects autoenable their menu items. See the protocol specification for more information.
NSMenu.hDismisses the menu and ends all menu tracking.
- (void)cancelTracking
NSMenu.hDismisses the menu and ends all menu tracking without displaying the associated animation.
- (void)cancelTrackingWithoutAnimation
NSMenu.hReturns the receiver’s delegate.
- (id < NSMenuDelegate >)delegate
The receiver’s delegate.
NSMenu.hReturns the font used to display the menu and its submenus.
- (NSFont *)font
The font object used for displaying the menu.
NSMenu.hOverridden by subclasses to implement specialized context-sensitive help behavior.
- (void)helpRequested:(NSEvent *)event
An NSEvent object representing the event associated with the help request.
Subclasses in their implementation of this method should cause the Help Manager (NSHelpManager) to display the help associated with the receiver. Never invoke this method directly.
On Mac OS X v10.6 and later this method has no effect. This method may be deprecated in a future release.
– showContextHelpForObject:locationHint: (NSHelpManager)NSMenu.hReturns the highlighted item in the receiver.
- (NSMenuItem *)highlightedItem
Returns the highlighted item in the receiver, or nil if no item in the menu is highlighted.
NSMenu.hReturns the index identifying the location of a specified menu item in the receiver.
- (NSInteger)indexOfItem:(NSMenuItem *)anObject
A menu item—that is an object conforming to the NSMenuItem protocol.
The integer index of the menu item or, if no such menu item is in the menu, –1.
NSMenu.hReturns the index of the first menu item in the receiver that has a given represented object.
- (NSInteger)indexOfItemWithRepresentedObject:(id)anObject
A represented object of the receiver.
The integer index of the menu item or, if no such menu item is in the menu, –1.
NSMenu.hReturns the index of the menu item in the receiver with the given submenu.
- (NSInteger)indexOfItemWithSubmenu:(NSMenu *)anObject
A menu object that is a menu item of the receiver (that is, a submenu).
The integer index of the menu item or, if no such menu item is in the menu, –1.
NSMenu.hReturns the index of the first menu item in the receiver identified by a tag.
- (NSInteger)indexOfItemWithTag:(NSInteger)aTag
An integer tag associated with the menu item of the receiver.
The integer index of the menu item or, if no such menu item is in the menu, –1.
NSMenu.hReturns the index of the first menu item in the receiver that has a specified action and target.
- (NSInteger)indexOfItemWithTarget:(id)anObject andAction:(SEL)actionSelector
An object that is set as the target of a menu item of the receiver.
A selector identifying an action method. If actionSelector is NULL, the first menu item in the receiver that has target anObject is returned
The integer index of the menu item or, if no such menu item is in the menu, –1.
– indexOfItemWithTag:– indexOfItemWithTitle:– indexOfItemWithRepresentedObject:– insertItem:atIndex:– itemAtIndex:NSMenu.hReturns the index of the first menu item in the receiver that has a specified title.
- (NSInteger)indexOfItemWithTitle:(NSString *)aTitle
The title of a menu item in the receiver.
The integer index of the menu item or, if no such menu item is in the menu, –1.
NSMenu.hInitializes and returns a menu having the specified title and with autoenabling of menu items turned on.
- (id)initWithTitle:(NSString *)aTitle
The title to assign to the receiver.
The initialized NSMenu object or nil if the object could not be initialized.
This method is the designated initializer for the class.
NSMenu.hInserts a menu item into the receiver at a specific location.
- (void)insertItem:(NSMenuItem *)newItem atIndex:(NSInteger)index
An object conforming to the NSMenuItem protocol that represents a menu item.
An integer index identifying the location of the menu item in the menu.
This method posts an NSMenuDidAddItemNotification, allowing interested observers to update as appropriate. This method is a primitive method. All item-addition methods end up calling this method, so this is where you should implement custom behavior on adding new items to a menu in a custom subclass. If the menu item already exists in another menu, it is not inserted and the method raises an exception of type NSInternalInconsistencyException.
NSMenu.hCreates and adds a menu item at a specified location in the receiver.
- (NSMenuItem *)insertItemWithTitle:(NSString *)aString action:(SEL)aSelector keyEquivalent:(NSString *)keyEquiv atIndex:(NSInteger)index
A string to be made the title of the menu item.
The action-message selector to assign to the menu item.
A string identifying the key to use as a key equivalent for the menu item. If you do not want the menu item to have a key equivalent, keyEquiv should be an empty string (@"") and not nil.
An integer index identifying the location of the menu item in the menu.
The new menu item (an object conforming to the NSMenuItem protocol) or nil if the item could not be created
NSMenu.hReturns a Boolean value that indicates whether the receiver is offscreen or attached to another menu (or if it’s the main menu).
- (BOOL)isTornOff
NO if the receiver is offscreen or attached to another menu (or if it’s the main menu), otherwise YES.
On Mac OS X v10.6 and later this method has no effect.
NSMenu.hReturns an array containing the receiver’s menu items.
- (NSArray *)itemArray
An array containing the receiver’s menu items.
NSMenu.hReturns the menu item at a specific location of the receiver.
- (NSMenuItem *)itemAtIndex:(NSInteger)index
An integer index locating a menu item in a menu.
The found menu item (an object conforming to the NSMenuItem protocol) or nil if the object couldn't be found.
This method raises an exception if index is out of bounds.
NSMenu.hInvoked when a menu item is modified visually (for example, its title changes).
- (void)itemChanged:(NSMenuItem *)anObject
The menu item that has visually changed.
This method is not called for changes involving the menu item's action, target, represented object, or tag. Posts an NSMenuDidChangeItemNotification.
NSMenu.hReturns the first menu item in the receiver with the specified tag.
- (NSMenuItem *)itemWithTag:(NSInteger)aTag
A numeric tag associated with a menu item.
The found menu item (an object conforming to the NSMenuItem protocol) or nil if the object couldn't be found.
NSMenu.hReturns the first menu item in the receiver with a specified title.
- (NSMenuItem *)itemWithTitle:(NSString *)aString
The title of a menu item.
The found menu item (an object conforming to the NSMenuItem protocol) or nil if the object couldn't be found.
NSMenu.hReturns the menu bar height for the current application’s main menu.
- (CGFloat)menuBarHeight
The receiver's main menu bar height or 0.0 if the receiver is some other menu.
This method supersedes the menuBarHeight class method of the NSMenuView class.
NSMenu.hReturns a Boolean value that indicates whether messages are sent to the application’s windows upon each change to the receiver.
- (BOOL)menuChangedMessagesEnabled
YES if messages are sent to the application’s windows upon each change to the receiver, otherwise NO.
On Mac OS X v10.6 and later this method has no effect. This method may be deprecated in a future release.
NSMenu.hReturns the minimum width of the menu.
- (CGFloat)minimumWidth
The minimum width of the menu in screen coordinates.
NSMenu.hReturns the number of menu items in the receiver, including separator items.
- (NSInteger)numberOfItems
The number of menu items in the receiver, including separator items.
NSMenu.hCauses the application to send the action message of a specified menu item to its target.
- (void)performActionForItemAtIndex:(NSInteger)index
The integer index of a menu item.
If a target is not specified, the message is sent to the first responder. As a side effect, this method posts NSMenuWillSendActionNotification and NSMenuDidSendActionNotification.
In Mac OS X v10.6 and laster the performActionForItemAtIndex: no longer triggers menu validation. This is because validation is typically done during menu tracking or key equivalent matching, so the subsequent performActionForItemAtIndex: validation was redundant. To trigger validation explicitly, use invoke the update method.
In Mac OS X v10.6 performActionForItemAtIndex:, when called, now triggers highlighting in the menu bar. It also sends out appropriate accessibility notifications indicating the item was selected.
NSMenu.hPerforms the action for the menu item that corresponds to the given key equivalent.
- (BOOL)performKeyEquivalent:(NSEvent *)theEvent
An NSEvent object that represents a key-equivalent event.
YES if theEvent is a key equivalent that the receiver handled, NO if it is not a key equivalent that it should handle.
NSMenu.hPops up the menu at the specified location.
- (BOOL)popUpMenuPositioningItem:(NSMenuItem *)item atLocation:(NSPoint)location inView:(NSView *)view
The menu item to be positioned at the specified location in the view.
The location in the view coordinate system to display the menu item.
The view to display the menu item over.
YES if menu tracking ended because an item was selected, and NO if menu tracking was cancelled for any reason.
Pops up the receiver as a popup menu. The top left corner of the specified item (if specified, item must be present in the receiver) is positioned at the specified location in the specified view, interpreted in the view's own coordinate system.
If item is nil, the menu is positioned such that the top left of the menu content frame is at the given location.
If view is nil, the location is interpreted in the screen coordinate system. This allows you to pop up a menu disconnected from any window.
NSMenu.hReturns the available properties for the menu.
- (NSMenuProperties)propertiesToUpdate
A bitwise-C or of the values in the “NSMenuProperties” that are applicable to this menu.
The propertiesToUpdate method may be called on the menu from specific callbacks to determine which properties the have been defined, and whether or not they are relevant to the changes you need to make. It is intended to allow more efficient updating of the menu in certain circumstances.
For example, if NSMenuPropertyItemImage is set, your delegate does not need to update the images of the menu items, because the images are not needed (for example, during key equivalent matching). If the NSMenuPropertyItemImage bit is 0, you can avoid updating the menu's images, which may improve performance if computing the images is expensive.
You only have to update a property if it may have changed since you last set it, even if the corresponding bit is 1. For example, if the title of a menu item never changes, you only have to set it once.
You may call this from the menu delegate methods menuNeedsUpdate:, or the menu validation methods -validateMenuItem: or validateUserInterfaceItem:. Calling this at other times will raise an exception.
If a menu property does not have a corresponding bit, you should ensure it is always set properly after the callback returns.
Calling this is optional; it is always acceptable to fully update all properties of the menu.
NSMenu.hRemoves all the menu items in the receiver.
- (void)removeAllItems
This method is more efficient than removing menu items individually.
Unlike the other remove methods, this method does not post NSMenuDidChangeItemNotification notifications.
NSMenu.hRemoves a menu item from the receiver.
- (void)removeItem:(NSMenuItem *)anItem
The menu item to remove.
NSMenu.hRemoves the menu item at a specified location in the receiver.
- (void)removeItemAtIndex:(NSInteger)index
An integer index identifying the menu item.
After it removes the menu item, this method posts an NSMenuDidRemoveItemNotification.
NSMenu.hSets whether the popup menu allows appending of contextual menu plugin items.
- (void)setAllowsContextMenuPlugIns:(BOOL)allows
YES if the popup menu should allow context menu plugin items to be appending, otherwise NO.
Contextual menu plugins are system-wide services provided by other applications. For example, a contextual menu plugin might provide an “Open URL...” service. By enabling context menu plugins your application’s contextual menu will display the appropriate items for the currently selected data type.
See Services Implementation Guide for more information on contextual menu plugins.
NSMenu.hControls whether the receiver automatically enables and disables its menu items based on delegates implementing the NSMenuValidation informal protocol.
- (void)setAutoenablesItems:(BOOL)flag
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.
NSMenu.hSets the receiver’s delegate.
- (void)setDelegate:(id < NSMenuDelegate >)anObject
The object to set as delegate.
You can use the delegate to populate a menu just before it is going to be drawn and to check for key equivalents without creating a menu item.
NSMenu.hSets the font used to display the menu and its submenus.
- (void)setFont:(NSFont *)font
The font object to use.
This font will be used to display the menu and any submenus that have not had their font set explicitly.
NSMenu.hControls whether the receiver sends messages to the application’s windows upon each menu change.
- (void)setMenuChangedMessagesEnabled:(BOOL)flag
YES if the receiver should send a message at each menu change, NO otherwise.
To avoid the “flickering” effect of many successive menu changes, invoke this method with flag set to NO, make changes to the menu, and invoke the method again with flag set to YES. This approach has the effect of batching changes and applying them all at once.
On Mac OS X v10.6 and later this method has no effect. This method may be deprecated in a future release.
NSMenu.hSet the minimum width of the menu.
- (void)setMinimumWidth:(CGFloat)width
The minimum width of the menu in screen coordinates.
The menu will not draw smaller than its minimum width, but may draw larger if it needs more space. The default value is 0.
NSMenu.hSets whether the receiver displays the state column.
- (void)setShowsStateColumn:(BOOL)showsState
YES to display the state column, otherwise NO.
NSMenu.hAssigns a menu to be a submenu of the receiver controlled by a given menu item.
- (void)setSubmenu:(NSMenu *)aMenu forItem:(NSMenuItem *)anItem
A menu object that is to be a submenu of the receiver.
A menu item (that is, an object conforming to the NSMenuItem protocol) that controls aMenu. The method sets the action of anItem to submenuAction:.
NSMenu.hSets the receiver’s supermenu.
- (void)setSupermenu:(NSMenu *)supermenu
A menu object to set as the supermenu of the receiver.
You should never invoke this method directly; it is public so subclassers can add behavior to the default implementation. Subclassers should call the superclass’s method as part of their implementation.
NSMenu.hSets the receiver’s title.
- (void)setTitle:(NSString *)aString
A string to assign as the new title of the receiver.
NSMenu.hReturns a Boolean value that indicates whether the receiver displays the state column.
- (BOOL)showsStateColumn
YES if the receiver displays the state column, otherwise NO.
NSMenu.hReturns the size of the menu.
- (NSSize)size
The size of the menu in screen coordinates.
The menu may draw at a smaller size when shown, depending on its positioning and display configuration.
NSMenu.hThe action method assigned to menu items that open submenus.
- (void)submenuAction:(id)sender
You may override this method to implement different behavior. Never invoke this method directly.
NSMenu.hReturns the receiver’s supermenu.
- (NSMenu *)supermenu
The receiver’s supermenu or nil if it has none.
NSMenu.hReturns the receiver’s title.
- (NSString *)title
The receiver’s title.
NSMenu.hEnables 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.
- (void)update
See the NSMenuValidation protocol specification for more information.
NSMenu.hThese constants are used as a bitmask for specifying a set of menu or menu item properties, used in the propertiesToUpdate.
enum {
NSMenuPropertyItemTitle = 1 << 0,
NSMenuPropertyItemAttributedTitle = 1 << 1
NSMenuPropertyItemKeyEquivalent = 1 << 2,
NSMenuPropertyItemImage = 1 << 3,
NSMenuPropertyItemEnabled = 1 << 4,
NSMenuPropertyItemAccessibilityDescription = 1 << 5
};
typedef NSUInteger NSMenuProperties;
NSMenuPropertyItemTitleThe menu item’s title.
Available in Mac OS X v10.6 and later.
Declared in NSMenu.h.
NSMenuPropertyItemAttributedTitleThe menu item’s attributed string title.
Available in Mac OS X v10.6 and later.
Declared in NSMenu.h.
NSMenuPropertyItemKeyEquivalentThe menu item’s key equivalent.
Available in Mac OS X v10.6 and later.
Declared in NSMenu.h.
NSMenuPropertyItemImageThe menu image.
Available in Mac OS X v10.6 and later.
Declared in NSMenu.h.
NSMenuPropertyItemEnabledWhether the menu item is enabled or disabled.
Available in Mac OS X v10.6 and later.
Declared in NSMenu.h.
NSMenuPropertyItemAccessibilityDescriptionThe menu item’s accessibility description.
Available in Mac OS X v10.6 and later.
Declared in NSMenu.h.
Posted after a menu item is added to the menu. The notification object is the instance of NSMenu that just added the new menu item. The userInfo dictionary contains the following information:
Key | Value |
|---|---|
| An |
NSMenu.hPosted after a menu item in the menu changes appearance. Changes include enabling/disabling, changes in state, and changes to title. The notification object is the instance of NSMenu with the menu item that changed. The userInfo dictionary contains the following information:
Key | Value |
|---|---|
| An |
NSMenu.hPosted when menu tracking begins. The notification object is the main menu bar ([NSApp mainMenu]) or the root menu of a popup button. This notification does not contain a userInfo dictionary.
extern, for example:extern NSString *NSMenuDidBeginTrackingNotification; |
NSMenu.hPosted when menu tracking ends, even if no action is sent. The notification object is the main menu bar ([NSApp mainMenu]) or the root menu of a popup button. This notification does not contain a userInfo dictionary.
NSMenu.hPosted after a menu item is removed from the menu. The notification object is the instance of NSMenu that just removed the menu item. The userInfo dictionary contains the following information:
Key | Value |
|---|---|
| An |
NSMenu.hPosted just after the application dispatches a menu item’s action method to the menu item’s target. The notification object is the instance of NSMenu containing the chosen menu item. The userInfo dictionary contains the following information:
Key | Value |
|---|---|
| The menu item that was chosen. |
NSMenu.hPosted just before the application dispatches a menu item’s action method to the menu item’s target. The notification object is the instance of NSMenu containing the chosen menu item. The userInfo dictionary contains the following information:
Key | Value |
|---|---|
| The menu item that was chosen. |
NSMenu.hLast updated: 2009-06-24
