PATH  Documentation > Mac OS X > Application Kit Reference: Objective-C

Table of Contents

NSCell


Inherits from:
NSObject
Conforms to:
NSCoding
NSCopying
NSObject (NSObject)
Declared in:
AppKit/NSCell.h




Class Description


The NSCell class provides a mechanism for displaying text or images in an NSView without the overhead of a full NSView subclass. In particular, it provides much of the functionality of the NSText class by providing access to a shared NSText object used by all instances of NSCell in an application. NSCells are also extremely useful for placing text or images at various locations in a custom subclass of NSView.

NSCell is used heavily by most of the NSControl classes to implement their internal workings. For example, NSSlider uses an NSSliderCell, NSTextField uses an NSTextFieldCell, and NSBrowser uses an NSBrowserCell. Sending a message to the NSControl is often simpler than dealing directly with the corresponding NSCell. For instance, NSControls typically invoke updateCell: (causing the cell to be displayed) after changing a cell attribute; whereas if you directly call the corresponding method of the NSCell, the NSCell might not automatically display itself again.

Some subclasses of NSControl (notably NSMatrix) group NSCells in an arrangement where they act together in some cooperative manner. Thus, with an NSMatrix, you can implement a uniformly sized group of radio buttons without needing an NSView for each button (and without needing an NSText object as the field editor for the text on each button).

The NSCell class provides primitives for displaying text or an image, editing text, setting and getting object values, maintaining state, highlighting, and tracking the mouse. NSCell's method trackMouse:inRect:ofView:untilMouseUp: implements the mechanism that sends action messages to target objects. However, NSCell implements target/action features abstractly, deferring the details of implementation to NSActionCell and its subclasses.


Object Values and Formatters


Every NSCell that displays text has a value associated with it. The NSCell stores that value as an object of potentially any type, displays it as an NSString, and returns it as a primary value or string object, according to what's requested ( intValue, floatValue, stringValue, and so on). Formatters are objects associated with NSCells (through setFormatter:) that translate a cell's object value to its it textual representation and convert what users type into the underlying object. NSCells have built-in formatters to handle common string and numeric (int, float, double) translations. In addition, you can specify date and numeric types more precisely with setEntryType: and specify floating-point format characteristics with setFloatingPointFormat:left:right:. You can also implement your own formatters to provide specialized object translation; see the NSFormatter specification for more information.

The text that an NSCell displays and stores can be an attributed string. Several methods help to set and get attributed-string values, including setAttributedStringValue: and setImportsGraphics:.


Cell States


For some subclasses of NSCell, such as an NSButtonCell, the object's value is its state. It can have either two states-NSOnState and NSOffState-or three states-NSOnState, NSOffState, and NSMixedState. A mixed state is useful for a checkbox or radio button that reflects the status of a feature. For example, suppose there's a checkbox that makes the selected text bold. If all the selected text is bold, it's on. If none of the selected text is bold, it's off. If the text has a combination of bold and plain text, it's mixed. Now suppose you click the checkbox. If you turn it on, all the text becomes bold. If you turn it off, all the text becomes plain. If you select the mixed state, the text remains as it is.

By default, an NSCell has two states. You can allow the third state with the method setAllowsMixedState:. To set the button's state directly, use setState:. To cycle through all available states, use setNextState.


Represented Objects


Represented objects are objects an NSCell stands for. (They're not to be confused with an NSCell's object value, which is the value of the cell.) By setting a represented object for an NSCell (using setRepresentedObject:) you make an association between the NSCell and that object. For instance, you could have a pop-up list, each cell of which lists a color as its title; when the user selects a cell, the represented NSColor object is displayed in a color well. This feature is solely for the developer's convenience. The cell itself does not use the represented object, except to archive and restore it.


Subclassing NSCell


The initImageCell: method is the designated initializer for NSCells that display images. The initTextCell: method is the designated initializer for NSCells that display text. Override one or both of these methods if you implement a subclass of NSCell that performs its own initialization. If you need to use target and action behavior, you may prefer to subclass NSActionCell or one of its subclasses, which provide the default implementation of this behavior.

If you want to implement your own mouse-tracking or mouse-up behavior, consider overriding startTrackingAt:inView:, continueTracking:at:inView:, and stopTracking:at:inView:mouseIsUp:. If you want to implement your own drawing, override drawWithFrame:inView: or drawInteriorWithFrame:inView:.

If the subclass contains instance variables that hold pointers to objects, consider overriding copyWithZone: to duplicate the objects. The default version copies only pointers to the objects.

For more information on how NSCell is used, see the NSControl class specification.




Constants


These constants specify how a cell formats numeric data. They're used by setEntryType: and entryType


Constant Restrictions and Other Information
NSIntType Must be between INT_MIN and INT_MAX
NSPositiveIntType Must be between 1 and INT_MAX
NSFloatType Must be between -FLT_MAX and FLT_MAX
NSPositiveFloatType Must be between FLT_MIN and FLT_MAX
NSDoubleType Must be between -DBL_MAX and DBL_MAX
NSPositiveDoubleType Must be between DBL_MAX and DBL_MAX
NSAnyType Any value is allowed.

These constants specify what a cell contains. They're used by setType: and type.


Constant Description
NSNullCellType Description forthcoming.
NSTextCellType Description forthcoming.
NSImageCellType Description forthcoming.

These constants specify how a button behaves when pressed and how it displays its state They're used by NSButton and NSButtonCell:


Constant Description
NSCellDisabled Description forthcoming.
NSCellState Description forthcoming.
NSPushInCell Description forthcoming.
NSCellEditable Description forthcoming.
NSChangeGrayCell Description forthcoming.
NSCellHighlighted Description forthcoming.
NSCellLightsByContents Description forthcoming.
NSCellLightsByGray Description forthcoming.
NSChangeBackgroundCell Description forthcoming.
NSCellLightsByBackground Description forthcoming.
NSCellIsBordered Description forthcoming.
NSCellHasOverlappingImage Description forthcoming.
NSCellHasImageHorizontal Description forthcoming.
NSCellHasImageOnLeftOrBottom Description forthcoming.
NSCellChangesContents Description forthcoming.
NSCellIsInsetButton Description forthcoming.
NSCellAllowsMixedState Description forthcoming.

