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 on the appropriate platform 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
accomodate all of the items in the menu.
NSMenuView is used to
display normal menus on all platforms except Windows. On Windows,
if your application tries to get the representation of its NSMenu
object by invoking its menuRepresentation method,
the method will return nil . However,
popup buttons do still use the NSMenuView as their menu representation,
even on Windows. If your application invokes menuRepresentation on
an NSMenu object belonging to an instance of NSPopupButton, the
method will return an appropriate menu view. |
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
- Getting and setting menu
view attributes
- - setMenu:
- - menu
- - setHorizontal:
- - isHorizontal
- - setFont:
- - font
- - setHighlightedItemIndex:
- - highlightedItemIndex
- - setMenuItemCell:forItemAtIndex:
- - 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:
- - resizeWindowWithMaxHeight:
- - setWindowFrameForAttachingToRect:onScreen:preferredEdge:popUpSelectedItem:
- Event handling
- - performActionWithHighlightingForItemAtIndex:
- - trackWithEvent:
Class
Methods
+ (float)menuBarHeight
<<Documentation Forthcoming>>
Instance Methods
- (NSMenu *)attachedMenu
Returns the NSMenu object associated
with this object's attached menu view.See
Also: - attachedMenuView, - isAttached
- (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
- (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:onScreen:preferredEdge:popUpSelectedItem:, - orderFront: (NSWindow)
- (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)
- (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
fontSee Also: - setFont:
- (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:
- (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:
- (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
- (float)imageAndTitleWidth
Returns the maximum wdth 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
- (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:
- (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)
- (BOOL)isAttached
Returns YES
if
this menu is currently attached to its parent menu.See
Also: - attachedMenu, - attachedMenuView
- (BOOL
)isHorizontal
Returns YES
if
the menu is displayed horizontally, such as for a menu bar, otherwise
returns NO
.See
Also: - setHorizontal:
- (BOOL)isTornOff
Returns YES
if
this menu view's window is disassociated from its parent menu.
- (void)itemAdded:(NSNotification
*)notification
This method is registered with
the menu-view's associated NSMenu object for notifications of
the type NSMenuDidAddItemNotification. 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:
- (void)itemChanged:(NSNotification
*)notification
This method is registered with
the menu-view's associated NSMenu object for notifications of
the type NSMenuDidChangeItemNotification. 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:
- (void)itemRemoved:(NSNotification
*)notification
This method is registered with
the menu-view's associated NSMenu object for notifications of
the type NSMenuDidRemoveItemNotification. 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:
- (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
- (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
- (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:onScreen:preferredEdge:popUpSelectedItem:">- setWindowFrameForAttachingToRect:onScreen:preferredEdge:popUpSelectedItem:, - sizeToFit
- (NSMenu *)menu
Returns the NSMenu associated
with this menu view.See
Also: - setMenu:
- (NSMenuItemCell *)menuItemCellForItemAtIndex:(int)index
Returns the menu-item cell
at the specified index. See
Also: - setMenuItemCell:forItemAtIndex:, - sizeToFit
- (BOOL)needsSizing
Returns YES
if
the menu view needs to be resized due to changes in the NSMenu. See
Also: - setNeedsSizing:
- (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)
- (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
- (void)resizeWindowWithMaxHeight:(float)maxHeight
Resizes the menu view's window
so that its maximum height is no greater than maxHeight. If
the menu is a horizontal menu, this method does not attempt to limit
the width of the menu. This method is used by the setWindowFrameForAttachingToRect:onScreen:preferredEdge:popUpSelectedItem: method
to fit the menu on the user's screen. If the menu's window is smaller
than the menu, the menu will scroll to display hidden items.
See
Also: - setWindowFrameForAttachingToRect:onScreen:preferredEdge:popUpSelectedItem:
- (void)setFont:(NSFont
*)font
Sets the default font to use
when drawing the menu text.See
Also: - font
- (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
- (void)setHorizontal:(BOOL)flag
Sets the orientation of the
menu. If flag is YES
,
the menu's items are displayed horizontally, otherwise the menu's
items are displayed vertically.See Also: - isHorizontal
- (void)setHorizontalEdgePadding:(float)pad
Sets the horizontal padding
for menu-item components.See
Also: - horizontalEdgePadding
- (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:
- (void)setMenuItemCell:(NSMenuItemCell
*)cell forItemAtIndex:(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:
- (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)
- (void)setNeedsSizing:(BOOL)flag
Set to YES
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
- (void)setWindowFrameForAttachingToRect:(NSRect)screenRect
onScreen:(NSScreen *)screen
preferredEdge:(NSRectEdge)edge
popUpSelectedItem:(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
- (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:
- (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
- (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
- (BOOL)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.
- (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)
[Previous] [Next]