Next Page > Hide TOC

NSMenu Class Reference

Overview

This class defines an object that manages an application’s menus.

Adopted Protocols

• encodeWithCoder:

• initWithCoder:

• copyWithZone:

Tasks

Managing the Menu Bar

• + menuBarVisible
• + setMenuBarVisible:
• – menuBarHeight

Creating an NSMenu Object

• – 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
• – locationForSubmenu:
• – supermenu
• – setSupermenu:
• – isTornOff

Enabling and Disabling Menu Items

• – autoenablesItems
• – setAutoenablesItems:
• – update

Handling Keyboard Equivalents

• – performKeyEquivalent:
• – menuHasKeyEquivalent:forEvent:target:action:  delegate method

Simulating Mouse Clicks

• – performActionForItemAtIndex:

Managing the Title

• – setTitle:
• – title

Updating Menu Layout

• – menuChangedMessagesEnabled
• – setMenuChangedMessagesEnabled:
• – sizeToFit
• – menu:updateItem:atIndex:shouldCancel:  delegate method

Displaying Context-Sensitive Help

• + popUpContextMenu:withEvent:forView:
• + popUpContextMenu:withEvent:forView:withFont:
• – helpRequested:

Managing Display of the State Column

• – setShowsStateColumn:
• – showsStateColumn

Controlling Allocation Zones

• + menuZone
• + setMenuZone:

Handling Highlighting

• – highlightedItem
• – menu:willHighlightItem:  delegate method

Managing the Delegate

• – setDelegate:
• – delegate

Handling Open and Close Events

• – menuWillOpen:  delegate method
• – menuDidClose:  delegate method

Handling Tracking

• – numberOfItemsInMenu:  delegate method
• – menuNeedsUpdate:  delegate method
• – cancelTracking

Deprecated Methods

• – contextMenuRepresentation
• – setContextMenuRepresentation:
• – tearOffMenuRepresentation
• – setTearOffMenuRepresentation:
• – setMenuRepresentation:
• – menuRepresentation

Class Methods

menuBarVisible

Returns a Boolean value that indicates whether the menu bar is visible.

+ (BOOL)menuBarVisible

Return Value

YES if the menu bar is visible, otherwise NO.

Availability

• Available in Mac OS X v10.2 and later.

See Also

• + setMenuBarVisible:

Declared In

menuZone

Returns the zone from which NSMenu objects should be allocated.

+ (NSZone *)menuZone

Return Value

The zone from which NSMenu objects should be allocated.

Discussion

The zone is created if necessary.

Availability

• Available in Mac OS X v10.0 and later.

Related Sample Code

• MenuItemView
• ObjectPath

Declared In

popUpContextMenu:withEvent:forView:

Displays a contextual menu over a view for an event.

+ (void)popUpContextMenu:(NSMenu *)menu withEvent:(NSEvent *)event forView:(NSView *)view

Parameters

menu

The menu object to use for the contextual menu.

event

An NSEvent object representing the event.

view

The view object over which to display the contextual menu.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• + popUpContextMenu:withEvent:forView:withFont:

Declared In

popUpContextMenu:withEvent:forView:withFont:

Displays 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

Parameters

menu

The menu object to use for the contextual menu.

event

An NSEvent object representing the event.

view

The view object over which to display the contextual menu.

font

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.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• + popUpContextMenu:withEvent:forView:

Declared In

setMenuBarVisible:

Sets whether the menu bar is visible and selectable by the user.

+ (void)setMenuBarVisible:(BOOL)visible

Parameters

visible

YES if menu bar is to be visible, otherwise NO.

Availability

• Available in Mac OS X v10.2 and later.

See Also

• + menuBarVisible

Declared In

setMenuZone:

Sets the zone from which NSMenu objects should be allocated

+ (void)setMenuZone:(NSZone *)zone

Parameters

zone

The memory zone to set.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

Instance Methods

addItem:

Adds a menu item to the end of the receiver.

- (void)addItem:(NSMenuItem *)newItem

Parameters

newItem

The menu item (an object conforming to the NSMenuItem protocol) to add to the menu.

