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


[Previous] [Class List] [Next]

NSMenuItemCell


Inherits from: NSButtonCell : NSActionCell : NSCell : NSObject
Package: com.apple.yellow.foundation


Class Description


NSMenuItemCell is a class that handles the measurement and display of a single menu item in its encompassing frame. Instances of NSMenuItemCell work in conjunction with an NSMenuView object to control the overall appearance of the menu.

An instance of NSMenuItemCell uses the information contained in an NSMenuItem object to obtain the basic geometry of the menu item. Using this geometry, the menu-item cell calculates the minimal space required for drawing each of its 3 components: the state image, the title text or image, and the key equivalent. Once this information has been calculated, the cell's menu view gathers the information and uses it to determine the optimal size for the menu. The cell then bases its drawing calculations on this optimal size information.

Menu Item Layout

Menu-item cells have two sets of methods for returning two different sets of measurements. The first set of methods return the minimal space required by the menu item's individual components. These methods include imageWidth, titleWidth, keyEquivalentWidth, and stateImageWidth.

The second set of methods return the drawing rectangle to be used by the cell when drawing a given component. 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.

Subclassing NSMenuItemCell

You can subclass NSMenuItemCell to change the way menu items are drawn by your application. For example, your subclass can display extra information for each menu item or change the basic appearance (background color, borders, adornments, and so on) of the menu item. If you create a custom subclass of NSMenuItemCell, you may also need to subclass NSMenuView to handle any additional information provided by your menu-item cell. If you simply want to change the way the cell is drawn, you can do that by overriding the menu-item cell's drawWithFrame:inView: method.


Method Types


Getting and setting menu item attributes
isHighlighted
setHighlighted
menuItem
setMenuItem
Calculating menu item sizes
calcSize
needsSizing
setNeedsSizing
imageWidth
titleWidth
keyEquivalentWidth
stateImageWidth
Getting the menu item's drawing rectangle
imageRectForBounds
keyEquivalentRectForBounds
stateImageRectForBounds
titleRectForBounds:
Drawing the menu item
drawBorderAndBackgroundWithFrameInView
drawImageWithFrameInView
drawKeyEquivalentWithFrame:inView:
drawSeparatorItemWithFrameInView
drawStateImageWithFrameInView
drawTitleWithFrameInView

Constructors


NSMenuItemCell

public NSMenuItemCell(String aString)

<<Documentation Forthcoming>>

public NSMenuItemCell(NSImage aImage)

<<Documentation Forthcoming>>

Instance Methods



calcSize

public void calcSize()

Calculates 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 automatically when necessary. You should not need to invoke it directly.

See Also: needsSizing



drawBorderAndBackgroundWithFrameInView

public void drawBorderAndBackgroundWithFrameInView(NSRect cellFrame, 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)



drawImageWithFrameInView

public void drawImageWithFrameInView(NSRect cellFrame, 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:inView:

public void drawKeyEquivalentWithFrameInView(NSRect cellFrame, 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.



drawSeparatorItemWithFrameInView

public void drawSeparatorItemWithFrameInView(NSRect cellFrame, 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 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:, drawTitleWithFrameInView, - isFlipped (NSView)



drawStateImageWithFrameInView

public void drawStateImageWithFrameInView(NSRect cellFrame, 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.



drawTitleWithFrameInView

public void drawTitleWithFrameInView(NSRect cellFrame, 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 title. 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

public NSRect 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

public float imageWidth()

Returns the width of the image associated with a menu item. You can associate an image with a menu item using NSMenuItem's setImage: method.

See Also: stateImageWidth, calcSize, needsSizing



isHighlighted

public boolean isHighlighted()

Returns true if the cell currently draws its menu item with a highlighted appearance.

See Also: setHighlighted



keyEquivalentRectForBounds

public NSRect 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, use the drawingRectForBounds: method.

See Also: - keyEquivalent (NSMenuItem), stateImageRectForBounds, imageRectForBounds, titleRectForBounds:, keyEquivalentRectForBounds



keyEquivalentWidth

public float keyEquivalentWidth()

Returns the width of the key equivalent associated with the menu item. You can associate a key equivalent with a menu item using NSMenuItem's setKeyEquivalent: method.

See Also: calcSize, needsSizing



menuItem

public NSMenuItem menuItem()

Returns the NSMenuItem associated with this cell.

See Also: setMenuItem



menuView

public NSMenuView menuView()

<<Documentation Forthcoming>>

needsDisplay

public boolean needsDisplay()

<<Documentation Forthcoming>>

needsSizing

public boolean needsSizing()

Returns true if the size of the menu item needs to be calculated, otherwise returns false.

See Also: setNeedsSizing, calcSize



setHighlighted

public void setHighlighted(boolean flag)

Sets the highlight state for this cell.

You should not need to call this method directly. It is invoked by the NSMenuView's setHighlightedItemIndex: method 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

public void setMenuItem(NSMenuItem item)

Sets the NSMenuItem for this cell.

See Also: menuItem



setMenuView

public void setMenuView(NSMenuView menuView)

<<Documentation Forthcoming>>

setNeedsDisplay

public void setNeedsDisplay(boolean flag)

<<Documentation Forthcoming>>

setNeedsSizing

public void setNeedsSizing(boolean flag)

Sets a flag that indicates whether or not the menu item must be resized. If flag is true, 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 false, 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. Other parts of 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

public NSRect 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, use the drawingRectForBounds: method.

See Also: stateImageRectForBounds, imageRectForBounds, titleRectForBounds:, keyEquivalentRectForBounds



stateImageWidth

public float 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 NSMenuItem's setOnStateImage:, setOffStateImage:, and setMixedStateImage: methods.

To change the state of the cell's menu item, use NSMenuItem's setState: method.

See Also: calcSize, needsSizing, - setState: (NSMenuItem)



titleRectForBounds:

public NSRect 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, use the drawingRectForBounds: method.

See Also: stateImageRectForBounds, imageRectForBounds, titleRectForBounds:, keyEquivalentRectForBounds



titleWidth

public float titleWidth()

Returns the width of the menu item text. To set the menu item text, use NSMenuItem's setTitle: method.

See Also: calcSize, needsSizing




[Previous] [Next]