---

NSMenuView

Overview

The NSMenuView class handles the display of menus on the user’s screen. A menu view displays its menu either horizontally or vertically and allows the user to interact with the items of that menu, either to navigate through hierarchical menus or to select a particular item.

Tasks

Constructors

• NSMenuView

Getting and Setting Menu View Attributes

• menuBarHeight
• setMenu
• menu
• setHorizontal
• isHorizontal
• setFont
• font
• setHighlightedItemIndex
• highlightedItemIndex
• setMenuItemCellForItemAtIndex
• menuItemCellForItemAtIndex
• attachedMenuView
• attachedMenu
• isAttached
• isTornOff
• horizontalEdgePadding
• setHorizontalEdgePadding

Notification Methods

• itemChanged
• itemAdded
• itemRemoved

Working with Submenus

• detachSubmenu
• attachSubmenuForItemAtIndex

Calculating Menu Geometry

• update
• setNeedsSizing
• needsSizing
• sizeToFit
• stateImageOffset
• stateImageWidth
• imageAndTitleOffset
• imageAndTitleWidth
• keyEquivalentOffset
• keyEquivalentWidth
• innerRect
• rectOfItemAtIndex
• indexOfItemAtPoint
• setNeedsDisplayForItemAtIndex
• locationForSubmenu
• setWindowFrameForAttachingToRect

Event Handling

• performActionWithHighlightingForItemAtIndex
• trackWithEvent

Static Methods

menuBarHeight

Returns the height of the menu bar.

public static float menuBarHeight()

Discussion

This method is superseded in Mac OS X v10.4 by the NSMenu menuBarHeight instance method.

Instance Methods

attachedMenu

Returns the NSMenu object associated with this object’s attached menu view.

public NSMenu attachedMenu()

Discussion

The attached menu view is the one associated with the currently visible submenu, if any.

See Also

• attachedMenuView
• isAttached

attachedMenuView

Returns the NSMenuView of this object’s attached menu view.

public NSMenuView attachedMenuView()

Discussion

The attached menu view is the one associated with the currently visible submenu, if any.

See Also

• attachedMenu
• detachSubmenu
• isAttached

attachSubmenuForItemAtIndex

Attaches the submenu associated with the menu item at index.

public void attachSubmenuForItemAtIndex(int index)

Discussion

This method prepares the submenu for display by positioning its window and ordering it to the front.

See Also

• setWindowFrameForAttachingToRect
• orderFront (NSWindow)

detachSubmenu

Detaches the window associated with the currently visible submenu and removes any menu item highlights.

public void detachSubmenu()

Discussion

If the submenu itself displays further submenus, this method detaches the windows associated with those submenus as well.

See Also

• attachSubmenuForItemAtIndex
• setHighlightedItemIndex
• orderOut (NSWindow)

font

Returns the default font used to draw the menu text.

public NSFont font()

Discussion

New items use this font by default, although the item’s menu item cell can use a different font.

See Also

• setFont

highlightedItemIndex

Returns the index of the currently highlighted menu item, or –1 if no menu item in the menu is highlighted.

public int highlightedItemIndex()

See Also

• setHighlightedItemIndex

horizontalEdgePadding

Returns the amount of horizontal space used for padding menu item components.

public float horizontalEdgePadding()

Discussion

The edge padding is added to the sides of each menu item component. This space is used to provide a visual separation between components of the menu item.

See Also

• setHorizontalEdgePadding

imageAndTitleOffset

Returns the offset to the starting point of a menu item’s image and title section.

public float imageAndTitleOffset()

Discussion

The image and title section of a menu item displays an image, a title, or possibly both as a way to identify the purpose of the menu item. The value returned by this method is used for all menu items of the menu.

If any changes have been made to the menu’s contents, this method invokes sizeToFit to update the menu view information.

See Also

• imageAndTitleWidth
• stateImageOffset
• keyEquivalentOffset

imageAndTitleWidth

Returns the maximum width of a menu item’s image and title section.

public float imageAndTitleWidth()

Discussion

The image and title section of a menu item displays an image, a title, or possibly both as a way to identify the purpose of the menu item. The value returned by this method is used for all menu items of the menu.

If any changes have been made to the menu’s contents, this method invokes sizeToFit to update the menu view information.

See Also

• imageAndTitleOffset
• stateImageWidth
• keyEquivalentWidth

indexOfItemAtPoint

Returns the index of the menu item underneath point or –1 if no menu item is underneath point.

public int indexOfItemAtPoint(NSPoint point)

Discussion

This method considers the menu borders as part of the item when calculating whether point is in the menu item rectangle. This method invokes the rectOfItemAtIndex method to obtain the basic rectangle for each menu item but may adjust that rectangle before testing.