Discussion

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.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – addItemWithTitle:action:keyEquivalent:
• – removeItem:
• – removeItemAtIndex:

Related Sample Code

• MenuItemView
• PDFKitLinker2
• QTAudioExtractionPanel
• Quartz Composer WWDC 2005 TextEdit
• TextEditPlus

Declared In

addItemWithTitle:action:keyEquivalent:

Creates a new menu item and adds it to the end of the receiver.

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

Parameters

aString

A string to be made the title of the menu item.

aSelector

The action-message selector to assign to the menu item.

keyEquiv

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.

Return Value

The created menu item (an object conforming to the NSMenuItem protocol) or nil if the object couldn't be created.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – addItem:
• – removeItem:
• – removeItemAtIndex:

Related Sample Code

• Clock Control
• UIElementInspector

Declared In

attachedMenu

Returns the menu currently attached to the receiver.

- (NSMenu *)attachedMenu

Return Value

The menu currently attached to the receiver or nil if there’s no such object.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – isAttached

Declared In

autoenablesItems

Returns a Boolean value that indicates whether the receiver automatically enables and disables its menu items.

- (BOOL)autoenablesItems

Return Value

YES if the receiver automatically enables and disables its menu items (based on the NSMenuValidation informal protocol), otherwise NO.

Discussion

By default, NSMenu objects autoenable their menu items. See the protocol specification for more information.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setAutoenablesItems:

Declared In

cancelTracking

Dismisses the menu and ends all menu tracking.

- (void)cancelTracking

Availability

• Available in Mac OS X v10.5 and later.

Related Sample Code

• MenuItemView

Declared In

contextMenuRepresentation

Deprecated. (Deprecated. Mac OS X does not use menu representations to draw menus.)

- (id)contextMenuRepresentation

Return Value

nil.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

delegate

Returns the receiver’s delegate.

- (id)delegate

Return Value

The receiver’s delegate.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – setDelegate:

Declared In

helpRequested:

Overridden by subclasses to implement specialized context-sensitive help behavior.

- (void)helpRequested:(NSEvent *)event

Parameters

event

An NSEvent object representing the event associated with the help request.

Discussion

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.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – showContextHelpForObject:locationHint: (NSHelpManager)

Declared In

highlightedItem

Returns the highlighted item in the receiver.

- (NSMenuItem *)highlightedItem

Return Value

Returns the highlighted item in the receiver, or nil if no item in the menu is highlighted.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – menu:willHighlightItem:

Declared In

indexOfItem:

Returns the index identifying the location of a specified menu item in the receiver.

- (NSInteger)indexOfItem:(NSMenuItem *)anObject

Parameters

anObject

A menu item—that is an object conforming to the NSMenuItem protocol.

Return Value

The integer index of the menu item or, if no such menu item is in the menu, –1.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – insertItem:atIndex:
• – itemAtIndex:

Declared In

indexOfItemWithRepresentedObject:

Returns the index of the first menu item in the receiver that has a given represented object.

- (NSInteger)indexOfItemWithRepresentedObject:(id)anObject

Parameters

anObject

A represented object of the receiver.

Return Value

The integer index of the menu item or, if no such menu item is in the menu, –1.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – indexOfItemWithTag:
• – indexOfItemWithTitle:
• – insertItem:atIndex:
• – itemAtIndex:

Declared In

indexOfItemWithSubmenu:

Returns the index of the menu item in the receiver with the given submenu.

- (NSInteger)indexOfItemWithSubmenu:(NSMenu *)anObject

Parameters

anObject

A menu object that is a menu item of the receiver (that is, a submenu).

Return Value

The integer index of the menu item or, if no such menu item is in the menu, –1.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – insertItem:atIndex:
• – itemAtIndex:

Declared In

indexOfItemWithTag:

Returns the index of the first menu item in the receiver identified by a tag.

- (NSInteger)indexOfItemWithTag:(NSInteger)aTag

Parameters

aTag

An integer tag associated with the menu item of the receiver.

Return Value