These constants specify the position of a button's image relative to its title. They're used by NSButton's and NSButtonCell's setImagePosition: and imagePosition.


Constant Description
NSNoImage The cell doesn't display an image
NSImageOnly The cell displays an image, but not a title
NSImageLeft The image is to the left of the title
NSImageRight The image is to the right of the title
NSImageBelow The image is below the title
NSImageAbove The image is above the title
NSImageOverlaps The image overlaps the title

These constants specify a cell's state and are used mostly for buttons. They're described in "Cell States" .


Constant Description
NSMixedState The corresponding feature is in effect somewhere.
NSOffState The corresponding feature is in effect nowhere.
NSOnState The corresponding feature is in effect everywhere.

These constants specify what happens when a button is pressed or is displaying its alternate state. They're used by NSButtonCell's highlightsBy and showsStateBy.


Constant Description
NSNoCellMask The button cell doesn't change.
NSPushInCellMask The button cell "pushes in" if it has a border.
NSContentsCellMask The button cell displays its alternate icon and/or title.
NSChangeGrayCellMask The button cell swaps the "control color" (NSColor's controlColor) and white pixels on the its background and icon.
NSChangeBackgroundCellMask Same as NSChangeGrayCellMask, but only background pixels are changed.



Method Types


Initializing an NSCell
- initImageCell:
- initTextCell:
Setting and getting cell values
- setObjectValue:
- objectValue
- hasValidObjectValue
- setIntValue:
- intValue
- setStringValue:
- stringValue
- setDoubleValue:
- doubleValue
- setFloatValue:
- floatValue
Setting and getting cell attributes
- setCellAttribute:to:
- cellAttribute:
- setType:
- type
- setEnabled:
- isEnabled
- setBezeled:
- isBezeled
- setBordered:
- isBordered
- isOpaque
Setting the state
- allowsMixedState
- nextState
- setAllowsMixedState:
- setNextState
- setState:
- state
Modifying textual attributes of cells
- setEditable:
- isEditable
- setSelectable:
- isSelectable
- setScrollable:
- isScrollable
- setAlignment:
- alignment
- setFont:
- font
- setWraps:
- wraps
- setAttributedStringValue:
- attributedStringValue
- setAllowsEditingTextAttributes:
- allowsEditingTextAttributes
- setImportsGraphics:
- importsGraphics
- setUpFieldEditorAttributes:
Setting the target and action
- setAction:
- action
- setTarget:
- target
- setContinuous:
- isContinuous
- sendActionOn:
Setting and getting an image
- setImage:
- image
Assigning a tag
- setTag:
- tag
Formatting and validating data
- setFormatter:
- formatter
- setEntryType:
- entryType
- isEntryAcceptable:
- setFloatingPointFormat:left:right:
Managing menus for cells
+ defaultMenu
- setMenu:
- menu
- menuForEvent:inRect:ofView:
Comparing cells
- compare:
Making cells respond to keyboard events
- acceptsFirstResponder
- setShowsFirstResponder:
- showsFirstResponder
- setTitleWithMnemonic:
- mnemonic
- refusesFirstResponder
- setMnemonicLocation:
- setRefusesFirstResponder:
- mnemonicLocation
- performClick:
Deriving values from other cells
- takeObjectValueFrom:
- takeIntValueFrom:
- takeStringValueFrom:
- takeDoubleValueFrom:
- takeFloatValueFrom:
Representing an object with a cell
- setRepresentedObject:
- representedObject
Tracking the mouse
- trackMouse:inRect:ofView:untilMouseUp:
- startTrackingAt:inView:
- continueTracking:at:inView:
- stopTracking:at:inView:mouseIsUp:
- mouseDownFlags
+ prefersTrackingUntilMouseUp
- getPeriodicDelay:interval:
Managing the cursor
- resetCursorRect:inView:
Handling keyboard alternatives
- keyEquivalent
Determining cell sizes
- calcDrawInfo:
- cellSize
- cellSizeForBounds:
- drawingRectForBounds:
- imageRectForBounds:
- titleRectForBounds:
Drawing and highlighting cells
- drawWithFrame:inView:
- drawInteriorWithFrame:inView:
- controlView
- highlight:withFrame:inView:
- isHighlighted
Editing and selecting cell text
- editWithFrame:inView:editor:delegate:event:
- selectWithFrame:inView:editor:delegate:start:length:
- sendsActionOnEndEditing
- setSendsActionOnEndEditing:
- endEditing:


Class Methods



defaultMenu

+ (NSMenu *)defaultMenu

Returns the default menu for instances of the receiver. The default implementation returns nil.

See Also: - menu, - setMenu:



prefersTrackingUntilMouseUp

+ (BOOL)prefersTrackingUntilMouseUp

The default implementation returns NO, so tracking stops when the mouse leaves the NSCell; subclasses may override.

See Also: - trackMouse:inRect:ofView:untilMouseUp:




Instance Methods



acceptsFirstResponder

- (BOOL)acceptsFirstResponder

Returns whether or not the cell will accept first responder status. The default implementation returns YES if the cell is enabled and refusesFirstResponder returns NO; subclasses can override.

See Also: - performClick:, - setShowsFirstResponder:, - setTitleWithMnemonic:



action

- (SEL)action

Implemented by NSActionCell and its subclasses to return the selector of the cell's action method. The default implementation returns a null selector.

See Also: - setAction:, - setTarget:, - target



alignment

- (NSTextAlignment)alignment

Returns the alignment of text in the cell: NSLeftTextAlignment, NSRightTextAlignment, NSCenterTextAlignment, NSJustifiedTextAlignment, or NSNaturalTextAlignment.

See Also: - setAlignment:



allowsEditingTextAttributes

- (BOOL)allowsEditingTextAttributes

Returns whether the receiver allows the user editing of textual attributes.

See Also: - setAllowsEditingTextAttributes:



allowsMixedState

- (BOOL)allowsMixedState

Returns YES if the button has three states: on, off, and mixed. Returns NO if the button has two states: on and off.

See Also: - nextState, - setAllowsMixedState:, - setNextState



attributedStringValue

- (NSAttributedString *)attributedStringValue

Returns the value of the receiver as an attributed string, using the cell's formatter object (if one exists) to create the attributed string. The textual attributes are determined by the default paragraph style, the receiver's font and alignment, and whether the receiver is enabled and scrollable.

See Also: - setAttributedStringValue:



calcDrawInfo:

- (void)calcDrawInfo:(NSRect)aRect

Implemented by subclasses to recalculate drawing sizes with reference to aRect. Objects (such as NSControls) that manage NSCells generally maintain a flag that informs them if any of their cells has been modified in such a way that the location or size of the cell should be recomputed. If so, NSControl's calcSize method is automatically invoked prior to the display of the NSCell, and that method invokes the NSCell's calcDrawInfo: method. The default implementation does nothing.

See Also: - cellSize, - drawingRectForBounds:



cellAttribute:

- (int)cellAttribute:(NSCellAttribute)aParameter

Depending on aParameter, returns a setting for a cell attribute, such as the receiver's state, and whether it's disabled, editable, or highlighted.

See Also: - setCellAttribute:to:



cellSize

- (NSSize)cellSize

Returns the minimum size needed to display the NSCell, taking account of the size of the image or text within a certain offset determined by border type. If the receiving cell is neither of image or text type, an extremely large size is returned; if the receiving cell is of image type, and no image has been set, an extremely small size is returned.

See Also: - drawingRectForBounds:



cellSizeForBounds:

- (NSSize)cellSizeForBounds:(NSRect)aRect

Returns the minimum size needed to display the NSCell, taking account of the size of the image or text within an offset determined by border type. If the receiving cell is of text type, the text is resized to fit within aRect (as much as aRect is within the bounds of the cell). If the receiving cell is neither of image or text type, an extremely large size is returned; if the receiving cell is of image type, and no image has been set, an extremely small size is returned.

See Also: - drawingRectForBounds:



compare:

- (NSComparisonResult)compare:(id)otherCell

Compares the string values of this cell and otherCell (which must be a kind of NSCell), disregarding case. Raises NSBadComparisonException if otherCell is not of the NSCell class or if one of the cells being compared is not a text-type cell.

continueTracking:at:inView:

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

Returns whether mouse-tracking should continue in the receiving cell based on lastPoint and currentPoint within controlView. currentPoint is the current location of the mouse while lastPoint is either the initial location of the mouse or the previous currentPoint. 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 is down or is being dragged. Subclasses can override this method to provide more sophisticated tracking behavior.

See Also: - startTrackingAt:inView:, - stopTracking:at:inView:mouseIsUp:



controlView

- (NSView *)controlView

Implemented by subclasses to return the NSView last drawn in (normally an NSControl). The default implementation returns nil.

See Also: - drawWithFrame:inView:



doubleValue

- (double)doubleValue

Returns the NSCell's value as a double. If the receiver is not a text-type cell or the cell value is not scannable, the method returns zero.

drawInteriorWithFrame:inView:

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

Draws the "inside" of the receiving cell-this includes the image or text within the NSCell's frame in controlView (usually the cell's NSControl) but excludes the border. cellFrame is the frame of the NSCell or, in some cases, a portion of it. Text-type NSCells display their contents in a rectangle slightly inset from cellFrame using a global NSText object. Image-type NSCells display their contents centered within cellFrame. If the proper attributes are set, it also displays the dotted-line rectangle to indicate first responder and highlights the cell. This method is invoked from NSControl's drawCellInside: to visually update the what the NSCell displays when its contents change. This drawing is minimal, and becomes more complex in objects such as NSButtonCell and NSSliderCell.

