---

NSCell Class Reference

Overview

The NSCell class provides a mechanism for displaying text or images in an NSView object without the overhead of a full NSView subclass. It’s used heavily by most of the NSControl classes to implement their internal workings.

Adopted Protocols

• encodeWithCoder:

• initWithCoder:

• copyWithZone:

Tasks

Initializing a Cell

• – initImageCell:
• – initTextCell:

Managing Cell Values

• – setObjectValue:
• – objectValue
• – hasValidObjectValue
• – setIntValue:
• – intValue
• – setIntegerValue:
• – integerValue
• – setStringValue:
• – stringValue
• – setDoubleValue:
• – doubleValue
• – setFloatValue:
• – floatValue

Managing Cell Attributes

• – setCellAttribute:to:
• – cellAttribute:
• – setType:
• – type
• – setEnabled:
• – isEnabled
• – allowsUndo
• – setAllowsUndo:

Managing Display Attributes

• – setBezeled:
• – isBezeled
• – setBordered:
• – isBordered
• – isOpaque
• – setControlTint:
• – controlTint
• – setBackgroundStyle:
• – backgroundStyle
• – interiorBackgroundStyle

Managing Cell State

• – allowsMixedState
• – nextState
• – setAllowsMixedState:
• – setNextState
• – setState:
• – state

Modifying Textual Attributes

• – setEditable:
• – isEditable
• – setSelectable:
• – isSelectable
• – setScrollable:
• – isScrollable
• – setAlignment:
• – alignment
• – setFont:
• – font
• – lineBreakMode
• – setLineBreakMode:
• – setWraps:
• – wraps
• – baseWritingDirection
• – setBaseWritingDirection:
• – setAttributedStringValue:
• – attributedStringValue
• – setAllowsEditingTextAttributes:
• – allowsEditingTextAttributes
• – setImportsGraphics:
• – importsGraphics
• – setUpFieldEditorAttributes:
• – title
• – setTitle:

Managing the Target and Action

• – setAction:
• – action
• – setTarget:
• – target
• – setContinuous:
• – isContinuous
• – sendActionOn:

Managing the Image

• – setImage:
• – image
• – preparedImage

Managing the Tag

• – setTag:
• – tag

Formatting and Validating Data

• – setFormatter:
• – formatter
• – isEntryAcceptable:
• – setFloatingPointFormat:left:right:
• – entryType Deprecated in Mac OS X v10.0 and later
• – setEntryType: Deprecated in Mac OS X v10.0 and later

Managing Menus

• + defaultMenu
• – setMenu:
• – menu
• – menuForEvent:inRect:ofView:

Comparing Cells

• – compare:

Respond to Keyboard Events

• – acceptsFirstResponder
• – setShowsFirstResponder:
• – showsFirstResponder
• – setTitleWithMnemonic:
• – mnemonic
• – refusesFirstResponder
• – setMnemonicLocation:
• – setRefusesFirstResponder:
• – mnemonicLocation
• – performClick:

Deriving Values

• – takeObjectValueFrom:
• – takeIntegerValueFrom:
• – takeIntValueFrom:
• – takeStringValueFrom:
• – takeDoubleValueFrom:
• – takeFloatValueFrom:

Representing an Object

• – setRepresentedObject:
• – representedObject

Tracking the Mouse

• – trackMouse:inRect:ofView:untilMouseUp:
• – startTrackingAt:inView:
• – continueTracking:at:inView:
• – stopTracking:at:inView:mouseIsUp:
• – mouseDownFlags
• + prefersTrackingUntilMouseUp
• – getPeriodicDelay:interval:

Hit Testing

• – hitTestForEvent:inRect:ofView:

Managing the Cursor

• – resetCursorRect:inView:

Handling Keyboard Alternatives

• – keyEquivalent

Managing Focus Rings

• + defaultFocusRingType
• – setFocusRingType:
• – focusRingType

Determining Cell Size

• – calcDrawInfo:
• – cellSize
• – cellSizeForBounds:
• – drawingRectForBounds:
• – imageRectForBounds:
• – titleRectForBounds:
• – controlSize
• – setControlSize:

Drawing and Highlighting

• – drawWithFrame:inView:
• – highlightColorWithFrame:inView:
• – drawInteriorWithFrame:inView:
• – controlView
• – setControlView:
• – highlight:withFrame:inView:
• – setHighlighted:
• – isHighlighted

Editing and Selecting Text

• – editWithFrame:inView:editor:delegate:event:
• – selectWithFrame:inView:editor:delegate:start:length:
• – sendsActionOnEndEditing
• – setSendsActionOnEndEditing:
• – endEditing:
• – wantsNotificationForMarkedText

Managing Expansion Frames

• – expansionFrameWithFrame:inView:
• – drawWithExpansionFrame:inView:

Class Methods

defaultFocusRingType

Returns the default type of focus ring for the receiver.

+ (NSFocusRingType)defaultFocusRingType

Return Value

The default type of focus ring for the receiver (one of the values listed in NSFocusRingType).

