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 null . 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
- 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
- resizeWindowWithMaxHeight:
- setWindowFrameForAttachingToRect
- Event handling
- performActionWithHighlightingForItemAtIndex
- trackWithEvent
Constructors
NSMenuView
public NSMenuView(boolean flag)
<<Documentation Forthcoming>>
Static
Methods
public static float menuBarHeight()
<<Documentation Forthcoming>>
Instance Methods
public NSMenu attachedMenu()
Returns the NSMenu object associated
with this object's attached menu view.See
Also: attachedMenuView, isAttached
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
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)
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)
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
fontSee Also: setFont:
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
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
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
public 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
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
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)
public boolean isAttached()
Returns true
if
this menu is currently attached to its parent menu.See
Also: attachedMenu, attachedMenuView
public boolean isHorizontal()
Returns true
if
the menu is displayed horizontally, such as for a menu bar, otherwise
returns false
.See
Also: setHorizontal
public boolean isTornOff()
Returns true
if
this menu view's window is disassociated from its parent menu.
public 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:
public 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
public 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
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
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
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">- setWindowFrameForAttachingToRect, sizeToFit
public NSMenu menu()
Returns the NSMenu associated
with this menu view.See
Also: setMenu
public NSMenuItemCell menuItemCellForItemAtIndex(int index)
Returns the menu-item cell
at the specified index. See
Also: setMenuItemCellForItemAtIndex, sizeToFit
public boolean needsSizing()
Returns true
if
the menu view needs to be resized due to changes in the NSMenu. See
Also: setNeedsSizing
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)
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
public void setFont(NSFont font)
Sets the default font to use
when drawing the menu text.See
Also: font
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
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
public void setHorizontalEdgePadding(float pad)
Sets the horizontal padding
for menu-item components.See
Also: horizontalEdgePadding
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
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
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)
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
public void setWindowFrameForAttachingToRect(NSRect screenRect, NSScreen screen, int edge, intselectedItemIndex)
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
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
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
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
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.
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)
[Previous] [Next]