Subclasses often override this method to provide more sophisticated drawing of cell contents. Because drawWithFrame:inView: invokes drawInteriorWithFrame:inView:: after it draws the NSCell's border, don't invoke drawWithFrame:inView: in your override implementation.

See Also: - isHighlighted, - setShowsFirstResponder:



drawWithFrame:inView:

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

Draws the receiver's regular or bezeled border (if those attributes are set) and then draws the interior of the cell by invoking drawInteriorWithFrame:inView:.

drawingRectForBounds:

- (NSRect)drawingRectForBounds:(NSRect)theRect

Returns the rectangle within which the cell draws itself; this rectangle is slightly inset from theRect on all sides to take the border into account.

See Also: - calcSize (NSControl)



editWithFrame:inView:editor:delegate:event:

- (void)editWithFrame:(NSRect)aRect inView:(NSView *)controlView editor:(NSText *)textObj delegate:(id)anObject event:(NSEvent *)theEvent

Begins editing of the receiver's text using the field editor textObj. This method is usually invoked in response to a mouse-down event. aRect must be the rectangle used for displaying the NSCell. theEvent is the NSLeftMouseDown event. anObject is made the delegate of textObj, and so will receive various NSText delegation and notification messages.

If the receiver isn't a text-type NSCell, no editing is performed. Otherwise, textObj is sized to aRect and its superview is set to aView, so it exactly covers the NSCell. Then it's activated and editing begins. It's the responsibility of the delegate to end editing when responding to textShouldEndEditing:. In doing this, it should remove any data from textObj.

See Also: - endEditing:, - selectWithFrame:inView:editor:delegate:start:length:



endEditing:

- (void)endEditing:(NSText *)textObj