The integer index of the menu item or, if no such menu item is in the menu, –1.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – itemWithTag:
• – insertItem:atIndex:
• – itemAtIndex:

Declared In

indexOfItemWithTarget:andAction:

Returns the index of the first menu item in the receiver that has a specified action and target.

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

Parameters

anObject

An object that is set as the target of a menu item of the receiver.

actionSelector

A selector identifying an action method. If actionSelector is NULL, the first menu item in the receiver that has target anObject is returned

Return Value

The integer index of the menu item or, if no such menu item is in the menu, –1.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – indexOfItemWithTag:
• – indexOfItemWithTitle:
• – indexOfItemWithRepresentedObject:
• – insertItem:atIndex:
• – itemAtIndex:

Declared In

indexOfItemWithTitle:

Returns the index of the first menu item in the receiver that has a specified title.

- (NSInteger)indexOfItemWithTitle:(NSString *)aTitle

Parameters

aTitle

The title of a menu item in the receiver.

Return Value

The integer index of the menu item or, if no such menu item is in the menu, –1.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – itemWithTitle:
• – insertItem:atIndex:
• – itemAtIndex:

Declared In

initWithTitle:

Initializes and returns a menu having the specified title and with autoenabling of menu items turned on.

- (id)initWithTitle:(NSString *)aTitle

Parameters

aTitle

The title to assign to the receiver.

Return Value

The initialized NSMenu object or nil if the object could not be initialized.

Special Considerations

This method is the designated initializer for the class.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setAutoenablesItems:

Related Sample Code

• DeskPictAppDockMenu
• MenuItemView
• SearchField

Declared In

insertItem:atIndex:

Inserts a menu item into the receiver at a specific location.

- (void)insertItem:(NSMenuItem *)newItem atIndex:(NSInteger)index

Parameters

newItem

An object conforming to the NSMenuItem protocol that represents a menu item.

index

An integer index identifying the location of the menu item in the menu.

Discussion

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.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – addItem:
• – itemAtIndex:
• – removeItem:

Related Sample Code

• SearchField

Declared In

insertItemWithTitle:action:keyEquivalent:atIndex:

Creates 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

Parameters

aString

A string to be made the title of the menu item.

aSelector

The action-message selector to assign to the menu item.

keyEquiv

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.

index

An integer index identifying the location of the menu item in the menu.

Return Value

The new menu item (an object conforming to the NSMenuItem protocol) or nil if the item could not be created

Availability

• Available in Mac OS X v10.0 and later.

Declared In

isAttached

Returns a Boolean value that indicates whether the receiver is currently attached to another menu.

- (BOOL)isAttached

Return Value

YES if the receiver is currently attached to another menu, otherwise NO.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – attachedMenu

Declared In

isTornOff

Returns a Boolean value that indicates whether the receiver is offscreen or attached to another menu (or if it’s the main menu).

- (BOOL)isTornOff

Return Value

NO if the receiver is offscreen or attached to another menu (or if it’s the main menu), otherwise YES.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

itemArray

Returns an array containing the receiver’s menu items.

- (NSArray *)itemArray

Return Value

An array containing the receiver’s menu items.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – itemWithTag:
• – itemWithTitle:
• – itemAtIndex:
• – numberOfItems

Related Sample Code

• EnhancedAudioBurn
• WhackedTV

Declared In

itemAtIndex:

Returns the menu item at a specific location of the receiver.

- (NSMenuItem *)itemAtIndex:(NSInteger)index

Parameters

index

An integer index locating a menu item in a menu.

Return Value

The found menu item (an object conforming to the NSMenuItem protocol) or nil if the object couldn't be found.

Discussion

This method raises an exception if index is out of bounds.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – indexOfItem:
• – itemWithTag:
• – itemWithTitle:
• – itemArray

Related Sample Code

• MenuItemView

Declared In

itemChanged:

Invoked when a menu item is modified visually (for example, its title changes).

- (void)itemChanged:(NSMenuItem *)anObject

Parameters

anObject

The menu item that has visually changed.

Discussion

This method is not called for changes involving the menu item's action, target, represented object, or tag. Posts an NSMenuDidChangeItemNotification.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