Availability

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

Declared In

NSCell.h

defaultMenu

Returns the default menu for instances of the receiver.

+ (NSMenu *)defaultMenu

Return Value

The default menu. The NSCell implementation of this method returns nil.

Availability

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

See Also

• – menu
• – setMenu:

Declared In

NSCell.h

prefersTrackingUntilMouseUp

Returns a Boolean value that indicates whether tracking stops when the cursor leaves the cell.

+ (BOOL)prefersTrackingUntilMouseUp

Return Value

YES if tracking stops when the cursor leaves the cell, otherwise NO.

Discussion

The default implementation returns NO. Subclasses may override this method to return a different value.

Availability

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

See Also

• – trackMouse:inRect:ofView:untilMouseUp:

Declared In

NSCell.h

Instance Methods

acceptsFirstResponder

Returns a Boolean value that indicates whether the receiver accepts first responder status.

- (BOOL)acceptsFirstResponder

Return Value

YES if the receiver can become the first responder, otherwise NO.

Discussion

The default value is YES if the receiver is enabled. Subclasses may override this method to return a different value.

Availability

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

See Also

• – performClick:
• – setShowsFirstResponder:
• – setTitleWithMnemonic:

Declared In

NSCell.h

action

Returns the default action-message selector associated with the cell.

- (SEL)action

Return Value

The selector associated with the cell. The NSCell implementation of this method returns NULL by default.

Availability

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

See Also

• – setAction:
• – setTarget:
• – target

Declared In

NSCell.h

alignment

Returns the alignment of text in the receiver.

- (NSTextAlignment)alignment

Return Value

The alignment of text in the receiver (one of the following constants: NSLeftTextAlignment, NSRightTextAlignment,NSCenterTextAlignment, NSJustifiedTextAlignment, NSNaturalTextAlignment).

Discussion

The default value is NSNaturalTextAlignment.

Availability

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

See Also

• – setAlignment:

Declared In

NSCell.h

allowsEditingTextAttributes

Returns a Boolean value that indicates whether the receiver allows user editing of textual attributes.

- (BOOL)allowsEditingTextAttributes

Return Value

YES if the receiver allows the user to edit textual attributes of the cell's text, otherwise NO.

Availability

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

See Also

• – setAllowsEditingTextAttributes:

Declared In

NSCell.h

allowsMixedState

Returns a Boolean value that indicates whether the receiver supports three states.

- (BOOL)allowsMixedState

Return Value

YES if the receiver supports all three states (on, off, and mixed), otherwise NO (the receiver supports only the on and off states).

Availability

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

See Also

• – nextState
• – setAllowsMixedState:
• – setNextState

Declared In

NSCell.h

allowsUndo

Returns a Boolean value that indicates whether the receiver assumes responsibility for undo operations.

- (BOOL)allowsUndo

Return Value

YES if the receiver handles undo operations, otherwise NO.

Discussion

By default, the NSTextFieldCell class uses this feature to handle undo operations for edited text. Other controls set a value that is appropriate for their implementation.

Availability

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

See Also

• – setAllowsUndo:

Declared In

NSCell.h

attributedStringValue

Returns the value of the receiver’s cell as an attributed string using the receiver's formatter object (if one exists).

- (NSAttributedString *)attributedStringValue

Return Value

The value of the cell interpreted as an attributed string.

Discussion

The textual attributes are the default paragraph style, the receiver’s font and alignment, and whether the receiver is enabled and scrollable.

For Mac OS X v10.3 and later: If you use a class that responds to the selector attributedStringValue for the object value of a cell, then the cell will use that method to fetch the string to draw rather than using stringValue.

Availability

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

See Also

• – setAttributedStringValue:

Declared In

NSCell.h

backgroundStyle

Returns the background style for the receiver.

- (NSBackgroundStyle)backgroundStyle

Return Value

The background style for the receiver.

Discussion

The background describes the surface the cell is drawn onto in drawWithFrame:inView:. A control typically sets this before it asks the cell to draw. A cell may draw differently based on background characteristics. For example, a tableview drawing a cell in a selected row might call [cell setBackgroundStyle:NSBackgroundStyleDark]. A text cell might decide to render its text white as a result. A rating-style level indicator might draw its stars white instead of gray.

Availability

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

Declared In

NSCell.h

baseWritingDirection

Returns the initial writing direction used to determine the actual writing direction for text.

- (NSWritingDirection)baseWritingDirection

Return Value

The initial writing direction the receiver uses to determine the actual writing direction for text (one of the following values: NSWritingDirectionNatural, NSWritingDirectionLeftToRight, NSWritingDirectionRightToLeft). If no writing direction is set, returns NSWritingDirectionNatural.

Discussion

The default value is NSWritingDirectionNatural.

The Text system uses this value as a hint for calculating the actual direction for displaying Unicode characters. You should not need to call this method directly.

Availability

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

See Also

• – setBaseWritingDirection:

Declared In

NSCell.h

calcDrawInfo:

Recalculates the cell geometry.