Ends any editing of text occurring in the receiver begun with editWithFrame:inView:editor:delegate:event: and selectWithFrame:inView:editor:delegate:start:length:.

entryType

- (int)entryType

Returns the type of data the user can type into the receiver. If the receiver is not a text-type cell, or if no type has been set, NSAnyType is returned. See setEntryType: for a list of type constants.

See Also: - isEntryAcceptable:



floatValue

- (float)floatValue

Returns the NSCell's value as a float. If the receiver is not a text-type cell or the cell value is not scannable, the method returns zero.

font

- (NSFont *)font

Returns the font used to display text in the receiving cell or nil if the receiver is not a text-type cell.

See Also: - setFont:



formatter

- (id)formatter

Returns the formatter object (a kind of NSFormatter) associated with the cell. This object handles translation of the cell's contents between its on-screen representation and its object value.

See Also: - setFormatter:



getPeriodicDelay:interval:

- (void)getPeriodicDelay:(float *)delay interval:(float *)interval

Returns initial delay and repeat values for continuous sending of action messages to target objects. Subclasses can override to supply their own delay and interval values.

See Also: - isContinuous, - setContinuous:



hasValidObjectValue

- (BOOL)hasValidObjectValue

Returns whether the object associated with the receiver has a valid object value. A valid object value is one that the receiver's formatter can "understand." Objects that are "invalid" have been rejected by the formatter, but accepted by the delegate of the receiver's NSControl (in control:didFailToFormatString:errorDescription:).

See Also: - objectValue, - setObjectValue:



highlight:withFrame:inView:

- (void)highlight:(BOOL)flag withFrame:(NSRect)cellFrame inView:(NSView *)controlView

If the receiver's highlight status is different from flag, sets that status to flag and, if flag is YES, highlights the rectangle cellFrame in the NSControl (controlView).

Note that NSCell's highlighting does not appear when highlighted cells are printed (although instances of NSTextFieldCell, NSButtonCell, and others can print themselves highlighted). Generally, you cannot depend on highlighting being printed because implementations of this method may choose (or not choose) to use transparency.

See Also: - drawWithFrame:inView:, - isHighlighted



image

- (NSImage *)image

Returns the image displayed by the receiver or nil if the receiver is not an image-type cell.

See Also: - setImage:



imageRectForBounds:

- (NSRect)imageRectForBounds:(NSRect)theRect

Returns the rectangle the cell's image is drawn in, which is slightly offset from theRect.

See Also: - cellSizeForBounds:, - drawingRectForBounds:



importsGraphics

- (BOOL)importsGraphics

Returns whether the text of the receiver (if a text-type cell) is of Rich Text Format (RTF) and thus can import graphics.

See Also: - setImportsGraphics:



initImageCell:

- (id)initImageCell:(NSImage *)anImage

Returns an NSCell object initialized with anImage and set to have the cell's default menu. If anImage is nil, no image is set.

initTextCell:

- (id)initTextCell:(NSString *)aString

Returns an NSCell object initialized with aString and set to have the cell's default menu. If no field editor (a shared NSText object) has been created for all NSCells, one is created.

intValue

- (int)intValue

Returns the receiver's value as an int. If the receiver is not a text-type cell or the cell value is not scannable, the method returns zero.

isBezeled

- (BOOL)isBezeled

Returns whether the receiving cell has a bezeled border.

See Also: - setBezeled:



isBordered

- (BOOL)isBordered

Returns whether the receiving cell has a plain border.

See Also: - setBordered:



isContinuous

- (BOOL)isContinuous

Returns whether the receiving cell sends its action message continuously on mouse down.

See Also: - setContinuous:



isEditable

- (BOOL)isEditable

Returns whether the receiving cell is editable.

See Also: - setEditable:



isEnabled

- (BOOL)isEnabled

Returns whether the receiving cell responds to mouse events.

See Also: - setEnabled:



isEntryAcceptable:

- (BOOL)isEntryAcceptable:(NSString *)aString

Returns whether a string representing a numeric or date value (aString) is formatted in a way suitable to the entry type.
Note: This method is being deprecated in favor of a new class of formatter objects. For more information, see NSFormatter. This documentation is provided only for developers who need to modify older applications.

See Also: - entryType, - setEntryType:



isHighlighted

- (BOOL)isHighlighted

Returns whether the receiving cell is highlighted.

isOpaque

- (BOOL)isOpaque

Returns whether the receiving cell is opaque (non-transparent).

isScrollable

- (BOOL)isScrollable

Returns whether the receiving cell scrolls typed text that exceeds the cell's bounds.

See Also: - setScrollable:



isSelectable

- (BOOL)isSelectable

Returns whether the text of the receiving cell can be selected.

See Also: - setSelectable:



keyEquivalent

- (NSString *)keyEquivalent

Implemented by subclasses to return a key equivalent to clicking the cell. The default implementation returns an empty string object.

menu

- (NSMenu *)menu

Returns the menu with commands contextually related to the cell or nil if no menu is associated.

See Also: - setMenu:



menuForEvent:inRect:ofView:

- (NSMenu *)menuForEvent:(NSEvent *)anEvent inRect:(NSRect)cellFrame ofView:(NSView *)aView

Returns the NSMenu associated with the receiver through the setMenu: method and related to anEvent when the mouse is detected within cellFrame. It is usually invoked by the NSControl (aView) managing the receiver. The default implementation simply invokes menu and returns nil if no menu has been set. Subclasses can override to customize the returned menu according to the event received and the area in which the mouse event occurs.

mnemonic

- (NSString *)mnemonic

Returns the character in the cell title that appears underlined for use as a mnemonic. If there is no mnemonic character, returns an empty string.

See Also: - setTitleWithMnemonic:



mnemonicLocation

- (unsigned)mnemonicLocation

Returns the position of the underlined character in the cell title used as a mnemonic. If there is no mnemonic character, returns NSNotFound.