itemWithTag:

Returns the first menu item in the receiver with the specified tag.

- (NSMenuItem *)itemWithTag:(NSInteger)aTag

Parameters

aTag

A numeric tag associated with a menu item.

Return Value

The found menu item (an object conforming to the NSMenuItem protocol) or nil if the object couldn't be found.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – indexOfItemWithTag:
• – itemWithTitle:
• – itemAtIndex:
• – itemArray

Declared In

itemWithTitle:

Returns the first menu item in the receiver with a specified title.

- (NSMenuItem *)itemWithTitle:(NSString *)aString

Parameters

aString

The title of a menu item.

Return Value

The found menu item (an object conforming to the NSMenuItem protocol) or nil if the object couldn't be found.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – indexOfItemWithTitle:
• – itemWithTag:
• – itemAtIndex:
• – itemArray

Declared In

locationForSubmenu:

Returns the location in screen coordinates where the given submenu is displayed when opened as a submenu of the receiver.

- (NSPoint)locationForSubmenu:(NSMenu *)aSubmenu

Parameters

aSubmenu

A menu object that is a submenu of the receiver.

Return Value

An NSPoint structure describing the location or (0.0, 0.0) if the submenu does not exist in the receiver.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

menuBarHeight

Returns the menu bar height for the current application’s main menu.

- (CGFloat)menuBarHeight

Return Value

The receiver's main menu bar height or 0.0 if the receiver is some other menu.

Discussion

This method supersedes the menuBarHeight class method of the NSMenuView class.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

menuChangedMessagesEnabled

Returns a Boolean value that indicates whether messages are sent to the application’s windows upon each change to the receiver.

- (BOOL)menuChangedMessagesEnabled

Return Value

YES if messages are sent to the application’s windows upon each change to the receiver, otherwise NO.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setMenuChangedMessagesEnabled:

Declared In

menuRepresentation

Deprecated. (Deprecated. Mac OS X does not use menu representations to draw menus.)

- (id)menuRepresentation

Return Value

nil.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

numberOfItems

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

- (NSInteger)numberOfItems

Return Value

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

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – itemArray

Declared In

performActionForItemAtIndex:

Causes the application to send the action message of a specified menu item to its target.

- (void)performActionForItemAtIndex:(NSInteger)index

Parameters

index

The integer index of a menu item.

Discussion

If a target is not specified, the message is sent to the first responder. As a side effect, this method posts NSMenuWillSendActionNotification and NSMenuDidSendActionNotification.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – performKeyEquivalent:

Declared In

performKeyEquivalent:

Performs the action for the menu item that corresponds to the given key equivalent.

- (BOOL)performKeyEquivalent:(NSEvent *)theEvent

Parameters

theEvent

An NSEvent object that represents a key-equivalent event.

Return Value

YES if theEvent is a key equivalent that the receiver handled, NO if it is not a key equivalent that it should handle.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – performActionForItemAtIndex:
• – menuHasKeyEquivalent:forEvent:target:action:

Declared In

removeItem:

Removes a menu item from the receiver.

- (void)removeItem:(NSMenuItem *)anItem

Parameters

anItem

The menu item to remove.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – addItem:
• – addItemWithTitle:action:keyEquivalent:
• – removeItemAtIndex:

Declared In

removeItemAtIndex:

Removes the menu item at a specified location in the receiver.

- (void)removeItemAtIndex:(NSInteger)index

Parameters

index

An integer index identifying the menu item.

Discussion

After it removes the menu item, this method posts an NSMenuDidRemoveItemNotification.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – addItem:
• – addItemWithTitle:action:keyEquivalent:
• – removeItem:

Related Sample Code

• ObjectPath

Declared In

setAutoenablesItems:

Controls whether the receiver automatically enables and disables its menu items based on delegates implementing the NSMenuValidation informal protocol.

- (void)setAutoenablesItems:(BOOL)flag

Parameters

flag

If flag is YES, menu items are automatically enabled and disabled. If flag is NO, menu items are not automatically enabled or disabled.

Discussion

