ADC Home > Reference Library > Reference > Legacy Documents > Cocoa > Application Kit Reference for Java (Legacy) >

Next Page > Hide TOC

Legacy Documentclose button

Important: The information in this document is obsolete and should not be used for new development.

NSCell

Inherits from
Implements
Package
com.apple.cocoa.application
Companion guide

Overview

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

Tasks

Constructors

Setting and Getting Cell Values

Setting and Getting Cell Attributes

Setting the State

Modifying Textual Attributes of Cells

Setting the Target and Action

Setting and Getting an Image

Assigning a Tag

Formatting and Validating Data

Managing Menus for Cells

Comparing Cells

Making Cells Respond to Keyboard Events

Deriving Values from Other Cells

Representing an Object with a Cell

Tracking the Mouse

Managing the Cursor

Managing Cell Messaging

Handling Keyboard Alternatives

Managing Focus Rings

Determining Cell Sizes

Drawing and Highlighting Cells

Editing and Selecting Cell Text

Constructors

NSCell

Creates an empty NSCell.

public NSCell()

Creates an NSCell initialized with aString and set to have the cell’s default menu.

public NSCell(String aString)

Discussion

If no field editor (a shared NSText object) has been created for all NSCells, one is created.

Creates an NSCell initialized with anImage and set to have the cell’s default menu.

public NSCell(NSImage anImage)

Discussion

If anImage is null, no image is set.

Static Methods

defaultFocusRingType

Returns the default type of focus ring.

public static int defaultFocusRingType()

Discussion

Possible values are listed in the “Constants” section of NSGraphics.

Availability

defaultMenu

Returns the default menu for instances of the receiver.

public static NSMenu defaultMenu()

Discussion

The default implementation returns null.

See Also

prefersTrackingUntilMouseUp

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

public static boolean prefersTrackingUntilMouseUp()

See Also

Instance Methods

acceptsFirstResponder

Returns whether or not the receiver will accept first responder status.

public boolean acceptsFirstResponder()

Discussion

The default implementation returns true if the receiver is enabled, and refusesFirstResponder returns false; subclasses can override.

See Also

action

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

public NSSelector action()

See Also

alignment

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

public int alignment()

See Also

allowsEditingTextAttributes

Returns whether the receiver allows user editing of textual attributes.

public boolean allowsEditingTextAttributes()

See Also

allowsMixedState

Returns true if the receiver has three states: on, off, and mixed.

public boolean allowsMixedState()

Discussion

Returns false if the receiver has two states: on and off.

See Also

allowsUndo

Returns true if undo operations are handled directly by the cell.

public boolean allowsUndo()

Discussion

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

Availability
See Also

attributedStringValue

Returns the value of the receiver as an attributed string (that is, a string with attributes), using the receiver’s formatter object (if one exists) to create the attributed string.

public NSAttributedString attributedStringValue()

Discussion

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

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

See Also

calcDrawInfo

Implemented by subclasses to recalculate drawing sizes with reference to aRect.

public void calcDrawInfo(NSRect aRect)

Discussion

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

cellAttribute

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

public int cellAttribute(int aParameter)

See Also

cellSize

Returns the minimum size needed to display the receiver, taking account of the size of the image or text within a certain offset determined by the border type.

public NSSize cellSize()

Discussion

If the receiver is of neither image nor text type, a size of 10000.0 x 10000.0 is returned; if the receiver is of image type, and no image has been set, NSSize.ZeroSize is returned.

See Also

cellSizeForBounds

Returns the minimum size needed to display the receiver, taking account of the size of the image or text within an offset determined by the border type.

public NSSize cellSizeForBounds(NSRect aRect)

Discussion

If the receiver is of text type, the text is resized to fit within aRect (as much as aRect is within the bounds of the cell). If the receiver is of neither image nor text type, the size of aRect parameter is returned; if the receiver is of image type, and no image has been set, a size with zero width and height is returned.

See Also

compare

Compares the string values of the receiver and otherCell (which must be a kind of NSCell), disregarding case.

public int compare(Object otherCell)

Discussion

Throws BadComparisonException if otherCell is not of the NSCell class.

continueTrackingMouse

Returns whether mouse tracking should continue in the receiving cell based on lastPoint and currentPoint within controlView.

