Inherits From:
NSButtonCell : NSActionCell : NSCell : NSObject
Conforms To:
NSCoding (from NSCell)
NSCopying (from NSCell)
NSObject (from NSObject)
Declared In:
AppKit/NSMenuItemCell.h
An NSMenuItemCell uses an instance of NSMenuItem to coordinate the display of the menu item. The NSMenuItem object contains the menu item state information, key equivalent information, and the text or image (or both) to be displayed by the menu item. The methods of NSMenuItemCell use this information to calculate the width and height of each component of the menu item.
Menu-item cells have methods for returning two different sets of measurements. The first set of measurements returns the actual widths of the menu item's individual components (as stored in the cell's NSMenuItem object). These methods include imageWidth
, titleWidth
, keyEquivalentWidth
, and stateImageWidth
.
The second set of measurements returns the rectangle for menu-item components based on the encompassing menu view. Because NSMenuView calculates the size of the menu using the largest menu-item components, each component is typically smaller than the space allotted to it. The methods imageRectForBounds:
, keyEquivalentRectForBounds:
, stateImageRectForBounds:
, and titleRectForBounds:
return the rectangle for each component, taking into account the NSMenuView adjustments. These adjusted rectangles allow the menu-item components to line up within the menu, forming coherent columns.
calcSize
NSMenuItemCell uses this method internally to calculate the minimum required width and height of the cell's menu item. The calculated values are cached for future use. This method also calculates the sizes of individual components of the cell's menu item and caches those values.
Typically this method is invoked only when necessary. You should not need to invoke it directly.
See also:
- needsSizing
drawBorderAndBackgroundWithFrame:
(NSRect)cellFrame inView:
(NSView *)controlView
Draws the borders and background associated with the cell's menu item (if any). The cell invokes this method before invoking the methods to draw the other menu-item components.
See also:
- drawWithFrame:inView:
(NSCell)
drawImageWithFrame:
(NSRect)cellFrame inView:
(NSView *)controlView
Draws the image associated with the menu item. This method invokes imageRectForBounds:
, passing it cellFrame, to calculate the rectangle in which to draw the image. The controlView parameter specifies the view that contains this cell.
Typically this method is invoked by the cell's drawWithFrame:
method. You should not need to invoke it directly. Subclasses may override this method to control the drawing of the image.
drawKeyEquivalentWithFrame:
(NSRect)cellFrame inView:
(NSView *)controlView
Draws the key equivalent associated with the menu item. This method invokes keyEquivalentRectForBounds:
, passing it cellFrame, to calculate the rectangle in which to draw the key equivalent. The controlView parameter specifies the view that contains this cell.
Typically this method is invoked by the cell's drawWithFrame:
method. You should not need to invoke it directly. Subclasses may override this method to control the drawing of the key equivalent.
drawSeparatorItemWithFrame:
(NSRect)cellFrame inView:
(NSView *)controlView
Draws a menu-item separator. This method uses the cellFrame parameter to calculate the rectangle in which to draw the menu-item separator. This method uses the controlView to determine whether the separator item should be drawn normally or should be flipped.
You should not need to invoke this method directly. Subclasses may override this method to control the drawing of the separator.
See also:
- drawKeyEquivalentWithFrame:inView:
, - drawTitleWithFrame:inView:
, - isFlipped
(NSView)
drawStateImageWithFrame:
(NSRect)cellFrame inView:
(NSView *)controlView
Draws the state image associated with the menu item. This method invokes stateImageRectForBounds:
, passing it cellFrame, to calculate the rectangle in which to draw the state image. The controlView parameter specifies the view that contains this cell.
Typically this method is invoked by the cell's drawWithFrame:
method. You should not need to invoke it directly. Subclasses may override this method to control the drawing of the state image.
drawTitleWithFrame:
(NSRect)cellFrame inView:
(NSView *)controlView
Draws the title associated with the menu item. This method invokes titleRectForBounds:
, passing it cellFrame, to calculate the rectangle in which to draw the menu-item text. The controlView parameter specifies the view that contains this cell.
Typically this method is invoked by the cell's drawWithFrame:
method. You should not need to invoke it directly. Subclasses may override this method to control the drawing of the title.
imageRectForBounds:
(NSRect)cellFrame
Returns the rectangle into which the menu item's image should be drawn. The returned rectangle is based on cellFrame but encompasses only the area to be occupied by the image. To obtain the overall drawing rectangle for the menu item, you can invoke the drawingRectForBounds:
method.
See also:
- stateImageRectForBounds:
, - imageRectForBounds:
, - titleRectForBounds:
,
- keyEquivalentRectForBounds:
imageWidth
Returns the width of the image associated with a menu item. You can associate an image with a menu item using the setImage:
method of NSMenuItem.
See also:
- stateImageWidth
, - calcSize
, - needsSizing
isHighlighted
Returns YES if the cell currently draws its menu item with a highlighted appearance.
See also:
- setHighlighted:
keyEquivalentRectForBounds:
(NSRect)cellFrame
Returns the rectangle into which the menu item's key equivalent should be drawn. The returned rectangle is based on cellFrame but encompasses only the area to be occupied by the key equivalent. To obtain the overall drawing rectangle for the menu item, you can invoke the drawingRectForBounds:
method.
See also:
- keyEquivalent
(NSMenuItem), - stateImageRectForBounds:
, - imageRectForBounds:
,
- titleRectForBounds:
, - keyEquivalentRectForBounds:
keyEquivalentWidth
Returns the width of the key equivalent associated with the menu item. You can associate a key equivalent with a menu item using the setKeyEquivalent:
method of NSMenuItem.
See also:
- calcSize
, - needsSizing
menuItem
Returns the NSMenuItem associated with this cell.
See also:
- setMenuItem:
needsSizing
Returns YES if the size of the menu item needs to be calculated, otherwise returns NO.
See also:
- setNeedsSizing:
, - calcSize
setHighlighted:
(BOOL)flag
Sets the highlight state for this cell.
You should not need to call this method directly. It is invoked by the setHighlightedItemIndex:
method of NSMenuView to provide user feedback during menu tracking or when the user selects a menu item (either by clicking or using a key equivalent).
See also:
- isHighlighted, - setHighlightedItemIndex:
(NSMenuView)
setMenuItem:
(NSMenuItem *)item
Sets the NSMenuItem for this cell.
See also:
- menuItem
setNeedsSizing:
(BOOL)flag
Sets a flag that indicates whether or not the menu item must be resized. If flag is YES, the next attempt to obtain any size-related information from this menu-item cell invokes the calcSize
method to recalculate the information. If flag is NO, the next attempt to obtain size-related information returns the currently cached values.
Subclasses that drastically change the way a menu item is drawn may need to invoke this method to recalculate the menu-item information, otherwise, your application should not need to invoke this method directly. The cell invokes this method as necessary when the contents of its menu item changes.
See also:
- needsSizing
stateImageRectForBounds:
(NSRect)cellFrame
Returns the rectangle into which the menu item's state image should be drawn. The returned rectangle is based on cellFrame but encompasses only the area to be occupied by the menu item's state image. To obtain the overall drawing rectangle for the cell's menu item, invoke the drawingRectForBounds:
method.
See also:
- stateImageRectForBounds:
, - imageRectForBounds:
, - titleRectForBounds:
,
- keyEquivalentRectForBounds:
stateImageWidth
Returns the width of the image used to indicate the state of the menu item. If the menu item has multiple images associated with it (to indicate any of the available states: on, off, or mixed) this method returns the width of the largest image. You can set the state images for a menu item using the setOnStateImage:
, setOffStateImage:
, and setMixedStateImage:
methods of NSMenuItem.
To change the state of the cell's menu item, use the setState:
method of NSMenuItem.
See also:
- calcSize
, - needsSizing
, - setState:
(NSMenuItem)
titleRectForBounds:
(NSRect)cellFrame
Returns the rectangle into which the menu item's title should be drawn. The returned rectangle is based on cellFrame but encompasses only the area to be occupied by the text of the title. To obtain the overall drawing rectangle for the menu item, you can invoke the drawingRectForBounds:
method.
See also:
- stateImageRectForBounds:
, - imageRectForBounds:
, - titleRectForBounds:
,
- keyEquivalentRectForBounds:
titleWidth
Returns the width of the menu item text. To set the menu item text, use the setTitle:
method of