See Also

• rectOfItemAtIndex

innerRect

Returns the drawing rectangle for the menu contents.

public NSRect innerRect()

Discussion

This rectangle is different (typically smaller) from the view bounds in that it does not include the space used to draw the menu borders.

See Also

• bounds (NSView)

isAttached

Returns true if this menu is currently attached to its parent menu.

public boolean isAttached()

See Also

• attachedMenu
• attachedMenuView

isHorizontal

Returns true if the menu is displayed horizontally; such as for a menu bar, otherwise returns false.

public boolean isHorizontal()

See Also

• setHorizontal

isTornOff

Deprecated. Tear-off menus are not supported in Mac OS X.

public boolean isTornOff()

Discussion

Returns true if this menu view’s window is disassociated from its parent menu.

itemAdded

Creates a new menu item cell for the newly created item and marks the menu view as needing to be resized.

public void itemAdded(NSNotification notification)

Discussion

This method is registered with the menu view’s associated NSMenu object for notifications of the type MenuDidAddItemNotification. The notification parameter contains the notification data.

See Also

• setNeedsSizing

itemChanged

Marks the menu view as needing to be resized so changes in size resulting from a change in the menu will be tracked.

public void itemChanged(NSNotification notification)

Discussion

This method is registered with the menu view’s associated NSMenu object for notifications of the type MenuDidChangeItemNotification. The notification parameter contains the notification data.

See Also

• setNeedsSizing

itemRemoved

Removes the removed item’s menu item cell and marks the menu view as needing to be resized.

public void itemRemoved(NSNotification notification)

Discussion

This method is registered with the menu view’s associated NSMenu object for notifications of the type MenuDidRemoveItemNotification. The notification parameter contains the notification data.

See Also

• setNeedsSizing

keyEquivalentOffset

Returns the beginning position of the menu’s key equivalent text.

public float keyEquivalentOffset()

Discussion

If any changes have been made to the menu’s contents, this method invokes sizeToFit to update the menu view information.

See Also

• keyEquivalentWidth
• stateImageOffset
• imageAndTitleOffset

keyEquivalentWidth

Returns the width of the menu’s key equivalent text.

public float keyEquivalentWidth()

Discussion

If any changes have been made to the menu’s contents, this method invokes sizeToFit to update the menu view information.

See Also

• keyEquivalentOffset
• stateImageWidth
• imageAndTitleWidth

locationForSubmenu

Returns the origin of the submenu view’s window.

public NSPoint locationForSubmenu(NSMenu aSubMenu)

Discussion

The aSubmenu parameter specifies the submenu being positioned and must belong to a menu item of this menu view. This method positions the submenu adjacent to its menu item as well as possible given the type of menu and the space constraints of the user’s screen.

If any changes have been made to the menu’s contents, this method invokes sizeToFit to update the menu view information.

See Also

• setWindowFrameForAttachingToRect
• sizeToFit

menu

Returns the NSMenu associated with this menu view.

public NSMenu menu()

See Also

• setMenu

menuItemCellForItemAtIndex

Returns the menu item cell at the specified index.

public NSMenuItemCell menuItemCellForItemAtIndex(int index)

See Also

• setMenuItemCellForItemAtIndex
• sizeToFit

needsSizing

Returns true if the menu view needs to be resized due to changes in the NSMenu.

public boolean needsSizing()

See Also

• setNeedsSizing

performActionWithHighlightingForItemAtIndex

Uses the associated NSMenu object to perform the action associated with the item at index when a key equivalent is pressed.

public void performActionWithHighlightingForItemAtIndex(int index)

Discussion

Because the menu item at index might not currently be visible, this method provides visual feedback by highlighting the nearest visible parent menu item before performing the action. After the action has been sent, this method removes the highlighting for the menu item.

See Also

• performActionForItemAtIndex (NSMenu)

rectOfItemAtIndex

Returns the drawing rectangle of the menu item at index.

public NSRect rectOfItemAtIndex(int index)

Discussion

The drawing rectangle may not be the same width or height as the actual menu and in fact is typically smaller to account for borders drawn by the menu view.

If any changes have been made to the menu’s contents, this method invokes sizeToFit to update the menu view information.

See Also

• innerRect
• needsSizing
• sizeToFit

setFont

Sets the default font to use when drawing the menu text.

public void setFont(NSFont font)

See Also

• font

setHighlightedItemIndex

Highlights the menu item at index.

public void setHighlightedItemIndex(int index)

Discussion

Specify –1 for index to remove all highlighting from the menu.