public boolean continueTrackingMouse(NSPoint lastPoint, NSPoint currentPoint, NSView controlView)

Discussion

currentPoint is the current location of the cursor while lastPoint is either the initial location of the cursor 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 button is down or the mouse is being dragged. Subclasses can override this method to provide more sophisticated tracking behavior.

See Also

controlSize

Returns the size of the receiver.

public int controlSize()

Discussion

Valid return values are described in “Constants.”

See Also

controlTint

Returns the receiver’s control tint.

public int controlTint()

Discussion

Valid return values are described in “Constants.”

See Also

controlView

Implemented by subclasses to return the NSView last drawn in (normally an NSControl).

public NSView controlView()

Discussion

The default implementation returns null.

See Also

doubleValue

Returns the receiver’s value as a double.

public double doubleValue()

Discussion

If the receiver is not a text-type cell or the cell value is not scannable, the method returns 0.

drawingRectForBounds

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

public NSRect drawingRectForBounds(NSRect theRect)

See Also

drawInteriorWithFrameInView

Draws the “inside” of the receiver—including the image or text within the receiver’s frame in controlView (usually the cell’s NSControl) but excluding the border.

public void drawInteriorWithFrameInView(NSRect cellFrame, NSView controlView)

Discussion

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 what the NSCell displays when its contents change. This drawing is minimal and becomes more complex in objects such as NSButtonCell and NSSliderCell.

This method draws the cell in the currently focused view, which can be different from the controlView passed in. Taking advantage of this is not recommended.

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

drawWithFrameInView

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

public void drawWithFrameInView(NSRect cellFrame, NSView controlView)

Discussion

This method draws the cell in the currently focused view, which can be different from the controlView passed in. Taking advantage of this is not recommended.

editWithFrameInView

Begins editing of the receiver’s text using the field editor textObj.

public void editWithFrameInView(NSRect aRect, NSView controlView, NSText textObj, Object anObject, NSEvent theEvent)

Discussion

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 NSEvent.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 controlView, 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

Ends any editing of text, using the field editor textObj, occurring in the receiver begun with editWithFrameInView and selectAndEditWithFrameInView.

public void endEditing(NSText textObj)

entryType

Returns the type of data the user can type into the receiver.

public int entryType()

Discussion

If the receiver is not a text-type cell, or if no type has been set, AnyType is returned. See “Constants” for a list of type constants.

See Also

floatValue

Returns the receiver’s value as a float.

public float floatValue()

Discussion

If the receiver is not a text-type cell or the cell value is not scannable, the method returns 0.

focusRingType

Returns the type of focus ring currently set.

public int focusRingType()

Discussion

Possible values are listed in the “Constants” section of NSGraphics You can disable a view's focus ring drawing by overriding this method so it always returns NSGraphics.FocusRingTypeNone, or by calling setFocusRingType with NSGraphics.FocusRingTypeNone. You should only disable a view from drawing its focus ring if you want to draw your own focus ring, or if there isn't sufficient space to display a focus ring in the default location.

Availability
See Also

font

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

public NSFont font()

See Also

formatter

Returns the formatter object (a kind of NSFormatter) associated with the receiver.

public NSFormatter formatter()

Discussion

This object handles translation of the receiver’s contents between its onscreen representation and its object value.

See Also

hasValidObjectValue

Returns whether the object associated with the receiver has a valid object value.

public boolean hasValidObjectValue()

Discussion

A valid object value is one that the receiver’s formatter can “understand.” Objects are always assumed to be valid unless they are rejected by the formatter. Invalid objects can still be accepted by the delegate of the receiver’s NSControl (in controlDidFailToFormatStringErrorDescription).

See Also

highlightColorWithFrameInView

Returns the color to use when drawing the receiver’s selection highlight in cellFrame.

public NSColor highlightColorWithFrameInView(NSRect cellFrame, NSView controlView)

Discussion

You should not assume that a cell would necessarily want to draw itself with the value returned from selectedControlColor. A cell may wish to draw with different a selection highlight color depending on such things as the key state of its controlView.

highlightWithFrameInView

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

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

Discussion

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

image

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

public NSImage image()

See Also

imageRectForBounds

Returns the rectangle the receiver’s image is drawn in, which is slightly offset from theRect.

