---

NSMenu

Overview

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

Tasks

Constructors

• NSMenu

Managing Delegates

• setDelegate
• delegate

Managing the Menu Bar

• menuBarVisible
• setMenuBarVisible
• menuBarHeight

Setting Up Menu Commands

• insertItemAtIndex
• addItem
• removeItem
• removeItemAtIndex
• itemChanged

Finding Menu Items

• itemWithTag
• itemWithTitle
• itemAtIndex
• numberOfItems
• itemArray

Finding Indices of Menu Items

• indexOfItem
• indexOfItemWithTitle
• indexOfItemWithTag
• indexOfItemWithTargetAndAction
• indexOfItemWithRepresentedObject
• indexOfItemWithSubmenu

Managing Submenus

• setSubmenuForItem
• 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

• popUpContextMenu
• helpRequested

Deprecated Methods

• contextMenuRepresentation
• setContextMenuRepresentation
• tearOffMenuRepresentation
• setTearOffMenuRepresentation

Populating a menu

• menuUpdateItemAtIndex  delegate method
• menuNeedsUpdate  delegate method
• numberOfItemsInMenu  delegate method

Handling key equivalents

• menuHasKeyEquivalent  delegate method
• menuKeyEquivalentAction  delegate method
• menuKeyEquivalentTarget  delegate method

Static Methods

menuBarVisible

Returns true if the menu bar is visible, false otherwise.

public static boolean menuBarVisible()

Availability

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

See Also

• "setMenuBarVisible"

popUpContextMenu

Displays menu as a context menu over view for event.

public static void popUpContextMenu(NSMenu menu, NSEvent event, NSView view)

Displays menu as a context menu over view for event using font.

public static void popUpContextMenu(NSMenu menu, NSEvent event, NSView view, NSFont font)

Discussion

If you pass in null for the font, the method uses the default font for menu.

Availability

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

setMenuBarVisible

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

public static void setMenuBarVisible(boolean visible)

Availability

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

See Also

• "menuBarVisible"

Instance Methods

addItem

Adds the menu item newItem to the end of the receiver.

public void addItem(NSMenuItem newItem)

Discussion

The receiver does not accept the menu item if it already belongs to another menu. After adding the menu item, the receiver updates itself.

Adds a new item with title aString, action aSelector, and key equivalent keyEquiv to the end of the receiver.

public NSMenuItem addItem(String aString, NSSelector aSelector, String keyEquiv)

Discussion

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

attachedMenu

Returns the menu currently attached to the receiver or null if there’s no such object.

public NSMenu attachedMenu()

autoenablesItems

Returns whether the receiver automatically enables and disables its menu items based on the “NSMenu.MenuValidation” interface.

public boolean autoenablesItems()

Discussion

By default NSMenus do autoenable their menu items. See the interface specification for more information.

See Also

• setAutoenablesItems

contextMenuRepresentation

Deprecated. Returns null.

public Object contextMenuRepresentation()

delegate

Returns the receiver’s delegate.

public Object delegate()

Availability

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

See Also

• setDelegate

helpRequested

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

public void helpRequested(NSEvent event)

Discussion

Never invoke this method directly.

See Also

• showContextHelpForObject (NSHelpManager)

indexOfItem

Returns the index identifying the location of menu item anObject in the receiver.

public int indexOfItem(NSMenuItem anObject)

Discussion

If no such menu item is in the menu, returns –1.

See Also

• insertItemAtIndex
• itemAtIndex

indexOfItemWithRepresentedObject

Returns the index of the first menu item in the receiver that has anObject as its represented object.

public int indexOfItemWithRepresentedObject(Object anObject)

Discussion

If no such menu item is in the menu, returns –1.

See Also

• insertItemAtIndex
• itemAtIndex

indexOfItemWithSubmenu

Returns the index of the menu item in the receiver that has submenu anObject.

public int indexOfItemWithSubmenu(NSMenu anObject)

Discussion

If no such menu item is in the menu, returns –1.

See Also

• insertItemAtIndex
• itemAtIndex

indexOfItemWithTag

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

public int indexOfItemWithTag(int aTag)

Discussion

If no such menu item is in the menu, returns –1.

See Also

• insertItemAtIndex
• itemAtIndex

indexOfItemWithTargetAndAction

Returns the index of the first menu item in the receiver that has target anObject and action actionSelector.

public int indexOfItemWithTargetAndAction(Object anObject, NSSelector actionSelector)

