---

NSMenuItemCell Class Reference

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

Configuring Menu-Item Attributes

• – menuItem
• – setMenuItem:
• – menuView
• – setMenuView:

Calculating the Size of a Menu Item

• – calcSize
• – needsSizing
• – setNeedsSizing:
• – imageWidth
• – titleWidth
• – keyEquivalentWidth
• – stateImageWidth

Getting the Menu Item’s Drawing Rectangle

• – keyEquivalentRectForBounds:
• – stateImageRectForBounds:
• – titleRectForBounds:

Drawing the Menu Item

• – drawBorderAndBackgroundWithFrame:inView:
• – drawImageWithFrame:inView:
• – drawKeyEquivalentWithFrame:inView:
• – drawSeparatorItemWithFrame:inView:
• – drawStateImageWithFrame:inView:
• – drawTitleWithFrame:inView:
• – needsDisplay
• – setNeedsDisplay:

Assigning a Tag

• – tag

Instance Methods

calcSize

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

- (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.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – needsSizing

Declared In

NSMenuItemCell.h

drawBorderAndBackgroundWithFrame:inView:

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

- (void)drawBorderAndBackgroundWithFrame:(NSRect)cellFrame inView:(NSView *)controlView

Parameters

cellFrame

A rectangle defining the receiver's frame area.

controlView

The view object that contains this cell (usually an NSControl object).

Discussion

This method invokes the NSCell method imageRectForBounds:, passing it cellFrame, to calculate the rectangle in which to draw the image. The cell invokes this method before invoking the methods to draw the other menu item components.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – drawWithFrame:inView: (NSCell)

Declared In

NSMenuItemCell.h

drawImageWithFrame:inView:

Draws the image associated with the menu item.

- (void)drawImageWithFrame:(NSRect)cellFrame inView:(NSView *)controlView

Parameters

cellFrame

A rectangle defining the receiver's frame area.

controlView

The view object that contains this cell (usually an NSControl object).

Discussion

This method invokes the NSCell method imageRectForBounds:, passing it cellFrame, to calculate the rectangle in which to draw the image. 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.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSMenuItemCell.h

drawKeyEquivalentWithFrame:inView:

Draws the key equivalent associated with the menu item.

- (void)drawKeyEquivalentWithFrame:(NSRect)cellFrame inView:(NSView *)controlView

Parameters

cellFrame

A rectangle defining the receiver's frame area.

controlView

The view object that contains this cell (usually an NSControl object).

Discussion

This method invokes keyEquivalentRectForBounds:, passing it cellFrame, to calculate the rectangle in which to draw the key equivalent. 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.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSMenuItemCell.h

drawSeparatorItemWithFrame:inView:

Draws a menu item separator.

- (void)drawSeparatorItemWithFrame:(NSRect)cellFrame inView:(NSView *)controlView

Parameters

cellFrame

A rectangle defining the receiver's frame area.

controlView

The view object that contains this cell (usually an NSControl object).

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.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – drawKeyEquivalentWithFrame:inView:
• – drawTitleWithFrame:inView:
• – isFlipped (NSView)

Declared In

NSMenuItemCell.h

drawStateImageWithFrame:inView:

Draws the state image associated with the menu item.

- (void)drawStateImageWithFrame:(NSRect)cellFrame inView:(NSView *)controlView

Parameters

cellFrame

A rectangle defining the receiver's frame area.

controlView

The view object that contains this cell (usually an NSControl object).

Discussion

This method invokes stateImageRectForBounds:, passing it cellFrame, to calculate the rectangle in which to draw the state image. 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.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSMenuItemCell.h

drawTitleWithFrame:inView:

Draws the title associated with the menu item.

- (void)drawTitleWithFrame:(NSRect)cellFrame inView:(NSView *)controlView

Parameters

cellFrame

A rectangle defining the receiver's frame area.

controlView

The view object that contains this cell (usually an NSControl object).

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.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSMenuItemCell.h

imageWidth

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

- (CGFloat)imageWidth

Discussion

You can associate an image with a menu item using the NSMenuItem setImage: method.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – stateImageWidth
• – calcSize
• – needsSizing

Declared In

NSMenuItemCell.h

keyEquivalentRectForBounds:

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

- (NSRect)keyEquivalentRectForBounds:(NSRect)cellFrame

Parameters

cellFrame

A rectangle that defines the bounds of the receiver.

Return Value

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

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – keyEquivalent (NSMenuItem)
• – stateImageRectForBounds:
• – titleRectForBounds:
• – keyEquivalentRectForBounds:

Declared In

NSMenuItemCell.h

keyEquivalentWidth

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

- (CGFloat)keyEquivalentWidth

Discussion

You can associate a key equivalent with a menu item using the NSMenuItem method setKeyEquivalent:.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – calcSize
• – needsSizing

Declared In

NSMenuItemCell.h

menuItem

Returns the NSMenuItem object associated with the receiver.

- (NSMenuItem *)menuItem

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setMenuItem:

Declared In

NSMenuItemCell.h

menuView

Returns the menu view associated with the receiver.

- (NSMenuView *)menuView

Availability

• Available in Mac OS X v10.0 and later.
• Not available to 64-bit applications.

See Also

• – setMenuView:

Declared In

NSMenuItemCell.h

needsDisplay

Returns YES if the menu item needs to be displayed; otherwise returns NO.

- (BOOL)needsDisplay

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setNeedsDisplay:

Declared In

NSMenuItemCell.h

needsSizing

Returns YES if the size of the menu item needs to be calculated; otherwise returns NO.

- (BOOL)needsSizing

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setNeedsSizing:
• – calcSize

Declared In

NSMenuItemCell.h

setMenuItem:

Sets the NSMenuItem object associated withthe receive.

- (void)setMenuItem:(NSMenuItem *)item

Parameters

item

The NSMenuItem object to set.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – menuItem

Declared In

NSMenuItemCell.h

setMenuView:

Sets the menu view for the receiver.

- (void)setMenuView:(NSMenuView *)menuView

Parameters

menuView

The NSMenuView object to associate with the receiver.

Availability

• Available in Mac OS X v10.0 and later.
• Not available to 64-bit applications.

See Also

• – menuView

Declared In

NSMenuItemCell.h

setNeedsDisplay:

Sets whether the menu item needs to be drawn.

- (void)setNeedsDisplay:(BOOL)flag

Parameters

flag

YES if the menu item needs to be drawn, NO otherwise.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – needsDisplay

Declared In

NSMenuItemCell.h

setNeedsSizing:

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

- (void)setNeedsSizing:(BOOL)flag

Parameters

flag

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.

Discussion

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.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – needsSizing

Declared In

NSMenuItemCell.h

stateImageRectForBounds:

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

- (NSRect)stateImageRectForBounds:(NSRect)cellFrame

Parameters

cellFrame

A rectangle that defines the bounds of the receiver.

Return Value

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

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – stateImageRectForBounds:
• – titleRectForBounds:
• – keyEquivalentRectForBounds:

Declared In

NSMenuItemCell.h

stateImageWidth

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

- (CGFloat)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 the NSMenuItem methods setOnStateImage:, setOffStateImage:, and setMixedStateImage:.

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

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – calcSize
• – needsSizing
• – setState: (NSMenuItem)

Declared In

NSMenuItemCell.h

tag

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

- (NSInteger)tag

Discussion

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

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setTag: (NSActionCell)

Declared In

NSMenuItemCell.h

titleRectForBounds:

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

- (NSRect)titleRectForBounds:(NSRect)cellFrame

Parameters

cellFrame

A rectangle that defines the bounds of the receiver.

Return Value

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

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – stateImageRectForBounds:
• – titleRectForBounds:
• – keyEquivalentRectForBounds:

Declared In

NSMenuItemCell.h

titleWidth

Returns the width of the menu item text.

- (CGFloat)titleWidth

Discussion

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

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – calcSize
• – needsSizing

Declared In

NSMenuItemCell.h

---