public NSRect imageRectForBounds(NSRect theRect)

See Also

importsGraphics

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

public boolean importsGraphics()

See Also

interval

Returns the amount of time that the cell pauses between messages when it’s sending action messages continuously to target objects.

public float interval()

Discussion

Override this method to supply your own interval value.

See Also

intValue

Returns the receiver’s value as an int.

public int intValue()

Discussion

If the receiver is not a text-type cell or the cell value is not scannable, the method returns 0.

isBezeled

Returns whether the receiver has a bezeled border.

public boolean isBezeled()

See Also

isBordered

Returns whether the receiver has a plain border.

public boolean isBordered()

See Also

isContinuous

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

public boolean isContinuous()

See Also

isEditable

Returns whether the receiver is editable.

public boolean isEditable()

See Also

isEnabled

Returns whether the receiver responds to mouse events.

public boolean isEnabled()

See Also

isEntryAcceptable

Returns whether a string representing a numeric or date value (aString) is formatted in a way suitable to the entry type.

public boolean isEntryAcceptable(String aString)

Discussion

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

isHighlighted

Returns whether the receiver is highlighted.

public boolean isHighlighted()

isOpaque

Returns whether the receiver is opaque (nontransparent).

public boolean isOpaque()

isScrollable

Returns whether the receiver scrolls typed text that exceeds the cell’s bounds.

public boolean isScrollable()

See Also

isSelectable

Returns whether the text of the receiver can be selected.

public boolean isSelectable()

See Also

keyEquivalent

Implemented by subclasses to return a key equivalent to clicking the cell.

public String keyEquivalent()

Discussion

The default implementation returns an empty string object.

lineBreakMode

Returns the line break mode currently used when drawing text.

public int lineBreakMode()

Availability
See Also

menu

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

public NSMenu menu()

See Also

menuForEvent

Returns the NSMenu associated with the receiver through the setMenu method and related to anEvent when the cursor is detected within cellFrame.

public NSMenu menuForEvent(NSEvent anEvent, NSRect cellFrame, NSView aView)

Discussion

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

Returns the character in the receiver’s title that appears underlined for use as a mnemonic.

public String mnemonic()

Discussion

If there is no mnemonic character, returns an empty string. Mnemonics are not supported in Mac OS X

See Also

mnemonicLocation

Returns the position of the underlined character in the receiver’s title used as a mnemonic.

public int mnemonicLocation()

Discussion

If there is no mnemonic character, returns NSArray.NotFound. Mnemonics are not supported in Mac OS X.

See Also

mouseDownFlags

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

public int mouseDownFlags()

See Also

nextState

Returns the receiver’s next state.

public int nextState()

Discussion

If the receiver has three states, it cycles through them in this order: on, off, mixed, on, and so forth. If the receiver has two states, it toggles between them.

See Also

objectValue

Returns the receiver’s value as an object if a valid object has been associated with the receiver; otherwise, returns null.

public Object objectValue()

Discussion

To be valid, the receiver must have a formatter capable of converting the object to and from its textual representation.

performClick

Can be used to simulate a single mouse click on the receiver.

public void performClick(Object sender)

Discussion

The receiver must be enabled and either the receiver's current controlView must be valid or sender, which must be a subclass of NSView, is used instead. The receiver's action is performed on its target. Throws an exception if the action message cannot be successfully sent.

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.

public float periodicDelay()

Discussion

Override this method to supply your own delay value.

See Also

refusesFirstResponder

Returns true if the receiver can never become the first responder.

public boolean refusesFirstResponder()

Discussion

To find out whether the receiver can become first responder at this time, use the method acceptsFirstResponder.

See Also

representedObject

Returns the object the receiver represents.

public Object representedObject()

Discussion

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

See Also

resetCursorRect

Sets the receiver to show the I-beam cursor within cellFrame while it tracks the mouse.

public void resetCursorRect(NSRect cellFrame, NSView controlView)

Discussion

The receiver must be an enabled and selectable (or editable) text-type cell. controlView is the NSControl that manages the cell.

This method is invoked by resetCursorRects and in general you do not need to call this method unless you have a custom NSView that uses a cell.

selectAndEditWithFrameInView

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.

public void selectAndEditWithFrameInView(NSRect aRect, NSView controlView, NSText textObj, Object anObject, int selStart, int selLength)

