---

NSMenuItemCell

Overview

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.

Tasks

Constructors

• NSMenuItemCell

Getting and Setting Menu Item Attributes

• isHighlighted
• setHighlighted
• menuItem
• setMenuItem
• menuView
• setMenuView

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
• drawKeyEquivalentWithFrameInView
• drawSeparatorItemWithFrameInView
• drawStateImageWithFrameInView
• drawTitleWithFrameInView
• needsDisplay
• setNeedsDisplay

Assigning a Tag

• tag

Instance Methods

calcSize

Calculates the minimum required width and height of the receiver’s menu item.

public void calcSize()

Discussion

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.

This method is invoked automatically when necessary. You should not need to invoke it directly.

See Also

• needsSizing

drawBorderAndBackgroundWithFrameInView

Draws the borders and background associated with the receiver’s menu item (if any).

public void drawBorderAndBackgroundWithFrameInView(NSRect cellFrame, NSView controlView)

Discussion

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. The cell invokes this method before invoking the methods to draw the other menu item components.

See Also

• drawWithFrameInView (NSCell)

drawImageWithFrameInView

Draws the image associated with the menu item.

public void drawImageWithFrameInView(NSRect cellFrame, NSView controlView)

Discussion

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.

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.

drawKeyEquivalentWithFrameInView

Draws the key equivalent associated with the menu item.

public void drawKeyEquivalentWithFrameInView(NSRect cellFrame, NSView controlView)

Discussion

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.

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

Draws a menu item separator.

public void drawSeparatorItemWithFrameInView(NSRect cellFrame, NSView controlView)

Discussion

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

• drawKeyEquivalentWithFrameInView
• drawTitleWithFrameInView
• isFlipped (NSView)

drawStateImageWithFrameInView

Draws the state image associated with the menu item.

public void drawStateImageWithFrameInView(NSRect cellFrame, NSView controlView)

Discussion

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.

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

Draws the title associated with the menu item.

public void drawTitleWithFrameInView(NSRect cellFrame, NSView controlView)

Discussion

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.

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

Returns the rectangle into which the menu item’s image should be drawn.

public NSRect imageRectForBounds(NSRect cellFrame)

Discussion

The returned rectangle is based on cellFrame but encompasses only the area to be occupied by the image.

See Also

• stateImageRectForBounds
• imageRectForBounds
• titleRectForBounds
• keyEquivalentRectForBounds

imageWidth

Returns the width of the image associated with a menu item.

public float imageWidth()

Discussion

You can associate an image with a menu item using NSMenuItem’s setImage method.

See Also

• stateImageWidth
• calcSize
• needsSizing

isHighlighted

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

public boolean isHighlighted()

Discussion

.

See Also

• setHighlighted

keyEquivalentRectForBounds

Returns the rectangle into which the menu item’s key equivalent should be drawn.

public NSRect keyEquivalentRectForBounds(NSRect cellFrame)

Discussion

The returned rectangle is based on cellFrame but encompasses only the area to be occupied by the key equivalent.

See Also

• keyEquivalent (NSMenuItem)
• stateImageRectForBounds
• imageRectForBounds
• titleRectForBounds
• keyEquivalentRectForBounds

keyEquivalentWidth

Returns the width of the key equivalent associated with the menu item.

public float keyEquivalentWidth()

Discussion

You can associate a key equivalent with a menu item using NSMenuItem’s setKeyEquivalent method.

See Also

• calcSize
• needsSizing

menuItem

Returns the NSMenuItem associated with the receiver.

public NSMenuItem menuItem()

See Also

• setMenuItem

menuView

Returns the menu view associated with the receiver.

public NSMenuView menuView()

See Also

• setMenuView

needsDisplay

Returns true if the menu item needs to be displayed; otherwise returns false.

public boolean needsDisplay()

See Also

• setNeedsDisplay

needsSizing

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

public boolean needsSizing()

See Also

• setNeedsSizing
• calcSize

setHighlighted

Sets the highlight state for the receiver to flag.

public void setHighlighted(boolean flag)

Discussion

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

Sets the NSMenuItem for the receiver to item.

public void setMenuItem(NSMenuItem item)

See Also

• menuItem

setMenuView

Sets the menu view for the receiver menuView.

public void setMenuView(NSMenuView menuView)

See Also

• menuView

setNeedsDisplay

Sets whether the menu item needs to be drawn to flag.

public void setNeedsDisplay(boolean flag)

See Also

• needsDisplay

setNeedsSizing

Sets a flag that indicates whether or not the menu item must be resized.

public void setNeedsSizing(boolean flag)

Discussion

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 content of its menu item changes.

See Also

• needsSizing

stateImageRectForBounds

Returns the rectangle into which the menu item’s state image should be drawn.

public NSRect stateImageRectForBounds(NSRect cellFrame)

Discussion

The returned rectangle is based on cellFrame but encompasses only the area to be occupied by the menu item’s state image.

See Also

• stateImageRectForBounds
• imageRectForBounds
• titleRectForBounds
• keyEquivalentRectForBounds

stateImageWidth

Returns the width of the image used to indicate the state of the menu item.

public float stateImageWidth()

Discussion

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)

tag

Returns the tag of the selected menu item, or 0 if no item is selected.

public int tag()

Discussion

Setting the tag value of an NSMenuItemCell with setTag does nothing.

See Also

• setTag (NSActionCell)

titleRectForBounds

Returns the rectangle into which the menu item’s title should be drawn.

public NSRect titleRectForBounds(NSRect cellFrame)

Discussion

The returned rectangle is based on cellFrame but encompasses only the area to be occupied by the text of the title.

See Also

• stateImageRectForBounds
• imageRectForBounds
• titleRectForBounds
• keyEquivalentRectForBounds

titleWidth

Returns the width of the menu item text.

public float titleWidth()

Discussion

To set the menu item text, use NSMenuItem’s setTitle method.

See Also

• calcSize
• needsSizing

---