See Also: - setMnemonicLocation:



mouseDownFlags

- (int)mouseDownFlags

Returns the modifier flags for the last (left) mouse-down event, or zero if tracking hasn't occurred yet for the cell or no modifier keys accompanied the mouse-down event.

See Also: - modifierFlags (NSEvent)



nextState

- (int)nextState

Returns the button's next state. If the button has three states, it cycles through them in this order: on, off, mixed, on, and so forth. If the button has two states, it toggles between them.

See Also: - allowsMixedState, - setAllowsMixedState:, - setNextState



objectValue

- (id <NSCopying>)objectValue

Returns the NSCell's value as an Objective-C object if a valid object has been associated with the receiver; otherwise, returns nil. To be valid, the cell must have a formatter capable of converting the object to and from its textual representation.

performClick:

- (void)performClick:(id)sender

Programmatically simulates a mouse click on the receiver, including the invocation of the action method in the target object. Raises an exception if the action message cannot be successfully sent.

refusesFirstResponder

- (BOOL)refusesFirstResponder

Returns YES if the cell can never become the first responder. To find out whether the cell can become first responder at this time, use the method acceptsFirstResponder.

See Also: - setRefusesFirstResponder:



representedObject

- (id)representedObject

Returns the object the receiving cell represents. For example, you could have a pop-up list of color names, and the represented objects could be the appropriate NSColor objects.

See Also: - setRepresentedObject:



resetCursorRect:inView:

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

Sets the receiver to show the I-beam cursor within cellFrame while it tracks the mouse. The receiver must be an enabled and selectable (or editable) text-type cell. controlView is the NSControl that manages the cell.

selectWithFrame:inView:editor:delegate:start:length:

- (void)selectWithFrame:(NSRect)aRect inView:(NSView *)controlView editor:(NSText *)textObj delegate:(id)anObject start:(int)selStart length:(int)selLength

Uses the field editor textObj to select text in a range marked by selStart and selLength, which will be highlighted and selected as though the user had dragged the cursor over it. This method is similar to editWithFrame:inView:editor:delegate:event:, except that it can be invoked in any situation, not only on a mouse-down event. aRect is the rectangle in which the selection should occur, controlView is the NSControl managing the receiver, and anObject is the delegate of the field editor. Returns without doing anything if controlView, textObj, or the receiver are nil, or if the receiver has no font set for it.

sendActionOn:

- (int)sendActionOn:(int)mask

Sets the conditions on which the receiver sends action messages to its target and returns a bit mask with which to detect the previous settings. mask is set with one or more of these bit masks:
Value Description
NSLeftMouseUpMask Don't send action message on (left) mouse up.
NSLeftMouseDownMask Send action message on (left) mouse down.
NSLeftMouseDraggedMask Send action message when (left) mouse is dragged.
NSPeriodicMask Send action message continuously.

You can use setContinuous: to turn on the flag corresponding to NSPeriodicMask or NSLeftMouseDraggedMask, whichever is appropriate to the given subclass of NSCell.

See Also: - action



sendsActionOnEndEditing

- (BOOL)sendsActionOnEndEditing

Returns whether the cell sends its action message whenever the user finishes editing the cell's text. If it returns YES, the cell sends its action message when the user does one of the following:

This behavior is familiar to Mac OS users.

If it returns NO, the cell sends its action message only when the user presses the Return key.



setAction:

- (void)setAction:(SEL)aSelector

In NSCell, raises NSInternalInconsistencyException. However, NSActionCell overrides this method to set the action method as part of the implementation of the target/action mechanism.

See Also: - action, - setTarget:, - target



setAlignment:

- (void)setAlignment:(NSTextAlignment)mode

Sets the alignment of text in the receiver. mode is one of five constants: NSLeftTextAlignment, NSRightTextAlignment, NSCenterTextAlignment, NSJustifiedTextAlignment, NSNaturalTextAlignment (the default alignment for the text).

See Also: - alignment, - setWraps:



setAllowsEditingTextAttributes:

- (void)setAllowsEditingTextAttributes:(BOOL)flag

Sets whether the textual attributes of the receiver can be modified by the user. If flag is NO, the receiver also cannot import graphics (that is, it does not support RTFD text).

See Also: - allowsEditingTextAttributes, - setImportsGraphics:



setAllowsMixedState:

- (void)setAllowsMixedState:(BOOL)flag

If flag is YES, the button has three states: on, off, and mixed. If flag is NO, the button has two states: on and off.

See Also: - allowsMixedState, - nextState, - setNextState



setAttributedStringValue:

- (void)setAttributedStringValue:(NSAttributedString *)attribStr

Sets the value of the receiver to the attributed string attribStr. If a formatter is set for the receiver, but the formatter does not understand the attributed string, it marks attribStr as an invalid object. If the receiver is not a text-type cell, it's converted to one. The following example sets the text in a cell to 14 points, red, in the system font.
    NSColor *txtColor = [NSColor redColor];
    NSFont *txtFont = [NSFont boldSystemFontOfSize:14];
    NSDictionary *txtDict = [NSDictionary dictionaryWithObjectsAndKeys:txtFont,
        NSFontAttributeName, txtColor, NSForegroundColorAttributeName, nil];
    NSAttributedString *attrStr = [[[NSAttributedString alloc]
        initWithString:@"Hello!" attributes:txtDict] autorelease];
    [[attrStrTextField cell] setAttributedStringValue:attrStr];
    [attrStrTextField updateCell:[attrStrTextField cell]];

See Also: - attributedStringValue



setBezeled:

- (void)setBezeled:(BOOL)flag

Sets whether the receiver draws itself with a bezeled border. The setBezeled: and setBordered: methods are mutually exclusive (that is, a border can be only plain or bezeled).

See Also: - isBezeled



setBordered:

- (void)setBordered:(BOOL)flag