See the NSMenuValidation protocol specification for more information.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – autoenablesItems

Related Sample Code

• SearchField

Declared In

setContextMenuRepresentation:

Deprecated. (Deprecated. Mac OS X does not use menu representations to draw menus.)

- (void)setContextMenuRepresentation:(id)menuRep

Availability

• Available in Mac OS X v10.0 and later.

Declared In

setDelegate:

Sets the receiver’s delegate.

- (void)setDelegate:(id)anObject

Parameters

anObject

The object to set as delegate.

Discussion

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.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – delegate

Declared In

setMenuChangedMessagesEnabled:

Controls whether the receiver sends messages to the application’s windows upon each menu change.

- (void)setMenuChangedMessagesEnabled:(BOOL)flag

Parameters

flag

YES if the receiver should send a message at each menu change, NO otherwise.

Discussion

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.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – menuChangedMessagesEnabled

Declared In

setMenuRepresentation:

Deprecated. (Deprecated. Mac OS X does not use menu representations to draw menus.)

- (void)setMenuRepresentation:(id)menuRep

Availability

• Available in Mac OS X v10.0 and later.

Declared In

setShowsStateColumn:

Sets whether the receiver displays the state column.

- (void)setShowsStateColumn:(BOOL)showsState

Parameters

showsState

YES to display the state column, otherwise NO.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – showsStateColumn

Declared In

setSubmenu:forItem:

Assigns a menu to be a submenu of the receiver controlled by a given menu item.

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

Parameters

aMenu

A menu object that is to be a submenu of the receiver.

anItem

A menu item (that is, an object conforming to the NSMenuItem protocol) that controls aMenu. The method sets the action of anItem to submenuAction:.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

setSupermenu:

Sets the receiver’s supermenu.

- (void)setSupermenu:(NSMenu *)supermenu

Parameters

supermenu

A menu object to set as the supermenu of the receiver.

Discussion

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.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – supermenu

Declared In

setTearOffMenuRepresentation:

Deprecated. (Deprecated. Mac OS X does not use menu representations to draw menus.)

- (void)setTearOffMenuRepresentation:(id)menuRep

Availability

• Available in Mac OS X v10.0 and later.

Declared In

setTitle:

Sets the receiver’s title.

- (void)setTitle:(NSString *)aString

Parameters

aString

A string to assign as the new title of the receiver.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – title

Declared In

showsStateColumn

Returns a Boolean value that indicates whether the receiver displays the state column.

- (BOOL)showsStateColumn

Return Value

YES if the receiver displays the state column, otherwise NO.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – setShowsStateColumn:

Declared In

sizeToFit

Resizes the receiver to exactly fit its items.

- (void)sizeToFit

Availability

• Available in Mac OS X v10.0 and later.

Declared In

submenuAction:

The action method assigned to menu items that open submenus.

- (void)submenuAction:(id)sender

Discussion

You may override this method to implement different behavior. Never invoke this method directly.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

supermenu

Returns the receiver’s supermenu.

- (NSMenu *)supermenu

Return Value

The receiver’s supermenu or nil if it has none.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setSupermenu:

Declared In

tearOffMenuRepresentation

Deprecated. (Deprecated. Mac OS X does not use menu representations to draw menus.)

- (id)tearOffMenuRepresentation

Return Value

nil.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

title

Returns the receiver’s title.

- (NSString *)title

Return Value

The receiver’s title.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setTitle:

Related Sample Code

• ToolbarSample

Declared In

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.

- (void)update

Discussion

See the NSMenuValidation protocol specification for more information.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

Delegate Methods

menu:updateItem:atIndex:shouldCancel:

Called to let the delegate update a menu item before it is displayed.

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

Parameters

menu

The menu object that owns item.

item

The menu-item object that may be updated.

index

The integer index of the menu item.

shouldCancel

Set to YES if, due to some user action, the menu no longer needs to be displayed before all the menu items have been updated. You can ignore this flag, return YES, and continue; or you can save your work (to save time the next time your delegate is called) and return NO to stop the updating.

Return Value