Discussion

If actionSelector is NULL, the first menu item in the receiver that has target anObject is returned. If no menu item matching these criteria is in the menu, returns –1.

See Also

• insertItemAtIndex
• itemAtIndex

indexOfItemWithTitle

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

public int indexOfItemWithTitle(String aTitle)

Discussion

If no such menu item is in the menu, returns –1.

See Also

• insertItemAtIndex
• itemAtIndex

insertItemAtIndex

Inserts the menu item newItem in the receiver at location index.

public void insertItemAtIndex(NSMenuItem newItem, int index)

Discussion

If the menu item already exists in another menu, it is not inserted. This method posts an MenuDidAddItemNotification, allowing interested observers to update as appropriate. It also causes the menu to update itself. 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.

Adds a new item at location index in the receiver with title aString, action aSelector, and key equivalent keyEquiv.

public NSMenuItem insertItemAtIndex(String aString, NSSelector aSelector, String keyEquiv, int index)

Discussion

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

See Also

• addItem
• itemAtIndex
• removeItem

isAttached

Returns true if the receiver is currently attached to another menu, false otherwise.

public boolean isAttached()

isTornOff

Returns false if the receiver is offscreen or attached to another menu (or if it’s the main menu), true otherwise.

public boolean isTornOff()

itemArray

Returns the receiver’s menu items.

public NSArray itemArray()

See Also

• numberOfItems

itemAtIndex

Returns the menu item at location index of the receiver.

public NSMenuItem itemAtIndex(int index)

Discussion

It throws an exception if index is out of bounds.

itemChanged

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

public void itemChanged(NSMenuItem anObject)

Discussion

It is not called for action, target, represented object, or tag changes. Posts a MenuDidChangeItemNotification.

itemWithTag

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

public NSMenuItem itemWithTag(int aTag)

itemWithTitle

Returns the first menu item in the receiver with title aString.

public NSMenuItem itemWithTitle(String aString)

locationForSubmenu

public NSPoint locationForSubmenu(NSMenu aSubmenu)

Discussion

Returns the screen coordinates where aSubmenu will be displayed when opened as a submenu of the receiver.

menuBarHeight

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

public float menuBarHeight()

Discussion

Returns 0.0 if the receiver is some other menu. This method supersedes the "menuBarHeight" class method of the NSMenuView class.

Availability

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

menuChangedMessagesEnabled

Returns true if messages are being sent to the application’s windows upon each change to the receiver, false otherwise.

public boolean menuChangedMessagesEnabled()

See Also

• setMenuChangedMessagesEnabled

menuRepresentation

Deprecated. Returns null.

public Object menuRepresentation()

See Also

• setMenuRepresentation

numberOfItems

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

public int numberOfItems()

See Also

• itemArray

performActionForItemAtIndex

Causes the application to send the action message of the menu item at index to its target.

public void performActionForItemAtIndex(int index)

Discussion

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

performKeyEquivalent

public boolean performKeyEquivalent(NSEvent theEvent)

Discussion

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

removeItem

Removes anItem from the receiver.

public void removeItem(NSMenuItem anItem)

removeItemAtIndex

Removes the menu item at location index.

public void removeItemAtIndex(int index)

Discussion

Posts a MenuDidRemoveItemNotification.

setAutoenablesItems

Controls whether the receiver automatically enables and disables its menu items based on delegates implementing the NSMenu.MenuValidation interface.

public void setAutoenablesItems(boolean flag)

Discussion

If flag is true, menu items are automatically enabled and disabled. If flag is false, menu items are not automatically enabled or disabled. See the “NSMenu.MenuValidation” interface specification for more information.

See Also

• autoenablesItems

setContextMenuRepresentation

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

public void setContextMenuRepresentation(Object menuRep)

setDelegate

Sets the receiver’s delegate.

public void setDelegate(Object anObject)

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

setMenuChangedMessagesEnabled

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

public void setMenuChangedMessagesEnabled(boolean flag)

Discussion

To avoid the “flickering” effect of many successive menu changes, invoke this method with flag set to false, make changes to the menu, and invoke the method again with flag set to true. This approach has the effect of batching changes and applying them all at once.

See Also

• menuChangedMessagesEnabled

setMenuRepresentation

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

public void setMenuRepresentation(Object menuRep)

See Also

• menuRepresentation

setSubmenuForItem

Makes aMenu a submenu controlled by anItem, automatically setting the action of anItem to submenuAction.