Sets whether the receiver draws itself outlined with a plain border. The setBezeled: and setBordered: methods are mutually exclusive (that is, a border can be only plain or bezeled).

See Also: - isBordered



setCellAttribute:to:

- (void)setCellAttribute:(NSCellAttribute)aParameter to:(int)value

Sets a cell attribute identified by aParameter-such as the receiver's state, and whether it's disabled, editable, or highlighted-to value.

See Also: - cellAttribute:



setContinuous:

- (void)setContinuous:(BOOL)flag

Sets whether the receiver continuously sends its action message to its target while it tracks the mouse. In practice, the continuous setting has meaning only for instances of NSActionCell and its subclasses, which implement the target/action mechanism. Some NSControl subclasses, notably NSMatrix, send a default action to a default target when a cell doesn't provide a target or action.

See Also: - isContinuous, - sendActionOn:



setDoubleValue:

- (void)setDoubleValue:(double)aDouble

Sets the value of the receiving cell to an object representing a double. In its implementation, this method invokes setObjectValue:. Does nothing if the receiver is not a text-type cell.

See Also: - doubleValue



setEditable:

- (void)setEditable:(BOOL)flag

Sets whether the user can edit the receiver's text. If flag is YES, the text can also be selected. If flag is NO, the selectable attribute is restored to what it was before the cell was last made editable.

See Also: - isEditable, - setSelectable:



setEnabled:

- (void)setEnabled:(BOOL)flag

Sets whether the receiver is enabled or disabled. The text of disabled cells is changed to gray. If a cell is disabled, it cannot be highlighted, does not support mouse tracking (and thus cannot participate in target/action functionality), and cannot be edited. However, you can still alter many attributes of a disabled cell programmatically ( setState:, for instance, will still work).

See Also: - isEnabled



setEntryType:

- (void)setEntryType:(int)aType

Sets how numeric data are formatted in the receiver and places restrictions on acceptable input. aType can be one of the following constants:
Constant Restrictions and Other Information
NSIntType Must be between INT_MIN and INT_MAX
NSPositiveIntType Must be between 1 and INT_MAX
NSFloatType Must be between -FLT_MAX and FLT_MAX
NSPositiveFloatType Must be between FLT_MIN and FLT_MAX
NSDoubleType Must be between -DBL_MAX and DBL_MAX
NSPositiveDoubleType Must be between DBL_MAX and DBL_MAX
NSAnyType Any value is allowed.

If the receiver isn't a text-type cell, this method converts it to one; in the process, it makes its title "Cell" and sets its font to the user's system font at 12 points.

You can check whether formatted strings conform to the entry types of cells with the isEntryAcceptable: method. NSControl subclasses also use isEntryAcceptable: to validate what users have typed in editable cells. You can control the format of values accepted and displayed in cells by creating a custom subclass of NSFormatter and associating an instance of that class with cells (through setFormatter:). In custom NSCell subclasses, you can also override isEntryAcceptable: to check for the validity of data entered into cells.


Note: This method is being deprecated in favor of a new class of formatter objects. For more information, see NSFormatter. This documentation is provided only for developers who need to modify older applications.

See Also: - entryType



setFloatingPointFormat:left:right:

- (void)setFloatingPointFormat:(BOOL)autoRange left:(unsigned)leftDigits right:(unsigned)rightDigits

Sets whether floating-point numbers are autoranged in the receiver, and sets the sizes of the fields to the left and right of the decimal point. If autoRange is NO, leftDigits specifies the maximum number of digits to the left of the decimal point, and rightDigits specifies the number of digits to the right (the fractional digit places will be padded with zeros to fill this width). However, if a number is too large to fit its integer part in leftDigits digits, as many places as are needed on the left are effectively removed from rightDigits when the number is displayed.

If autoRange is YES, leftDigits and rightDigits are simply added to form a maximum total field width for the receiver (plus 1 for the decimal point). The fractional part will be padded with zeros on the right to fill this width, or truncated as much as possible (up to removing the decimal point and displaying the number as an integer). The integer portion of a number is never truncated-that is, it is displayed in full no matter what the field width limit is.

The following example sets a cell used to display dollar amounts up to 99,999.99:

    [[currencyDollarsField cell] setEntryType:NSFloatType];
    [[currencyDollarsField cell] setFloatingPointFormat:NO left:5 right:2]; 


Note: This method is being deprecated in favor of a new class of formatter objects. For more information, see NSFormatter. This documentation is provided only for developers who need to modify older applications.

See Also: - setEntryType:



setFloatValue:

- (void)setFloatValue:(float)aFloat

Sets the value of the receiving cell to an object representing a float. In its implementation, this method invokes setObjectValue:. Does nothing if the receiver is not a text-type cell.

See Also: - floatValue



setFont:

- (void)setFont:(NSFont *)fontObj

Sets the font to be used when the receiver displays text. If the receiver is not a text-type cell, the method converts it to that type. If fontObj is nil and the receiver is a text-type cell, the font currently held by the receiver is autoreleased.

See Also: - font



setFormatter:

- (void)setFormatter:(NSFormatter *)newFormatter

Sets the formatter object used to format the textual representation of the receiver's object value and to validate cell input and convert it to that object value. If the new formatter cannot interpret the receiver's current object value, that value is converted to a string object. This method retains new formatters and releases replaced ones. If newFormatter is nil, the receiver is disassociated from the current formatter.

See Also: - formatter



setImage:

- (void)setImage:(NSImage *)image

Sets the image to be displayed by the receiver. If the receiver is not an image-type cell, the method converts it to that type. If image is nil and the receiver is an image-type cell, the image currently held by the receiver is autoreleased.

See Also: - image



setImportsGraphics:

- (void)setImportsGraphics:(BOOL)flag

Sets whether the receiver can import images into its text (that is, whether it supports RTFD text). If flag is YES, the receiver is also set to allow editing of text attributes ( setAllowsEditingTextAttributes:).