Discussion

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 is null, or if the receiver has no font set for it.

sendsActionOnEndEditing

Returns whether the receiver’s NSControl object sends its action message whenever the user finishes editing the cell’s text.

public boolean sendsActionOnEndEditing()

Discussion

If it returns true, the receiver’s NSControl object sends its action message when the user does one of the following:

If it returns false, the cell’s NSControl object sends its action message only when the user presses the Return key.

See Also

setAction

public void setAction(NSSelector aSelector)

Discussion

In NSCell, throws InternalInconsistencyException. However, NSActionCell overrides this method to set the action method, depending on the value of aSelector, as part of the implementation of the target/action mechanism.

See Also

setAlignment

Sets the alignment of text in the receiver.

public void setAlignment(int mode)

Discussion

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

See Also

setAllowsEditingTextAttributes

Sets whether the textual attributes of the receiver can be modified by the user.

public void setAllowsEditingTextAttributes(boolean flag)

Discussion

If flag is false, the receiver also cannot import graphics (that is, it does not support RTFD text).

See Also

setAllowsMixedState

public void setAllowsMixedState(boolean flag)

Discussion

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

See Also

setAllowsUndo

If allowsUndo is true, the receiver assumes responsibility for undo operations within the cell.

public void setAllowsUndo(boolean allowsUndo)

Discussion

If allowsUndo is false, undo operations are handled by the application’s custom undo manager.

Availability
See Also

setAttributedStringValue

Sets the value of the receiver to the attributed string attribStr.

public void setAttributedStringValue(NSAttributedString attribStr)

Discussion

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.

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

See Also

setBezeled

Sets whether the receiver draws itself with a bezeled border, depending on the Boolean value flag.

public void setBezeled(boolean flag)

Discussion

The setBezeled and setBordered methods are mutually exclusive (that is, a border can be only plain or bezeled). Invoking this method results in setBordered being sent with a value of false.

See Also

setBordered

Sets whether the receiver draws itself outlined with a plain border, depending on the Boolean value flag.

public void setBordered(boolean flag)

Discussion

The setBezeled and setBordered methods are mutually exclusive (that is, a border can be only plain or bezeled). Invoking this method results in setBezeled being sent with a value of false.

See Also

setCellAttribute

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

public void setCellAttribute(int aParameter, int value)

See Also

setContinuous

Sets whether the receiver continuously sends its action message to its target while it tracks the mouse, depending on the Boolean value flag.

public void setContinuous(boolean flag)

Discussion

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

setControlSize

Sets the size of the receiver.

public void setControlSize(int size)

Discussion

Valid values for size are described in “Constants.”

Changing the cell’s control size does not change the font of the cell. Use the NSFont class method systemFontSizeForControlSize to obtain the system font based on the new control size and set it.

See Also

setControlTint

Sets the receiver’s control tint.

public void setControlTint(int controlTint)

Discussion

Valid values for controlTint are described in “Constants.”

See Also

setControlView

Sets the receiver’s control view.

public void setControlView(NSView view)

Discussion

The control view represents the control currently being rendered by the cell.

Availability
See Also

setDoubleValue

Sets the value of the receiver to an object aDouble, representing a double value.

public void setDoubleValue(double aDouble)

Discussion

In its implementation, this method invokes setObjectValue. Does nothing if the receiver is not a text-type cell.

See Also

setEditable

Sets whether the user can edit the receiver’s text, depending on the Boolean value flag.

public void setEditable(boolean flag)

Discussion

If flag is true, the text is also made selectable. If flag is false, the selectable attribute is restored to the value it was before the cell was last made editable.

See Also

setEnabled

Sets whether the receiver is enabled or disabled, depending on the Boolean value flag.

public void setEnabled(boolean flag)

Discussion

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

setEntryType

Sets how numeric data is formatted in the receiver and places restrictions on acceptable input.

public void setEntryType(int aType)

Discussion

aType can be one of the types defined in “Constants.” The formatter associated with the receiver is replaced with a newly instantiated formatter appropriate to the entry type.

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

setEventMaskForSendingAction

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.

public int setEventMaskForSendingAction(int mask)

Discussion