YES to continue the process. If you return NO, your menu:updateItem:atIndex:shouldCancel: is not called again. In that case, it is your responsibility to trim any extra items from the menu.

Discussion

If your numberOfItemsInMenu: delegate method returns a positive value, then your menu:updateItem:atIndex:shouldCancel: method is called for each item in the menu. You can then update the menu title, image, and so forth for each menu item.

Availability

• Available in Mac OS X v10.3 and later.

Declared In

menu:willHighlightItem:

Called to indicates that a menu is about to highlight a given item.

- (void)menu:(NSMenu *)menu willHighlightItem:(NSMenuItem *)item

Parameters

menu

The menu object about to highlight an item.

item

The item about to be highlighted.

Discussion

Only one item per menu can be highlighted at a time. If item is nil, it means that all items in the menu are about to be unhighlighted

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – highlightedItem

Declared In

menuDidClose:

Sent after a menu closed.

- (void)menuDidClose:(NSMenu *)menu

Parameters

menu

The menu that closed.

Special Considerations

Do not modify the structure of the menu or the menu items during this method.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – menuWillOpen:

Declared In

menuHasKeyEquivalent:forEvent:target:action:

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

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

Parameters

menu

The menu object sending the delegation message.

event

An NSEvent object representing a key-down event.

target

Return by reference the target object for the menu item that corresponds to the event. Specify nil to requests the menu's target.

action

Return by reference the action selector for the menu item that corresponds to the event.

Return Value

If there is a valid and enabled menu item that corresponds to this key-down even, return YES after specifying the target and action. Return NO if there are no items with that key equivalent or if the item is disabled.

Discussion

If the delegate does not define this method, the menu is populated to find out if any items have a matching key equivalent.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – performKeyEquivalent:
• – performActionForItemAtIndex:
• – setDelegate:

Declared In

menuNeedsUpdate:

Called when a menu is about to be displayed at the start of a tracking session so the delegate can modify the menu.

- (void)menuNeedsUpdate:(NSMenu *)menu

Parameters

menu

The menu object that is about to be displayed.

Discussion

You can change the menu by adding, removing or modifying menu items. Be sure to set the proper enable state for any new menu items. If populating the menu will take a long time, implement numberOfItemsInMenu: and menu:updateItem:atIndex:shouldCancel: instead.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – setDelegate:

Declared In

menuWillOpen:

Sent when a menu is about to open.

- (void)menuWillOpen:(NSMenu *)menu

Parameters

menu

The menu that is about to open.

Special Considerations

Do not modify the structure of the menu or the menu items during this method.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – menuDidClose:

Declared In

numberOfItemsInMenu:

Called when a menu is about to be displayed at the start of a tracking session so the delegate can specify the number of items in the menu.

- (NSInteger)numberOfItemsInMenu:(NSMenu *)menu

Parameters

menu

The menu object about to be displayed.

Return Value

The number of menu items in the menu.

Discussion

If you return a positive value, the menu is resized by either removing or adding items. Newly created items are blank. After the menu is resized, your menu:updateItem:atIndex:shouldCancel: method is called for each item. If you return a negative value, the number of items is left unchanged and menu:updateItem:atIndex:shouldCancel: is not called. If you can populate the menu quickly, you can implement menuNeedsUpdate: instead of numberOfItemsInMenu: and menu:updateItem:atIndex:shouldCancel:.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – setDelegate:

Declared In

Notifications

NSMenuDidAddItemNotification

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:

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSMenuDidChangeItemNotification

Posted 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:

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSMenuDidBeginTrackingNotification

Posted 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 NSString *NSMenuDidBeginTrackingNotification;

Availability

• Available in Mac OS X v10.5 and later.

Declared In

NSMenuDidEndTrackingNotification

Posted 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.

Availability

• Available in Mac OS X v10.3 and later.

Declared In

NSMenuDidRemoveItemNotification

Posted 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:

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSMenuDidSendActionNotification

Posted 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:

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSMenuWillSendActionNotification

Posted 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:

Availability

• Available in Mac OS X v10.0 and later.

Declared In

Next Page > Hide TOC