See Also: - importsGraphics



setIntValue:

- (void)setIntValue:(int)anInt

Sets the value of the receiving cell to an object representing an int. In its implementation, this method invokes setObjectValue:. Does nothing if the receiver is not a text-type cell.

See Also: - intValue



setMenu:

- (void)setMenu:(NSMenu *)aMenu

Associates a menu with the cell that has commands contextually related to the cell. The associated menu is retained. If aMenu is nil, any association with a previous menu is removed.

See Also: - menu



setMnemonicLocation:

- (void)setMnemonicLocation:(unsigned)location

Sets the character of the cell title identified by location to be underlined. This character identifies the access key by which users can access the cell. location must be between 0 and 254.

See Also: - mnemonicLocation



setNextState

- (void)setNextState

Sets the button to its next state. If the button has three states, it cycles through them in this order: on, off, mixed, on, and so forth. If the button has two states, it toggles between them.

See Also: - allowsMixedState, - nextState, - setAllowsMixedState:



setObjectValue:

- (void)setObjectValue:(id)object

Sets the receiver's object value to object.

See Also: - objectValue, - setRepresentedObject:



setRefusesFirstResponder:

- (void)setRefusesFirstResponder:(BOOL)flag

Sets whether the cell can become the first responder. If flag is YES, the cell cannot become the first responder.

If refusesFirstResponder returns NO and the cell is enabled, the method acceptsFirstResponder returns YES, allowing the cell to become first responder



setRepresentedObject:

- (void)setObjectValue:(id <NSCopying>)anObject

Sets the object represented by the receiver. For example, an NSColor object for a cell with a title of "Blue."

See Also: - setObjectValue:, - representedObject



setScrollable:

- (void)setScrollable:(BOOL)flag

Sets whether excess text in the receiver is scrolled past the cell's bounds. If flag is YES, wrapping is turned off. When the scrollable attribute is turned on, the alignment of text in the cell is changed to left alignment.

See Also: - isScrollable



setSelectable:

- (void)setSelectable:(BOOL)flag

Sets whether text in the receiver can be selected; always makes the receiver's text uneditable.

See Also: - isSelectable, - setEditable:



setSendsActionOnEndEditing:

- (void)setSendsActionOnEndEditing:(BOOL)flag

Sets whether the cell sends its action message whenever the user finishes editing the cell's text. If flag is YES, the cell sends its action message when the user does one of the following:

This behavior is familiar to Mac OS users.

If flag is NO, the cell sends its action message only when the user presses the Return key.



setShowsFirstResponder:

- (void)setShowsFirstResponder:(BOOL)flag

Sets whether the receiver displays a dotted-line outline when it assumes first responder status.

See Also: - showsFirstResponder



setState:

- (void)setState:(int)value

Sets the cell's state to value, which can be NSOnState, NSOffState, or NSMixedState.

The cell can have two or three states. If it has two, value can be NSOffState (the normal or unpressed state) or NSOnState (the alternate or pressed state). If it has three, value can be NSOnState (the feature is in effect everywhere), NSOffState (the feature is in effect nowhere), or NSMixedState (the feature is in effect somewhere). Note that if the cell has only two states and value is NSMixedState, this method sets the cell's state to NSOnState.

Although using the enumerated constants is preferred, value can also be an integer. If the cell has two states, zero is treated as NSOffState, and a non-zero value is treated as NSOnState. If the cell has three states, zero is treated as NSOffState; a negative value, as NSMixedState; and a positive value, as NSOnState.

Note that the value state returns may not be the same value you passed into setState:.

To check whether the cell has three states (and uses the mixed state), invoke the method allowsMixedState.

See Also: - state



setStringValue:

- (void)setStringValue:(NSString *)aString

Sets the value of the receiving cell to aString. In its implementation, this method invokes setObjectValue:. If no formatter is assigned to the receiver or if the formatter cannot "translate" aString to an underlying object, the receiver is flagged as having an invalid object. If the receiver is not a text-type cell, this method converts it to one before setting the object value.

See Also: - stringValue



setTag:

- (void)setTag:(int)anInt

Implemented by NSActionCell to set the receiver's tag integer. NSCell's implementation raises NSInternalInconsistencyException.

See Also: - tag



setTarget:

- (void)setTarget:(id)anObject

Implemented by NSActionCell to set the receiver's target object receiving the action message. NSCell's implementation raises NSInternalInconsistencyException.

See Also: - target



setTitleWithMnemonic:

- (void)setTitleWithMnemonic:(NSString *)aString

Sets the title of a cell with a character denoted as an access key. Use an ampersand character to mark the character (the one following the ampersand) to be designated. For example, the following message causes the "c" in "Receive" to be designated:
[aCell setTitleWithMnemonic:NSLocalizedString(@"Re&ceive")];

See Also: - mnemonic, - setMnemonicLocation:



setType:

- (void)setType:(NSCellType)aType

If the type of the receiving cell is different from aType, sets it to aType, which must one of NSTextCellType, NSImageTypeCell, or NSNullCellType. If aType is NSTextCellType, converts the receiver to a cell of that type, giving it a default title and setting the font to the system font at the default size. If aType is NSImageTypeCell, sets a nil image.

See Also: - type



setUpFieldEditorAttributes:

- (NSText *)setUpFieldEditorAttributes:(NSText *)textObj

Sets textual and background attributes of the receiver, depending on certain attributes. If the receiver is disabled, sets the text color to dark gray; otherwise sets it to the default color. If the receiver has a bezeled border, sets the background to the default color for text backgrounds; otherwise, sets it to the color of the receiver's NSControl.

setWraps:

- (void)setWraps:(BOOL)flag

Sets whether text in the receiver wraps when its length exceeds the frame of the cell. If flag is YES, then it also sets the receiver to be non-scrollable.

See Also: - wraps



showsFirstResponder

- (BOOL)showsFirstResponder