setEventMaskForSendingAction is used during mouse tracking when the mouse button state changes, the mouse moves, or, if the cell is marked to send its action continuously while tracking, periodically. Because of this, the only bits checked in mask are NSEvent.LeftMouseDownMask, NSEvent.LeftMouseUpMask, NSEvent.LeftMouseDraggedMask, and NSEvent.PeriodicMask.

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

See Also

setFloatingPointFormat

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.

public void setFloatingPointFormat(boolean autoRange, int leftDigits, int rightDigits)

Discussion

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

setFloatValue

Sets the value of the receiver to an object aFloat, representing a float value.

public void setFloatValue(float aFloat)

Discussion

In its implementation, this method invokes setObjectValue. Does nothing if the receiver is not a text-type cell.

See Also

setFocusRingType

Sets the type of focus ring to be used.

public void setFocusRingType(int focusRingType)

Discussion

Possible values are listed in the “Constants” section of NSGraphics. You can disable a view's focus ring drawing by calling this method with NSGraphics.FocusRingTypeNone. You should only disable a view from drawing its focus ring if you want to draw your own focus ring, or if there isn't sufficient space to display a focus ring in the default location.

Availability
See Also

setFont

Sets the font to be used when the receiver displays text.

public void setFont(NSFont fontObj)

Discussion

If the receiver is not a text-type cell, the method converts it to that type.

See Also

setFormatter

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.

public void setFormatter(NSFormatter newFormatter)

Discussion

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

setHighlighted

Sets whether the receiver has a highlighted appearance, depending on the Boolean value flag.

public void setHighlighted(boolean flag)

Discussion

By default, it does nothing. NSButtonCell overrides this method to draw the button with the appearance specified by LightsByBackground, LightsByContents, or LightsByGray.

setImage

Sets the image to be displayed by the receiver.

public void setImage(NSImage image)

Discussion

If the receiver is not an image-type cell, the method converts it to that type.

See Also

setImportsGraphics

Sets whether the receiver can import images into its text (that is, whether it supports RTFD text).

public void setImportsGraphics(boolean flag)

Discussion

If flag is true, the receiver is also set to allow editing of text attributes (setAllowsEditingTextAttributes).

See Also

setIntValue

Sets the value of the receiver to an object anInt, representing an integer value.

public void setIntValue(int anInt)

Discussion

In its implementation, this method invokes setObjectValue. Does nothing if the receiver is not a text-type cell.

See Also

setLineBreakMode

Sets the line break mode used when drawing text to mode.

public void setLineBreakMode(int mode)

Discussion

The line break mode can also be modified by calling the setWraps method.

Availability
See Also

setMenu

Associates a menu with the cell that has commands contextually related to the receiver.

public void setMenu(NSMenu aMenu)

Discussion

The associated menu is retained. If aMenu is null, any association with a previous menu is removed.

See Also

setMnemonicLocation

Sets the character of the receiver’s title identified by location to be underlined.

public void setMnemonicLocation(int location)

Discussion

Mnemonics are not supported in Mac OS X.

See Also

setNextState

Sets the receiver to its next state.

public void setNextState()

Discussion

If the receiver has three states, it cycles through them in this order: on, off, mixed, on, and so forth. If the receiver has two states, it toggles between them.

See Also

setObjectValue

Sets the receiver’s object value to object.

public void setObjectValue(Object object)

See Also

setRefusesFirstResponder

Sets whether the receiver can become the first responder.

public void setRefusesFirstResponder(boolean flag)

Discussion

If flag is true, the receiver 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

Sets the object represented by the receiver—f

public void setRepresentedObject(Object anObject)

Discussion

or example, an NSColor object for a cell with a title of “Blue.”

See Also

setScrollable

Sets whether excess text in the receiver is scrolled past the cell’s bounds.

public void setScrollable(boolean flag)

Discussion

If flag is true, wrapping is turned off.

See Also

setSelectable

Sets whether text in the receiver can be selected, depending on the Boolean value flag.

public void setSelectable(boolean flag)

Discussion

If flag is false, editability is also disabled. If flag is true, editability is not affected.

See Also

setSendsActionOnEndEditing

Sets whether the receiver’s NSControl object sends its action message whenever the user finishes editing the cell’s text.

public void setSendsActionOnEndEditing(boolean flag)

Discussion

If flag is true, the receiver’s NSControl object sends its action message when the user does one of the following:

