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

Table of Contents

NSCell


Inherits from:
NSObject
Package:
com.apple.yellow.application


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 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 a String, 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. 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-OnState and OffState-or three states-OnState, OffState, and MixedState. 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 startTrackingMouse, continueTrackingMouse, and stopTrackingMouse. If you want to implement your own drawing, override drawWithFrameInView or drawInteriorWithFrameInView.

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
IntType Must be between INT_MIN and INT_MAX
PositiveIntType Must be between 1 and INT_MAX
FloatType Must be between -FLT_MAX and FLT_MAX
PositiveFloatType Must be between FLT_MIN and FLT_MAX
DoubleType Must be between -DBL_MAX and DBL_MAX
PositiveDoubleType Must be between DBL_MAX and DBL_MAX
AnyType Any value is allowed.

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


Constant Description
NullCellType Description forthcoming.
TextCellType Description forthcoming.
ImageCellType 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
CellDisabled Description forthcoming.
CellState Description forthcoming.
PushInCell Description forthcoming.
CellEditable Description forthcoming.
ChangeGrayCell Description forthcoming.
CellHighlighted Description forthcoming.
CellLightsByContents Description forthcoming.
CellLightsByGray Description forthcoming.
ChangeBackgroundCell Description forthcoming.
CellLightsByBackground Description forthcoming.
CellIsBordered Description forthcoming.
CellHasOverlappingImage Description forthcoming.
CellHasImageHorizontal Description forthcoming.
CellHasImageOnLeftOrBottom Description forthcoming.
CellChangesContents Description forthcoming.
CellIsInsetButton Description forthcoming.
CellAllowsMixedState 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
NoImage The cell doesn't display an image
ImageOnly The cell displays an image, but not a title
ImageLeft The image is to the left of the title
ImageRight The image is to the right of the title
ImageBelow The image is below the title
ImageAbove The image is above the title
ImageOverlaps 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
MixedState The corresponding feature is in effect somewhere.
OffState The corresponding feature is in effect nowhere.
OnState 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
NoCellMask The button cell doesn't change.
PushInCellMask The button cell "pushes in" if it has a border.
ContentsCellMask The button cell displays its alternate icon and/or title.
ChangeGrayCellMask The button cell swaps the "control color" (NSColor's controlColor) and white pixels on the its background and icon.
ChangeBackgroundCellMask Same as ChangeGrayCellMask, but only background pixels are changed.



Method Types


Constructors
NSCell
Setting and getting cell values
setObjectValue
objectValue
hasValidObjectValue
setIntValue
intValue
setStringValue
stringValue
setDoubleValue
doubleValue
setFloatValue
floatValue
Setting and getting cell attributes
setCellAttribute
cellAttribute
setType
int
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
setEventMaskForSendingAction
Setting and getting an image
setImage
image
Assigning a tag
setTag
tag
Formatting and validating data
setFormatter
formatter
setEntryType
entryType
isEntryAcceptable
setFloatingPointFormat
Managing menus for cells
defaultMenu
setMenu
menu
menuForEvent
Comparing cells
compare
Making cells respond to keyboard events
acceptsFirstResponder
setShowsFirstResponder
showsFirstResponder
setTitleWithMnemonic
mnemonic
refusesFirstResponder
setMnemonicLocation
setRefusesFirstResponder
mnemonicLocation
performClick
Deriving values from other cells
takeObjectValue
takeIntValue
takeStringValue
takeDoubleValue
takeFloatValue
Representing an object with a cell
setRepresentedObject
representedObject
Tracking the mouse
trackMouse
startTrackingMouse
continueTrackingMouse
stopTrackingMouse
mouseDownFlags
prefersTrackingUntilMouseUp
Managing the cursor
resetCursorRect
Managing cell messaging
interval
periodicDelay
Handling keyboard alternatives
keyEquivalent
Determining cell sizes
calcDrawInfo
cellSize
cellSizeForBounds
drawingRectForBounds
imageRectForBounds
titleRectForBounds
Drawing and highlighting cells
drawWithFrameInView
drawInteriorWithFrameInView
controlView
highlightWithFrameInView
isHighlighted
Editing and selecting cell text
editWithFrameInView
selectAndEditWithFrameInView
sendsActionOnEndEditing
setSendsActionOnEndEditing
endEditing


Constructors



NSCell

public NSCell()

Description forthcoming.

public NSCell(String aString)

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

public NSCell(NSImage anImage)

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


Static Methods



defaultMenu

public static NSMenu defaultMenu()

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

See Also: menu, setMenu



prefersTrackingUntilMouseUp

public static boolean prefersTrackingUntilMouseUp()

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

See Also: trackMouse




Instance Methods



acceptsFirstResponder

public boolean acceptsFirstResponder()

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

See Also: performClick, setShowsFirstResponder, setTitleWithMnemonic



action

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

public int alignment()

Returns the alignment of text in the cell: LeftTextAlignment, RightTextAlignment, CenterTextAlignment, JustifiedTextAlignment, or NaturalTextAlignment.

See Also: setAlignment



allowsEditingTextAttributes

public boolean allowsEditingTextAttributes()

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

See Also: setAllowsEditingTextAttributes



allowsMixedState

public boolean allowsMixedState()

Returns true if the button has three states: on, off, and mixed. Returns false if the button has two states: on and off.

See Also: nextState, setAllowsMixedState, setNextState



attributedStringValue

public 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

public 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

public int cellAttribute(int 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



cellSize

public 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

public 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

public int compare(Object otherCell)

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

continueTrackingMouse

public boolean continueTrackingMouse( NSPoint lastPoint, NSPoint currentPoint, 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. The default implementation returns true 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: startTrackingMouse, stopTrackingMouse



controlView

public NSView controlView()

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

See Also: drawWithFrameInView



doubleValue

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

drawInteriorWithFrameInView

public void drawInteriorWithFrameInView( NSRect cellFrame, 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 drawWithFrameInView invokes drawInteriorWithFrameInView: after it draws the NSCell's border, don't invoke drawWithFrameInView in your override implementation.

See Also: isHighlighted, setShowsFirstResponder



drawWithFrameInView

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

drawingRectForBounds

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



editWithFrameInView

public void editWithFrameInView( NSRect aRect, NSView controlView, NSText textObj, Object anObject, 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 LeftMouseDown 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, selectAndEditWithFrameInView



endEditing

public void endEditing(NSText textObj)

Ends any editing of text occurring in the receiver begun with editWithFrameInView and selectAndEditWithFrameInView.

entryType

public 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, AnyType is returned. See setEntryType for a list of type constants.

See Also: isEntryAcceptable



floatValue

public 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

public NSFont font()

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

See Also: setFont



formatter

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



hasValidObjectValue

public boolean 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 controlDidFailToFormatStringErrorDescription).

See Also: objectValue, setObjectValue



highlightWithFrameInView

public void highlightWithFrameInView( boolean flag, NSRect cellFrame, NSView controlView)

If the receiver's highlight status is different from flag, sets that status to flag and, if flag is true, 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: drawWithFrameInView, isHighlighted



image

public NSImage image()

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

See Also: setImage



imageRectForBounds

public 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

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



int

public int int()

Description forthcoming.

interval

public float interval()

Returns the amount of time that the cell pauses between messages when it's sending action messages continuously to target objects. Override this method to supply your own interval value.

See Also: periodicDelay



intValue

public 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

public boolean isBezeled()

Returns whether the receiving cell has a bezeled border.

See Also: setBezeled



isBordered

public boolean isBordered()

Returns whether the receiving cell has a plain border.

See Also: setBordered



isContinuous

public boolean isContinuous()

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

See Also: setContinuous



isEditable

public boolean isEditable()

Returns whether the receiving cell is editable.

See Also: setEditable



isEnabled

public boolean isEnabled()

Returns whether the receiving cell responds to mouse events.

See Also: setEnabled



isEntryAcceptable

public boolean isEntryAcceptable(String 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

public boolean isHighlighted()

Returns whether the receiving cell is highlighted.

isOpaque

public boolean isOpaque()

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

isScrollable

public boolean isScrollable()

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

See Also: setScrollable



isSelectable

public boolean isSelectable()

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

See Also: setSelectable



keyEquivalent

public String keyEquivalent()

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

menu

public NSMenu menu()

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

See Also: setMenu



menuForEvent

public NSMenu menuForEvent( NSEvent anEvent, NSRect cellFrame, 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 null 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

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

public int mnemonicLocation()

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

See Also: setMnemonicLocation



mouseDownFlags

public 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

public 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

public Object objectValue()

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

performClick

public void performClick(Object 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.

periodicDelay

public float periodicDelay()

Returns the amount of time that the cell pauses before sending its first message when it's sending action messages continuously to target objects. Override this method to supply your own delay value.

See Also: interval



refusesFirstResponder

public boolean refusesFirstResponder()

Returns true 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

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

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

selectAndEditWithFrameInView

public void selectAndEditWithFrameInView( NSRect aRect, NSView controlView, NSText textObj, Object anObject, int selStart, 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 editWithFrameInView, 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 null, or if the receiver has no font set for it.

setEventMaskForSendingAction

public int setEventMaskForSendingAction(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
LeftMouseUpMask Don't send action message on (left) mouse up.
LeftMouseDownMask Send action message on (left) mouse down.
LeftMouseDraggedMask Send action message when (left) mouse is dragged.
PeriodicMask Send action message continuously.

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

See Also: action



sendsActionOnEndEditing

public boolean sendsActionOnEndEditing()

Returns whether the cell sends its action message whenever the user finishes editing the cell's text. If it returns true, 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 false, the cell sends its action message only when the user presses the Return key.



setAction

public void setAction(NSSelector aSelector)

In NSCell, throws InternalInconsistencyException. 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

public void setAlignment(int mode)

Sets the alignment of text in the receiver. mode is one of five constants: LeftTextAlignment, RightTextAlignment, CenterTextAlignment, JustifiedTextAlignment, NaturalTextAlignment (the default alignment for the text).

See Also: alignment, setWraps



setAllowsEditingTextAttributes

public void setAllowsEditingTextAttributes(boolean flag)

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

See Also: allowsEditingTextAttributes, setImportsGraphics



setAllowsMixedState

public void setAllowsMixedState(boolean flag)

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

See Also: allowsMixedState, nextState, setNextState



setAttributedStringValue

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

See Also: attributedStringValue



setBezeled

public void setBezeled(boolean 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

public void setBordered(boolean 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

public void setCellAttribute( int aParameter, 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

public void setContinuous(boolean 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, setEventMaskForSendingAction



setDoubleValue

public 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

public void setEditable(boolean flag)

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

See Also: isEditable, setSelectable



setEnabled

public void setEnabled(boolean 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

public 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
IntType Must be between INT_MIN and INT_MAX
PositiveIntType Must be between 1 and INT_MAX
FloatType Must be between -FLT_MAX and FLT_MAX
PositiveFloatType Must be between FLT_MIN and FLT_MAX
DoubleType Must be between -DBL_MAX and DBL_MAX
PositiveDoubleType Must be between DBL_MAX and DBL_MAX
AnyType 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

public void setFloatingPointFormat( boolean autoRange, int leftDigits, int 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 false, 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 true, 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.

See Also: setEntryType



setFloatValue

public 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

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

See Also: font



setFormatter

public 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. If newFormatter is null, the receiver is disassociated from the current formatter.

See Also: formatter



setImage

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

See Also: image



setImportsGraphics

public void setImportsGraphics(boolean flag)

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

See Also: importsGraphics



setIntValue

public 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

public 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 null, any association with a previous menu is removed.

See Also: menu



setMnemonicLocation

public void setMnemonicLocation(int 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

public 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

public void setObjectValue(Object object)

Sets the receiver's object value to object.

See Also: objectValue, setRepresentedObject



setRefusesFirstResponder

public void setRefusesFirstResponder(boolean flag)

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

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



setRepresentedObject

public void setRepresentedObject(Object 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

public void setScrollable(boolean flag)

Sets whether excess text in the receiver is scrolled past the cell's bounds. If flag is true, 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

public void setSelectable(boolean flag)

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

See Also: isSelectable, setEditable



setSendsActionOnEndEditing

public void setSendsActionOnEndEditing(boolean flag)

Sets whether the cell sends its action message whenever the user finishes editing the cell's text. If flag is true, 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 false, the cell sends its action message only when the user presses the Return key.



setShowsFirstResponder

public void setShowsFirstResponder(boolean flag)

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

See Also: showsFirstResponder



setState

public void setState(int value)

Sets the cell's state to value, which can be OnState, OffState, or MixedState.

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

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

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

public void setStringValue(String 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

public void setTag(int anInt)

Implemented by NSActionCell to set the receiver's tag integer. NSCell's implementation throws InternalInconsistencyException.

See Also: tag



setTarget

public void setTarget(Object anObject)

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

See Also: target



setTitleWithMnemonic

public void setTitleWithMnemonic(String 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.

See Also: mnemonic, setMnemonicLocation



setType

public void setType(int aType)

If the type of the receiving cell is different from aType, sets it to aType, which must one of TextCellType, ImageTypeCell, or NullCellType. If aType is TextCellType, 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 ImageTypeCell, sets a null image.

See Also: type



setUpFieldEditorAttributes

public 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

public void setWraps(boolean flag)

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

See Also: wraps



showsFirstResponder

public boolean showsFirstResponder()

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

See Also: setShowsFirstResponder



startTrackingMouse

public boolean startTrackingMouse( NSPoint startPoint, NSView controlView)

NSCell's implementation of trackMouse 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 true 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: continueTrackingMouse, stopTrackingMouse



state

public 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 OnState (the alternate or pressed state). If it has three, it returns OnState (the feature is in effect everywhere), OffState (the feature is in effect nowhere), or MixedState (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



stopTrackingMouse

public void stopTrackingMouse( NSPoint lastPoint, NSPoint stopPoint, NSView controlView, boolean flag)

NSCell's implementation of trackMouse invokes this method when the mouse has left the bounds of the receiver or the mouse goes up (in which case flag is true). 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.

See Also: startTrackingMouse, stopTrackingMouse



stringValue

public String stringValue()

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

See Also: setStringValue



tag

public int tag()

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

See Also: setTag



takeDoubleValue

public void takeDoubleValue(Object sender)

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

See Also: setDoubleValue



takeFloatValue

public void takeFloatValue(Object sender)

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

See Also: setFloatValue



takeIntValue

public void takeIntValue(Object sender)

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

See Also: setIntValue



takeObjectValue

public void takeObjectValue(Object sender)

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

See Also: setObjectValue



takeStringValue

public void takeStringValue(Object sender)

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

See Also: setStringValue



target

public Object target()

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

See Also: setTarget



titleRectForBounds

public 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

public boolean trackMouse( NSEvent theEvent, NSRect cellFrame, NSView controlView, boolean 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 true, this method returns true if the mouse goes up anywhere; false, otherwise. If that flag is set to false, this method returns true if the mouse goes up within cellFrame; false, 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 false, tracking ends when the mouse is dragged after the initial mouse down.

This method first invokes startTrackingMouse. If that method returns true, then as mouse-dragged events are intercepted, continueTrackingMouse is invoked. Finally, stopTrackingMouse is invoked. If untilMouseUp is true, it's invoked when the mouse goes up anywhere, If untilMouseUp is false, it's invoked when the mouse goes up within cellFrame. (If cellFrame is null, then the bounds are considered infinitely large.) You usually override one or more of these methods to respond to specific mouse events.



wraps

public boolean wraps()

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

See Also: setWraps




Table of Contents