- (void)calcDrawInfo:(NSRect)aRect

Parameters

aRect

The reference rectangle to use when calculating the cell information.

Discussion

Objects (such as controls) that manage NSCell objects generally maintain a flag that informs them if any of their cells have been modified in such a way that the location or size of the cell should be recomputed. If so, calcSize method of NSControl is automatically invoked prior to the display of the cell, and that method invokes the calcDrawInfo: method of the cell.

The default implementation of this method does nothing.

Availability

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

See Also

• – cellSize
• – drawingRectForBounds:

Declared In

NSCell.h

cellAttribute:

Returns the value for the specified cell attribute.

- (NSInteger)cellAttribute:(NSCellAttribute)aParameter

Parameters

aParameter

The cell attribute whose value you want to get. Attributes include the receiver's current state and whether it is disabled, editable, or highlighted.

Return Value

The value for the cell attribute specified by aParameter.

Availability

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

See Also

• – setCellAttribute:to:

Declared In

NSCell.h

cellSize

Returns the minimum size needed to display the receiver.

- (NSSize)cellSize

Return Value

The size of the cell, or the size (10000, 10000) if the receiver is not a text or image cell. If the cell is an image cell but no image has been set, returns NSZeroSize.

Discussion

This method takes into account of the size of the image or text within a certain offset determined by the border type of the cell.

Availability

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

See Also

• – drawingRectForBounds:

Declared In

NSCell.h

cellSizeForBounds:

Returns the minimum size needed to display the receiver, constraining it to the specified rectangle.

- (NSSize)cellSizeForBounds:(NSRect)aRect

Parameters

aRect

The size of the cell, or the size of the aRect parameter if the cell is not a text or image cell. If the cell is an image cell but no image has been set, returns NSZeroSize.

Discussion

This method takes into account of the size of the image or text within a certain offset determined by the border type of the cell. If the receiver is of text type, the text is resized to fit within aRect (as much as aRect is within the bounds of the cell).

Availability

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

See Also

• – drawingRectForBounds:

Declared In

NSCell.h

compare:

Compares the string values of the receiver another cell, disregarding case.

- (NSComparisonResult)compare:(id)otherCell

Parameters

otherCell

The cell to compare against the receiver. This parameter must be of type NSCell; if it is not, this method raises NSBadComparisonException.

This value must not be nil. If the value is nil, the behavior is undefined and may change in future versions of Mac OS X.

Return Value

NSOrderedAscending if the string value of the receiver precedes the string value of otherCell in lexical ordering, NSOrderedSame if the string values are equivalent in lexical value, and NSOrderedDescending string value of the receiver follows the string value of otherCell in lexical ordering.

Availability

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

Declared In

NSCell.h

continueTracking:at:inView:

Returns a Boolean value that indicates whether mouse tracking should continue in the receiving cell.

- (BOOL)continueTracking:(NSPoint)lastPoint at:(NSPoint)currentPoint inView:(NSView *)controlView

Parameters

lastPoint

Contains either the initial location of the cursor when tracking began or the previous current point.

currentPoint

The current location of the cursor.

controlView

The NSControl object managing the receiver.

Return Value

YES if mouse tracking should continue, otherwise NO.

Discussion

This method is invoked in trackMouse:inRect:ofView:untilMouseUp:. The default implementation returns YES if the cell is set to continuously send action messages to its target when the mouse button is down or the mouse is being dragged. Subclasses can override this method to provide more sophisticated tracking behavior.

Availability

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

See Also

• – startTrackingAt:inView:
• – stopTracking:at:inView:mouseIsUp:

Declared In

NSCell.h

controlSize

Returns the size of the receiver.

- (NSControlSize)controlSize

Return Value

A value that specifies the size of the receiver (for possible values, see “Control Sizes”).

Availability

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

See Also

• – setControlSize:

Declared In

NSCell.h

controlTint

Returns the receiver’s control tint.

- (NSControlTint)controlTint

Return Value

An NSControlTint value that specifies the tint of the receiver (see “Control Tints” for possible values).

Availability

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

See Also

• – setControlTint:

Declared In

NSCell.h

controlView

Returns the receiver's control.

- (NSView *)controlView

Return Value

The view (normally an NSControl object) associated with this cell. The default implementation returns nil.

Availability

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

See Also

• – drawWithFrame:inView:
• – setControlView:

Declared In

NSCell.h

doubleValue

Returns the value of the receiver’s cell as a double-precision floating-point number.

- (double)doubleValue

Return Value

The value of the cell interpreted as a double-precision floating-point number. If the receiver is not a text-type cell or the cell value is not scannable, returns 0.

Availability

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

See Also

• – setDoubleValue:

Declared In

NSCell.h

drawingRectForBounds:

Returns the rectangle within which the receiver draws itself

- (NSRect)drawingRectForBounds:(NSRect)theRect

Parameters

theRect

The bounding rectangle of the receiver.

Return Value

The rectangle in which the receiver draws itself. This rectangle is slightly inset from the one in theRect.

Availability

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

See Also

• –