If flag is false, the cell’s NSControl object sends its action message only when the user presses the Return key.

See Also

setShowsFirstResponder

Sets whether the receiver draws some indication of its first responder status.

public void setShowsFirstResponder(boolean flag)

Discussion

NSCell itself does not draw any indication but subclasses may use flag to decide to draw a focus ring.

See Also

setState

Sets the receiver’s state to value, which can be OnState, OffState, or MixedState.

public void setState(int value)

Discussion

A 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, 0 is treated as OffState, and a nonzero value is treated as OnState. If the cell has three states, 0 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

setStringValue

Sets the value of the receiver to aString.

public void setStringValue(String aString)

Discussion

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.

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

See Also

setTag

Implemented by NSActionCell to set the receiver’s tag integer to anInt.

public void setTag(int anInt)

Discussion

NSCell’s implementation throws InternalInconsistencyException. Tags allow you to identify particular cells. Tag values are not used internally; they are only changed by external invocations of setTag. You typically set tag values in Interface Builder. When you set the tag of a control with a single cell in Interface Builder, it sets the tags of both the control and the cell to the same value as a convenience.

See Also

setTarget

Implemented by NSActionCell to set the receiver’s target object receiving the action message to anObject.

public void setTarget(Object anObject)

Discussion

NSCell’s implementation throws InternalInconsistencyException.

See Also

setTitle

Sets the title of the receiver to aString.

public void setTitle(String aString)

setTitleWithMnemonic

Sets the title of the receiver to aString with a character denoted as an access key.

public void setTitleWithMnemonic(String aString)

Discussion

Mnemonics are not supported in Mac OS X.

See Also

setType

If the type of the receiver is different from aType, sets it to aType, which must be one of TextCellType, ImageCellType, or NullCellType.

public void setType(int aType)

Discussion

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 ImageCellType, sets a null image. If aType is set to ImageCellType and the image is set to null, the cell type will be reported as NullCellType until a new, non-null image is set.

See Also

setUpFieldEditorAttributes

Sets textual and background attributes of textObj, depending on certain attributes.

public NSText setUpFieldEditorAttributes(NSText textObj)

Discussion

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.

You should not use this method to substitute a new field editor. setUpFieldEditorAttributes is intended to modify the attributes of the text object (that is, the field editor) passed into it and return that text object. If you want to substitute your own field editor, use the NSWindow method fieldEditorForObject or the NSWindow delegate method windowWillReturnFieldEditor.

setWraps

Sets whether text in the receiver wraps when its length exceeds the frame of the cell.

public void setWraps(boolean flag)

Discussion

If flag is true, then it also sets the receiver to be nonscrollable.

If the text of the receiver is an attributed string value you must explicitly set the paragraph style line break mode. Calling this method with the value true is equivalent to calling the setLineBreakMode: method with the value NSLineBreakByWordWrapping.

See Also

showsFirstResponder

Returns whether the receiver should draw some indication when it assumes first responder status.

public boolean showsFirstResponder()

See Also

startTrackingMouse

public boolean startTrackingMouse(NSPoint startPoint, NSView controlView)

Discussion

NSCell’s implementation of trackMouse invokes this method when tracking begins. startPoint is the point the cursor is currently at, and controlView is the NSControl managing the receiver. NSCell’s default implementation returns true if the receiver is either set to respond continuously or set to respond when the mouse is dragged. Otherwise, false is returned. Subclasses override this method to implement special mouse-tracking behavior at the beginning of mouse tracking—for example, displaying a special cursor.

See Also

state

Returns the receiver’s state.

public int state()

Discussion