Returns whether the receiver displays a dotted-line outline when it assumes first responder status.

See Also: - setShowsFirstResponder:



startTrackingAt:inView:

- (BOOL)startTrackingAt:(NSPoint)startPoint inView:(NSView *)controlView

NSCell's implementation of trackMouse:inRect:ofView:untilMouseUp: invokes this method when tracking begins. startPoint is the point the mouse is currently at and controlView is the NSControl managing the receiver. NSCell's default implementation returns YES if the receiver is set to respond continuously or when the mouse is dragged. Subclasses override this method to implement special mouse-tracking behavior at the beginning of mouse tracking-for example, displaying a special cursor.

See Also: - continueTracking:at:inView:, - stopTracking:at:inView:mouseIsUp:



state

- (int)state

Returns the button's state. The cell can have two or three states. If it has two, it returns either NSOffState (the normal or unpressed state) or NSOnState (the alternate or pressed state). If it has three, it returns NSOnState (the feature is in effect everywhere), NSOffState (the feature is in effect nowhere), or NSMixedState (the feature is in effect somewhere).

To check whether the button uses the mixed state, use the method allowsMixedState.

Note that the value state returns may not be the same value you passed into setState:.

See Also: - setState:



stopTracking:at:inView:mouseIsUp:

- (void)stopTracking:(NSPoint)lastPoint at:(NSPoint)stopPoint inView:(NSView *)controlView mouseIsUp:(BOOL)flag

NSCell's implementation of trackMouse:inRect:ofView:untilMouseUp: invokes this method when the mouse has left the bounds of the receiver or the mouse goes up (in which case flag is YES). lastPoint is the point the mouse was at and stopPoint is its current point. controlView is the NSControl managing the receiver. NSCell's default implementation does nothing. Subclasses often override this method to provide customized tracking behavior. The following example increments the state of a tri-state cell when the mouse is clicked.
- (void)stopTracking:(NSPoint)lastPoint at:(NSPoint)stopPoint 
    inView:(NSView *)controlView mouseIsUp:(BOOL)flag
{
    if (flag == YES) {
        [self setTriState:([self triState]+1)];
    }
}

See Also: - startTrackingAt:inView:, - stopTracking:at:inView:mouseIsUp:



stringValue

- (NSString *)stringValue

Returns the receiver's value as an NSString as converted by the receiver's formatter, if one exists. If no formatter exists and the value is an NSString, returns the value as an plain, attributed or localized formatted string. If the value is not an NSString or can't be converted to one, returns an empty string.

See Also: - setStringValue:



tag

- (int)tag

Implemented by NSActionCell to return the receiver's tag integer. NSCell's implementation returns -1.

See Also: - setTag:



takeDoubleValueFrom:

- (void)takeDoubleValueFrom:(id)sender

Sets the receiver's own value as a double using the double value of sender.

See Also: - setDoubleValue:



takeFloatValueFrom:

- (void)takeFloatValueFrom:(id)sender

Sets the receiver's own value as a float using the float value of sender.

See Also: - setFloatValue:



takeIntValueFrom:

- (void)takeIntValueFrom:(id)sender

Sets the receiver's own value as an int using the int value of sender. The following example shows this method being used to write the value taken from a slider (sender) to a text field cell:
- (void)sliderMoved:(id)sender
{
    [[valueField cell] takeIntValueFrom:[sender cell]];
    [valueField display];
}

See Also: - setIntValue:



takeObjectValueFrom:

- (void)takeObjectValueFrom:(id)sender

Sets the receiver's own value as an object using the object value of sender.

See Also: - setObjectValue:



takeStringValueFrom:

- (void)takeStringValueFrom:(id)sender

Sets the receiver's own value as a string object using the NSString value of sender.

See Also: - setStringValue:



target

- (id)target

Implemented by NSActionCell to return the target object to which the receiver's action message is sent. NSCell's implementation returns nil.

See Also: - setTarget:



titleRectForBounds:

- (NSRect)titleRectForBounds:(NSRect)theRect

If the receiver is a text-type cell, resizes the drawing rectangle for the title (theRect) inward by a small offset to accommodate the cell border. If the receiver is not a text-type cell, the method does nothing.

See Also: - imageRectForBounds:



trackMouse:inRect:ofView:untilMouseUp:

- (BOOL)trackMouse:(NSEvent *)theEvent inRect:(NSRect)cellFrame ofView:(NSView *)controlView untilMouseUp:(BOOL)untilMouseUp

Invoked by an NSControl to initiate the tracking behavior of one of its NSCells. It's generally not overridden because the default implementation invokes other NSCell methods that can be overridden to handle specific events in a dragging session. This method's return value depends on the untilMouseUp flag. If that flag is set to YES, this method returns YES if the mouse goes up anywhere; NO, otherwise. If that flag is set to NO, this method returns YES if the mouse goes up within cellFrame; NO, otherwise. The argument theEvent is typically the mouse event received by the initiating NSControl, usually identified by controlView. The untilMouseUp argument indicates whether tracking should continue until the mouse button goes up; if it's NO, tracking ends when the mouse is dragged after the initial mouse down.

This method first invokes startTrackingAt:inView:. If that method returns YES, then as mouse-dragged events are intercepted, continueTracking:at:inView: is invoked. Finally, stopTracking:at:inView:mouseIsUp: is invoked. If untilMouseUp is YES, it's invoked when the mouse goes up anywhere, If untilMouseUp is NO, it's invoked when the mouse goes up within cellFrame. (If cellFrame is nil, then the bounds are considered infinitely large.) You usually override one or more of these methods to respond to specific mouse events.



type

- (NSCellType)type

Returns the type of the receiver, one of NSTextCellType, NSImageTypeCell, or NSNullCellType.

See Also: - setType:



wraps

- (BOOL)wraps

Returns whether text of the receiver wraps when it exceeds the borders of the cell.

See Also: - setWraps:




Table of Contents