PATH  Documentation > Mac OS X > Application Kit Reference: Java

Table of Contents

NSMenuView


Inherits from:
NSView : NSResponder : NSObject
Package:
com.apple.yellow.application


Class Description


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.

Although NSMenuView handles the display of a menu's contents, it does not store those contents itself. Instead, NSMenuView works together with an instance of NSMenu to display the menu. The NSMenu object stores the menu instance data while the NSMenuView provides the code to draw the menu items with the appropriate interface.

NSMenuView draws the basic menu background and uses menu-item cells to draw the individual menu items. Although it is responsible for drawing the menu item, a menu-item cell still uses information calculated by its menu view to position elements of the item correctly. NSMenuView calculates the positioning information by querying each of its menu-item cells for the size of each of its elements. The menu view uses this information to determine element sizes that can accommodate all of the items in the menu.


Subclassing NSMenuView


NSMenuView should not need to be subclassed for most purposes. However, if you define a custom look for your application's menus, you may need to subclass NSMenuView to implement that appearance. For example, you could override NSMenuView to implement a grid menu or to implement a popup button whose menu is displayed horizontally. If you simply want to change the appearance of the menu's items, you should subclass NSMenuItemCell instead.

When subclassing NSMenuView, you should override the sizeToFit method to calculate the geometry of your menu. Other methods invoke sizeToFit as necessary to account for changes in the menu content, such as when items are added or removed.

NSMenuView provides access to the menu geometry through the methods stateImageOffset, stateImageWidth, imageAndTitleOffset, imageAndTitleWidth, keyEquivalentOffset, and keyEquivalentWidth. If you are using instances of NSMenuItemCell for your menu-item cells, you should override these methods to return the information required by the cell. Otherwise, you can define new methods that your custom cell knows how to use.




Method Types


Constructors
NSMenuView
Getting and setting menu view attributes
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


Constructors



NSMenuView

public NSMenuView()

Description forthcoming.

public NSMenuView(boolean flag)

Description forthcoming.


Static Methods



menuBarHeight

public static float menuBarHeight()

Description forthcoming.


Instance Methods



attachSubmenuForItemAtIndex

public void attachSubmenuForItemAtIndex(int index)

Attaches the submenu associated with the menu item at index. This method prepares the submenu for display by positioning its window and ordering it to the front.

See Also: setWindowFrameForAttachingToRect, orderFront (NSWindow)



attachedMenu

public NSMenu attachedMenu()

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

See Also: attachedMenuView, isAttached



attachedMenuView

public NSMenuView attachedMenuView()

Returns the NSMenuView of this object's attached menu view. (The attached menu view is the one associated with the currently visible submenu, if any.)

See Also: attachedMenu, detachSubmenu, isAttached



detachSubmenu

public void detachSubmenu()

Detaches the window associated with the currently visible submenu and removes any menu item highlights. 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

public NSFont font()

Returns the default font used to draw the menu text. New items use this font by default, although the item's menu-item cell can use a different font

See Also: setFont



highlightedItemIndex

public int highlightedItemIndex()

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

See Also: setHighlightedItemIndex



horizontalEdgePadding

public float horizontalEdgePadding()

Returns the amount of horizontal space used for padding menu-item components. 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

public float imageAndTitleOffset()

Returns the offset to the starting point of a menu item's image and title section. 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

public float imageAndTitleWidth()

Returns the maximum width of a menu item's image and title section. 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

public int indexOfItemAtPoint(NSPoint point)

Returns the index of the menu item underneath point or -1 if no menu item is underneath point. 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

public NSRect innerRect()

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

See Also: bounds (NSView)



isAttached

public boolean isAttached()

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

See Also: attachedMenu, attachedMenuView



isHorizontal

public boolean isHorizontal()

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

See Also: setHorizontal



isTornOff

public boolean isTornOff()

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

itemAdded

public void itemAdded(NSNotification notification)

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.

To account for the newly added menu item, this method creates a new menu-item cell for the item and marks the menu view as needing to be resized.

See Also: setNeedsSizing



itemChanged

public void itemChanged(NSNotification notification)

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.

To account for changes to a menu item, this method marks the menu view as needing to be resized.

See Also: setNeedsSizing



itemRemoved

public void itemRemoved(NSNotification notification)

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

To account for changes to a menu item, this method removes the item's menu-item cell and marks the menu view as needing to be resized

See Also: setNeedsSizing



keyEquivalentOffset

public float keyEquivalentOffset()

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

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

public float keyEquivalentWidth()

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

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

public NSPoint locationForSubmenu(NSMenu aSubMenu)

Returns the origin of the submenu view's window. 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

public NSMenu menu()

Returns the NSMenu associated with this menu view.

See Also: setMenu



menuItemCellForItemAtIndex

public NSMenuItemCell menuItemCellForItemAtIndex(int index)

Returns the menu-item cell at the specified index.

See Also: setMenuItemCellForItemAtIndex, sizeToFit



needsSizing

public boolean needsSizing()

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

See Also: setNeedsSizing



performActionWithHighlightingForItemAtIndex

public void performActionWithHighlightingForItemAtIndex(int index)

Invoked when a key equivalent is pressed, this method uses its NSMenu object to perform the action associated with the item at index. 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

public NSRect rectOfItemAtIndex(int index)

Returns the drawing rectangle of the menu item at index. 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

public void setFont(NSFont font)

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

See Also: font



setHighlightedItemIndex

public void setHighlightedItemIndex(int index)

Highlights the menu item at index. 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

public void setHorizontal(boolean flag)

Sets the orientation of the menu. If flag is true, the menu's items are displayed horizontally, otherwise the menu's items are displayed vertically.

See Also: isHorizontal



setHorizontalEdgePadding

public void setHorizontalEdgePadding(float pad)

Sets the horizontal padding for menu-item components.

See Also: horizontalEdgePadding



setMenu

public void setMenu(NSMenu menu)

Sets the menu to be displayed in this view. 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

public void setMenuItemCellForItemAtIndex( NSMenuItemCell cell, int index)

Replaces the menu-item cell at index with cell. This method does not change the contents of the menu itself; it only changes 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

public void setNeedsDisplayForItemAtIndex(int index)

This method adds the region occupied by the menu item at index to the menu view's invalid region. 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, setNeedsDisplayInRect: (NSView)



setNeedsSizing

public void setNeedsSizing(boolean flag)

Set to true when the menu contents have changed or the menu appearance has changed. 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

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

Causes the menu view to resize its window so its frame is the appropriate size to attach to screenRect. 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 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

public void sizeToFit()

Used internally by the menu view to cache information about the menu item geometry. 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

public float stateImageOffset()

Returns the offset to the space reserved for state images of this menu. 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

public float stateImageWidth()

Returns the maximum width of the state images used by this menu. 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

public boolean trackWithEvent(NSEvent event)

Handles events sent to this menu view. For mouse events, this method tracks the mouse 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

public void update()

Asks the associated NSMenu to update itself. 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)




Table of Contents