The receiver can have two or three states. If it has two, it returns either OffState (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 receiver 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

stopTrackingMouse

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

Discussion

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

stringValue

Returns the receiver’s value as a String as converted by the receiver’s formatter, if one exists.

public String stringValue()

Discussion

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

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

See Also

tag

Implemented by NSActionCell to return the receiver’s tag integer.

public int tag()

Discussion

NSCell’s implementation returns –1. Tags allow you to identify particular cells. You typically set tag values in Interface Builder. When you set the tag of a control with a single cell in Interface Builder, it sets the tags of both the control and the cell to the same value as a convenience.

See Also

takeDoubleValue

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

public void takeDoubleValue(Object sender)

See Also

takeFloatValue

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

public void takeFloatValue(Object sender)

See Also

takeIntValue

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

public void takeIntValue(Object sender)

See Also

takeObjectValue

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

public void takeObjectValue(Object sender)

See Also

takeStringValue

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

public void takeStringValue(Object sender)

See Also

target

public Object target()

Discussion

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

See Also

titleRectForBounds

public NSRect titleRectForBounds(NSRect theRect)

Discussion

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

trackMouse

Invoked by an NSControl to initiate the tracking behavior of one of its NSCells.

public boolean trackMouse(NSEvent theEvent, NSRect cellFrame, NSView controlView, boolean untilMouseUp)

Discussion

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 untilMouseUp is set to true, this method returns true if the mouse button goes up while the cursor is anywhere; false, otherwise. If untilMouseUp is set to false, this method returns true if the mouse button goes up while the cursor is 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 leaves the cell frame even if the mouse button isn't released.

This method first invokes startTrackingMouse. If that method returns true, then as mouse-dragged events are intercepted, continueTrackingMouse is invoked until either the method returns false or the mouse is released. Finally, stopTrackingMouse is invoked if the mouse is released. If untilMouseUp is true, it’s invoked when the mouse button goes up while the cursor is anywhere. If untilMouseUp is false, it’s invoked when the mouse button goes up while the cursor is 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.

type

Returns the type of the receiver, one of TextCellType, ImageCellType, or NullCellType.

public int type()

Discussion

If the receiver’s type is set to ImageCellType and its image is set to null, the cell type will be reported as NullCellType until a new, non-null image is set.

See Also

wraps

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

public boolean wraps()

See Also

Constants

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

Constant

Description

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

Cell displays nothing.

TextCellType

Cell displays text.

ImageCellType

Cell displays images.

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

Constant

Description

ChangeBackground

If the cell’s state is MixedState or OnState, changes the cell’s background color from gray to white.

ChangesContents

If the cell’s state is MixedState or OnState, displays the cell’s alternate image.

ChangeGray

If the cell’s state is MixedState or OnState, displays the cell’s image as darkened.

Disabled

Does not let the user manipulate the cell.

Editable

Lets the user edit the cell’s contents.

HasImageHorizontal HasImageOnLeftOrBottom HasOverlappingImage

Controls the position of the cell’s image and text. To place the image above, set none of them. To place the image below, set HasImageOnLeftOrBottom. To place the image to the right, set HasImageHorizontal. To place the image to the left, set HasImageHorizontal and HasImageOnLeftOrBottom. To place the image directly over, set HasOverlappingImage.

Highlighted

Draws the cell with a highlighted appearance. This constant is deprecated. Use setHighlighted instead.

IsBordered

Draws a border around the cell.

IsInsetButton

Insets the cell’s contents from the border. By default, they’re inset by 2 pixels. This constant is ignored if the cell is unbordered.

LightsByBackground

If the cell is pushed in, changes the cell’s background color from gray to white.

LightsByContents

If the cell is pushed in, displays the cell’s alternate image.

LightsByGray

If the cell is pushed in, displays the cell’s image as darkened.

PushIn

Determines whether the cell’s image and text appear to be shifted down and to the right.

State

The cell’s state. It can be MixedState, OffState, or OnState.

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 its background and icon.

ChangeBackgroundCellMask

Same as ChangeGrayCellMask, but only background pixels are changed.

These constants specify a cell’s tint. They’re used by controlTint and setControlTint.

Constant

Description

DefaultControlTint

The current default tint setting

ClearControlTint

Clear control tint

BlueControlTint

Aqua control tint

GraphiteControlTint

Graphite control tint

These constants specify a cell’s size. They’re used by controlSize and setControlSize.

Constant

Description

RegularControlSize

The control is sized as regular.

SmallControlSize

The control has a smaller size. This constant is for controls that cannot be resized in one direction, such as push buttons, radio buttons, checkboxes, sliders, scroll bars, pop-up buttons, tabs, and progress indicators. You should use a small system font with a small control.

MiniControlSize

The control has a smaller size than SmallControlSize.



Next Page > Hide TOC

© 1997, 2007 Apple Inc. All Rights Reserved. (Last updated: 2007-02-01)

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.