The rectangle of the menu item is marked as invalid and is redrawn the next time the event loop comes around. If another menu item was previously highlighted, that menu item is redrawn without highlights when the event loop comes around again.

See Also

• setNeedsDisplayForItemAtIndex
• highlightedItemIndex

setHorizontal

Sets the orientation of the menu.

public void setHorizontal(boolean flag)

Discussion

If flag is true, the menu’s items are displayed horizontally; otherwise the menu’s items are displayed vertically.

See Also

• isHorizontal

setHorizontalEdgePadding

Sets the horizontal padding for menu item components to pad.

public void setHorizontalEdgePadding(float pad)

See Also

• horizontalEdgePadding

setMenu

Sets the menu to be displayed in this view to menu.

public void setMenu(NSMenu menu)

Discussion

This method invokes the setNeedsSizing method to force the menu view’s layout to be recalculated before drawing.

This method adds the menu view to the new NSMenu object’s list of observers. The notifications this method establishes notify this menu view when menu items in the NSMenu object are added, removed, or changed. This method removes the menu view from its previous NSMenu object’s list of observers.

See Also

• setNeedsSizing
• itemAdded
• itemRemoved
• itemChanged

setMenuItemCellForItemAtIndex

Replaces the menu item cell at index with cell.

public void setMenuItemCellForItemAtIndex(NSMenuItemCell cell, int index)

Discussion

This method does not change the contents of the menu itself; it changes only the cell used to display the menu item at index. The old cell is released, and both the new cell and the menu view are marked as needing resizing.

See Also

• menuItemCellForItemAtIndex
• setNeedsSizing

setNeedsDisplayForItemAtIndex

Adds the region occupied by the menu item at index to the menu view’s invalid region.

public void setNeedsDisplayForItemAtIndex(int index)

Discussion

The region to be redrawn includes the space occupied by the menu borders. This invalid region is redrawn the next time the event loop comes around.

See Also

• rectOfItemAtIndex
• setNeedsDisplay (NSView)

setNeedsSizing

Sets a flag that indicates whether the layout is invalid and needs resizing. If flag is true, the menu contents have changed or the menu appearance has changed.

public void setNeedsSizing(boolean flag)

Discussion

This method is used internally; you should not need to invoke it directly unless you are implementing a subclass that can cause the layout to become invalid.

See Also

• sizeToFit

setWindowFrameForAttachingToRect

Causes the menu view to resize its window so its frame is the appropriate size to attach to screenRect within screen.

public void setWindowFrameForAttachingToRect(NSRect screenRect, NSScreen screen, int edge, int selectedItemIndex)

Discussion

If selectedItemIndex contains a value other than –1, this method attempts to position the menu such that the item at selectedItemIndex appears on top of screenRect.

The selectedItemIndex parameter specifies the amount by which the selected item’s rectangle overlaps screenRect.

If the preferred edge, edge, cannot be honored, because there is not enough room, the opposite edge is used. If the rectangle does not completely fit either edge, this method uses the edge where there is more room.

If any changes have been made to the menu’s contents, this method invokes sizeToFit to update the menu view information.

See Also

• sizeToFit

sizeToFit

Used internally by the menu view to cache information about the menu item geometry.

public void sizeToFit()

Discussion

This cache is updated as necessary when menu items are added, removed, or changed.

The geometry of each menu item is determined by asking its corresponding menu item cell. The menu item cell is obtained from the menuItemCellForItemAtIndex method.

See Also

• setNeedsSizing
• menuItemCellForItemAtIndex

stateImageOffset

Returns the offset to the space reserved for state images of this menu.

public float stateImageOffset()

Discussion

The offset is used for all menu items of the menu.

If any changes have been made to the menu’s contents, this method invokes sizeToFit to update the menu view information.

See Also

• horizontalEdgePadding
• setHorizontalEdgePadding
• sizeToFit

stateImageWidth

Returns the maximum width of the state images used by this menu.

public float stateImageWidth()

Discussion

The width is used for all menu items of the menu.

If any changes have been made to the menu’s contents, this method invokes sizeToFit to update the menu view information.

See Also

• sizeToFit

trackWithEvent

Handles events sent to this menu view.

public boolean trackWithEvent(NSEvent event)

Discussion

If event is a mouse event, this method tracks the cursor position in the menu and displays the menus as appropriate. This method also handles mouse clicks that result in the selection of a menu item, in which case the menu item’s action is performed.

You should not need to use this method directly.

update

Asks the associated NSMenu to update itself.

public void update()

Discussion

If any changes have been made to the menu’s contents, this method invokes sizeToFit to update the menu view’s layout.

See Also

• sizeToFit
• setNeedsSizing
• update (NSMenu)

---