public void setSubmenuForItem(NSMenu aMenu, NSMenuItem anItem)

setSupermenu

Sets the receiver’s supermenu to supermenu.

public void setSupermenu(NSMenu supermenu)

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.

See Also

• supermenu

setTearOffMenuRepresentation

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

public void setTearOffMenuRepresentation(Object menuRep)

setTitle

Sets the receiver’s title to aString.

public void setTitle(String aString)

See Also

• title

sizeToFit

Resizes the receiver to exactly fit its items.

public void sizeToFit()

submenuAction

This method is the action method assigned to menu items that open submenus.

public void submenuAction(Object sender)

Discussion

Never invoke this method directly.

supermenu

Returns the receiver’s supermenu or null if it has none.

public NSMenu supermenu()

tearOffMenuRepresentation

Deprecated. Returns null

public Object tearOffMenuRepresentation()

Discussion

.

title

Returns the receiver’s title.

public String title()

See Also

• setTitle

update

Enables or disables the receiver’s menu items based on the NSMenu.MenuValidation interface and sizes the menu to fit its current menu items if necessary.

public void update()

Discussion

See the “NSMenu.MenuValidation” interface specification for more information.

Delegate Methods

menuHasKeyEquivalent

Called to allow the delegate to return the key down event has a key equivalent.

public abstract boolean menuHasKeyEquivalent(NSMenu menu, NSEvent event)

Discussion

If there is a valid and enabled menu item that corresponds to this key down even, return true. Return false if there are no items with that key equivalent or if the item is disabled. 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

• menuKeyEquivalentTarget
• menuKeyEquivalentAction

menuKeyEquivalentAction

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

public abstract NSSelector menuKeyEquivalentAction(NSMenu menu, NSEvent event)

Discussion

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

Availability

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

See Also

• menuHasKeyEquivalent
• menuKeyEquivalentTarget

menuKeyEquivalentTarget

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

public abstract Object menuKeyEquivalentTarget(NSMenu menu, NSEvent event)

Discussion

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

Availability

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

See Also

• menuHasKeyEquivalent
• menuKeyEquivalentAction

menuNeedsUpdate

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

public abstract void menuNeedsUpdate(NSMenu menu)

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 menuUpdateItemAtIndex instead.

Availability

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

See Also

• setDelegate

menuUpdateItemAtIndex

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

public abstract boolean menuUpdateItemAtIndex(NSMenu menu, NSMenuItem item, int index, boolean shouldCancel)

Discussion

If your numberOfItemsInMenu delegate method returns a positive value, then your menuUpdateItemAtIndex method is called for each item in the menu. You can then update the menu title, image, and so forth for the menu item. Return true to continue the process. If you return false, your menuUpdateItemAtIndex is not called again. In that case, it is your responsibility to trim any extra items from the menu.

The shouldCancel parameter is set to true when your delegate is called 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 true, and continue; or you can save your work (to save time the next time your delegate is called) and return false to stop the updating.

Availability

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

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.

public abstract int numberOfItemsInMenu(NSMenu 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 menuUpdateItemAtIndex method is called for each item. If you return a negative value, the number of items is left unchanged and menuUpdateItemAtIndex is not called. If you can populate the menu quickly, you can implement menuNeedsUpdate instead of numberOfItemsInMenu and menuUpdateItemAtIndex.

Availability

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

See Also

• setDelegate

Notifications

MenuDidAddItemNotification

Posted after a menu item is added to the menu. The notification object is the NSMenu that just added the new menu item. The userInfo dictionary contains the following information:

MenuDidChangeItemNotification

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 NSMenu with the menu item that changed. The userInfo dictionary contains the following information:

MenuDidEndTrackingNotification

Posted when menu tracking ends, even if no action is sent. The notification object is the main menu bar (NSApplication.sharedApplication().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.

MenuDidRemoveItemNotification

Posted after a menu item is removed from the menu. The notification object is the NSMenu that just removed the menu item. The userInfo dictionary contains the following information:

MenuDidSendActionNotification

Posted just after the application dispatches a menu item’s action method to the menu item’s target. The notification object is the NSMenu containing the chosen menu item. The userInfo dictionary contains the following information:

MenuWillSendActionNotification

Posted just before the application dispatches a menu item’s action method to the menu item’s target. The notification object is the NSMenu containing the chosen menu item. The userInfo dictionary contains the following information:

---