Next Page >

Hide TOC

Legacy Document

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

NSControl

Inherits from	NSView : NSResponder : NSObject
Implements	NSCoding (NSResponder)
Package	com.apple.cocoa.application
Companion guide	Control and Cell Programming Topics for Cocoa

Overview

NSControl is an abstract superclass that provides three fundamental features for implementing user interface devices: drawing devices on the screen, responding to user events, and sending action messages. It works closely with NSCell.

NSControl provides several delegate methods for its subclasses that allow text editing, such as NSTextField and NSMatrix. Note that although NSControl defines delegate methods, it does not itself have a delegate. Any subclass that uses these methods must have a delegate and the methods to get and set it.

Note that although NSControl defines delegate methods, it does not itself have a delegate. Any subclass that uses these methods must have a delegate and the methods to get and set it.

Tasks

Constructors

Setting the Control’s Cell

Enabling and Disabling the Control

Identifying the Selected Cell

Setting the Control’s Value

Interacting with Other Controls

Formatting Text

Managing the Field Editor

Resizing the Control

Displaying a Cell

Implementing the Target/action Mechanism

Getting and Setting Tags

Activating from the Keyboard

Tracking the Mouse

Validating the contents of a control

Editing text in a control

Getting error information from a formatter

Working with key bindings

Working with text completion

Constructors

NSControl

Creates an NSControl object with a zero-sized frame rectangle and creates a cell for it if the cell’s class has been specified for controls of this type with setCellClass.

public NSControl()

Discussion

Because NSControl is an abstract class, you should call this constructor only in the constructors of subclasses; that is, there should always be a more specific constructor for the subclass, as this is the constructor for NSControl.

Creates an NSControl object in frameRect and creates a cell for it if the cell’s class has been specified for controls of this type with setCellClass.

public NSControl(NSRect frameRect)

Discussion

Static Methods

cellClass

Returns the class of cells used by the receiving class.

public static Class cellClass()

Discussion

Returns null if no cell class has been specified for the receiving class or any of its superclasses (up to NSControl).

setCellClass

Sets the class of cells used by instances of the receiver.

public static void setCellClass(Class class)

Instance Methods

abortEditing

Terminates and discards any editing of text displayed by the receiver and removes the field editor’s delegate.

public boolean abortEditing()

Discussion

Returns true if there was a field editor associated with the control, false otherwise.

action

Returns the action-message selector of the receiver’s cell (the default NSControl behavior), or the default action-message selector for a control with multiple cells (such as an NSMatrix or an NSForm).

public NSSelector action()

Discussion

For controls with multiple cells, it’s better to get the action-message selector for a particular cell.

alignment

Returns the alignment mode of the text in the receiver’s cell.

public int alignment()

Discussion

The return value can be one of these constants: NSText.LeftTextAlignment, NSText.RightTextAlignment, NSText.CenterTextAlignment, NSText.JustifiedTextAlignment, or NSText.NaturalTextAlignment (the default alignment).

attributedStringValue

Returns the object value of the receiver’s cell (or selected cell) as an attributed string after validating any editing currently being done.

public NSAttributedString attributedStringValue()

Discussion

If no cell is associated with the receiver, returns an empty attributed string.

calcSize

Recomputes any internal sizing information for the receiver, if necessary, by invoking its NSCell’s calcDrawInfo method.

public void calcSize()

Discussion

Most NSControls maintain a flag that informs them if any of their cells have been modified in such a way that the location or size of the cell should be recomputed. If such a modification happens, calcSize is automatically invoked whenever the NSControl is displayed; you never need to invoke it yourself.

cell

Returns the receiver’s cell.

public NSCell cell()

Discussion

In NSControls with multiple cells (such as NSMatrix or NSForm), use selectedCell or a similar method for finding a particular cell.

currentEditor

public NSText currentEditor()

Discussion

If the receiver is being edited—that is, it has a field editor and is the first responder of its NSWindow—this method returns the field editor; otherwise, it returns null.

The field editor is a single NSTextView object that is shared among all the controls in a window for light text-editing needs. It is automatically instantiated when needed.

doubleValue

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

public double doubleValue()

Discussion

If the NSControl contains many cells (for example, NSMatrix), then the value of the currently selected cell is returned. If the NSControl is in the process of editing the affected cell, then it invokes validateEditing before extracting and returning the value.

drawCell

If aCell is the cell used to implement the receiver, then the receiver is displayed.

public void drawCell(NSCell aCell)

Discussion

This method is provided primarily to support a consistent set of methods between NSControls with single and multiple cells, because an NSControl with multiple cells needs to be able to draw a single cell at a time.

drawCellInside

Draws the inside of the receiver’s cell (the area within a bezel or border) specified by aCell.

public void drawCellInside(NSCell aCell)

Discussion

If the receiver is transparent, the method causes the superview to draw itself. This method invokes NSCell’s drawInteriorWithFrameInView method. This method has no effect on NSControls (such as NSMatrix and NSForm) that have multiple cells.

floatValue

Returns the value of the receiver’s cell (or selected cell, if a multiple-cell NSControl) as a single-precision floating-point number.

public float floatValue()

Discussion

See doubleValue for more details.

font

Returns the NSFont used to draw text in the receiver’s cell.

public NSFont font()

formatter

Returns the receiver’s formatter.

public Object formatter()

ignoresMultiClick

Returns whether the receiver ignores multiple clicks made in rapid succession.

public boolean ignoresMultiClick()

Discussion

See setIgnoresMultiClick for details.

intValue

Returns the value of the receiver’s cell (or selected cell, if a multiple-cell NSControl) as an integer.

public int intValue()

Discussion

See doubleValue for more details.

isContinuous

Returns whether the receiver’s NSCell continuously sends its action message to its target during mouse tracking.

public boolean isContinuous()

isEnabled

Returns whether the receiver reacts to mouse events.

public boolean isEnabled()

mouseDown

public void mouseDown(NSEvent theEvent)

Discussion

Invoked when the mouse button is pressed while the cursor is within the bounds of the receiver, generating theEvent. This method highlights the receiver’s NSCell and sends it a trackMouse message. Whenever the NSCell finishes tracking the mouse (for example, because the cursor has left the cell’s bounds), the cell is unhighlighted. If the mouse button is still down and the cursor reenters the bounds, the cell is again highlighted and a new trackMouse message is sent. This behavior repeats until the mouse button goes up. If it goes up with the cursor in the control, the state of the control is changed, and the action message is sent to the target. If the mouse button goes up when the cursor is outside the control, no action message is sent.

objectValue

Returns the value of the receiver’s cell (or selected cell, if a multiple-cell NSControl) as an object.

public Object objectValue()

Discussion

See doubleValue for more details.

performClick

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

public void performClick(Object sender)

Discussion

sender is ignored. This method calls performClick on the receiver's cell with the sender being the control itself. Throws an exception if the action message cannot be successfully sent.

refusesFirstResponder

Returns whether the receiver refuses first responder status.

public boolean refusesFirstResponder()

selectCell

Selects aCell (by setting its state to true) and redraws the NSControl if aCell is a cell of the receiver and is unselected.

public void selectCell(NSCell aCell)

selectedCell

Returns the receiver’s selected cell.

public NSCell selectedCell()

Discussion

The default implementation for NSControl simply returns the associated cell (or null if no cell has been set). Subclasses of NSControl that manage multiple cells (such as NSMatrix and NSForm) override this method to return the cell selected by users.

selectedTag

Returns the tag integer of the receiver’s selected cell (see selectedCell) or –1 if there is no selected cell.

public int selectedTag()

Discussion

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 with the same value as a convenience.

sendActionToTarget

Sends sendActionToTargetFromSender to NSApplication.sharedApplication(), which in turn sends a message to theTarget to perform theAction, adding the receiver as the last parameter.

public boolean sendActionToTarget(NSSelector theAction, Object theTarget)

Discussion

sendActionToTarget is invoked primarily by NSCell’s trackMouse.

If theAction is NULL, no message is sent. If theTarget is null, NSApplication.sharedApplication() looks for an object that can respond to the message by following the responder chain (see the class description for NSActionCell). This method returns false if no object that responds to theAction could be found.

setAction

Sets the receiver’s action method to aSelector.

public void setAction(NSSelector aSelector)

Discussion

If aSelector is NULL, then no action messages will be sent from the receiver.

See Action Messages for additional information on action messages.

setAlignment

Sets the alignment of text in the receiver’s cell and, if the cell is being edited, aborts editing and updates the cell.

public void setAlignment(int mode)

Discussion

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

setAttributedStringValue

Sets the value of the receiver’s cell (or selected cell) as an attributed string object.

public void setAttributedStringValue(NSAttributedString object)

Discussion

If the cell is being edited, it aborts all editing before setting the value; if the cell doesn’t inherit from NSActionCell, it marks it for automatic redisplay (NSActionCell performs its own updating of cells).

setCell

Sets the receiver’s cell to aCell.

public void setCell(NSCell aCell)

Discussion

Use this method with great care as it can irrevocably damage the affected control; specifically, you should only use this method in initializers for subclasses of NSControl.

setContinuous

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

public void setContinuous(boolean flag)

setDoubleValue

Sets the value of the receiver’s cell (or selected cell) to aDouble (a double-precision floating-point number).

public void setDoubleValue(double aDouble)

Discussion

If the cell is being edited, it aborts all editing before setting the value; if the cell doesn’t inherit from NSActionCell, it marks the cell’s interior as needing to be redisplayed (NSActionCell performs its own updating of cells).

setEnabled

Sets whether the receiver’s cell—or if there is no associated cell, the NSControl itself—is active (that is, whether it tracks the mouse and sends its action to its target).

public void setEnabled(boolean flag)

Discussion

If flag is false, any editing is aborted. Redraws the entire control if it is marked as needing redisplay. Subclasses may want to override this method to redraw only a portion of the control when the enabled state changes, as do NSButton and NSSlider.

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

You use this method during mouse tracking when the mouse button changes state, 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 LeftMouseDownMask, LeftMouseUpMask, LeftMouseDraggedMask, and PeriodicMask, which are declared in NSEvent.h. NSControl’s default implementation simply invokes the setEventMaskForSendingAction method of its associated cell.

setFloatingPointFormat

Sets the autoranging and floating point number format of the receiver’s cell, so that at most leftDigits are displayed to the left of the decimal point, and rightDigits to the right.

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

Discussion

The autoRange argument specifies whether floating-point numbers are autoranged in the receiver. See the description of this method in the NSCell class specification for details. If the cell is being edited, what’s typed is discarded, and the cell’s interior is redrawn.

setFloatValue

Sets the value of the receiver’s cell (or selected cell) to aFloat (a single-precision floating-point number).

public void setFloatValue(float aFloat)

Discussion

setFont

Sets the font used to draw text in the receiver’s cell to fontObject.

public void setFont(NSFont fontObject)

Discussion

If the cell is being edited, the text in the cell is redrawn in the new font, and the cell’s editor (the NSText object used globally for editing) is updated with the new NSFont.

setFormatter

Sets the receiver’s formatter to newFormatter.

public void setFormatter(NSFormatter newFormatter)

setIgnoresMultiClick

Sets whether the receiver ignores multiple clicks made in rapid succession, depending on the Boolean value flag.

public void setIgnoresMultiClick(boolean flag)

Discussion

By default, controls treat double clicks as two distinct clicks, triple clicks as three distinct clicks, and so on. However, when an NSControl returning true to this method receives multiple clicks (within a predetermined interval), each mouseDown event after the first is passed on to super.

setIntValue

Sets the value of the receiver’s cell (or selected cell) to the integer anInt.

public void setIntValue(int anInt)

Discussion

setNeedsDisplay

Marks the receiver as needing redisplay (assuming automatic display is enabled) after recalculation of its dimensions.

public void setNeedsDisplay()

setObjectValue

Sets the value of the receiver’s cell (or selected cell) to object.

public void setObjectValue(Object object)

Discussion

setRefusesFirstResponder

Sets whether the receiver refuses first responder status, depending on the Boolean value flag.

public void setRefusesFirstResponder(boolean flag)

Discussion

By default, the user can advance the focus of keyboard events between controls by pressing the Tab key; when this focus—or first responder status—is indicated for a control (by the insertion point or, for nontext controls, a faint rectangle), the user can activate the control by pressing the Space bar.

setStringValue

Sets the value of the receiver’s cell (or selected cell) to the string aString.

public void setStringValue(String aString)

Discussion

setTag

Sets the tag of the receiver to anInt.

public void setTag(int anInt)

Discussion

It doesn’t affect the tag of the receiver’s cell. 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.

setTarget

Sets the target object for the action message of the receiver’s cell; NSCell’s setTarget is used instead of any subclass override of this method.

public void setTarget(Object anObject)

Discussion

If anObject is null and the control sends an action message, the application looks for an object that can respond to the message by following the responder chain (see description of the NSActionCell class for details).

sizeToFit

Changes the width and the height of the receiver’s frame so they are the minimum needed to contain its cell.

public void sizeToFit()

Discussion

If you want a multiple-cell custom subclass of NSControl to size itself to fit its cells, you must override this method. This method neither redisplays the receiver nor marks it as needing display. You must do this yourself with either display or setNeedsDisplay.

stringValue

Returns the value of the receiver’s cell (or selected cell, if a multiple-cell NSControl) as a String.

public String stringValue()

Discussion

See doubleValue for details.

tag

Returns the tag identifying the receiver (not the tag of the receiver’s cell).

public int tag()

Discussion

Tags allow you to identify particular controls. 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.

takeDoubleValue

Sets the double-precision floating-point value of the receiver’s cell (or selected cell) to the value obtained by sending a doubleValue message to sender.

public void takeDoubleValue(Object sender)

Discussion

You can use this method to link action messages between controls. It permits one control or cell (sender) to affect the value of another control (the receiver) by invoking this method in an action message to the receiver. For example, a text field can be made the target of a slider. Whenever the slider is moved, it will send a takeDoubleValue message to the text field. The text field will then get the slider’s floating-point value, turn it into a text string, and display it, thus tracking the value of the slider.

takeFloatValue

Sets the receiver’s selected cell to the value obtained by sending a floatValue message to sender.

public void takeFloatValue(Object sender)

Discussion

See takeDoubleValue for more information.

takeIntValue

Sets the receiver’s selected cell to the value obtained by sending an intValue message to sender.

public void takeIntValue(Object sender)

Discussion

See takeDoubleValue for more information.

takeObjectValue

Sets the receiver’s selected cell to the value obtained by sending an objectValue message to sender.

public void takeObjectValue(Object sender)

Discussion

See takeDoubleValue for more information.

takeStringValue

Sets the receiver’s selected cell to the value obtained by sending a stringValue message to sender.

public void takeStringValue(Object sender)

Discussion

See takeDoubleValue for more information.

target

Returns the target object of the receiver’s cell.

public Object target()

updateCell

Redisplays aCell or marks it for redisplay.

public void updateCell(NSCell aCell)

updateCellInside

Redisplays the inside of aCell or marks it for redisplay.

public void updateCellInside(NSCell aCell)

validateEditing

Validates the user’s changes to text in a cell of the receiving control.

public void validateEditing()

Discussion

Validation sets the object value of the cell to the current contents of the cell’s editor (the NSText object used for editing), storing it as a simple String or an attributed string object based on the attributes of the editor.

Delegate Methods

controlDidFailToFormatStringErrorDescription

Invoked when the formatter for the cell belonging to control (or selected cell) cannot convert a String to an underlying object.

public abstract boolean controlDidFailToFormatStringErrorDescription(NSControl control, String string, String error)

Discussion

error is a localized user-presentable String that explains why the conversion failed. Evaluate the error or query the user and return true if string should be accepted as is, or false if string should be rejected.

controlDidFailToValidatePartialString

Invoked when the formatter for the cell belonging to control (or selected cell) rejects a partial string a user is typing into the cell.

public abstract void controlDidFailToValidatePartialString(NSControl control, String string, String error)

Discussion

This String (string) includes the character that caused the rejection. error is a localized user-presentable String that explains why the validation failed. You can implement this method to display a warning message or perform a similar action when the user enters improperly formatted text.

controlIsValidObject

Invoked when the insertion point leaves a cell belonging to control, but before the string value of the cell’s object is displayed.

public abstract boolean controlIsValidObject(NSControl control, Object object)

Discussion

Return true to allow display of the string and false to reject display and return the cursor to the cell. This method gives the delegate the opportunity to validate the contents of the control’s cell (or selected cell). In validating, the delegate checks object to determine if it falls within a permissible range, has required attributes, accords with a given context, and so on. Examples of objects subject to such evaluations are an NSDate object that should not represent a future date or a monetary amount (represented by an NSNumber) that exceeds a predetermined limit.

controlTextDidBeginEditing

Sent by the default notification center to the delegate and all observers of the notification when a control with editable cells (such as a text field, a form field, or an NSMatrix) begins editing text.

public abstract void controlTextDidBeginEditing(NSNotification aNotification)

Discussion

The name of notification aNotification is always ControlTextDidBeginEditingNotification. Use the key "NSFieldEditor" to obtain the field editor from aNotification’s userInfo dictionary. If the delegate implements this method, it’s automatically registered to receive this notification.

controlTextDidChange

Sent by the default notification center to the delegate when the text in the receiving control (usually a text field, a form field, or NSMatrix with editable cells) changes.

public abstract void controlTextDidChange(NSNotification aNotification)

Discussion

The name of notification aNotification is always ControlTextDidChangeNotification. Use the key "NSFieldEditor" to obtain the field editor from aNotification’s userInfo dictionary. If the delegate implements this method, it’s automatically registered to receive this notification.

controlTextDidEndEditing

public abstract void controlTextDidEndEditing(NSNotification aNotification)

Discussion

The name of notification aNotification is always ControlTextDidEndEditingNotification. Use the key "NSFieldEditor" to obtain the field editor from aNotification’s userInfo dictionary. If the delegate implements this method, it’s automatically registered to receive this notification.

controlTextShouldBeginEditing

Sent directly by control to the delegate when the user tries to enter a character in a cell of a control that allows editing of text (such as a text field or form field).

public abstract boolean controlTextShouldBeginEditing(NSControl control, NSText fieldEditor)

Discussion

Return true if the NSControl’s fieldEditor should be allowed to start editing the text, false otherwise.

controlTextShouldEndEditing

Sent directly by control to the delegate when the insertion point tries to leave a cell of the control that has been edited.

public abstract boolean controlTextShouldEndEditing(NSControl control, NSText fieldEditor)

Discussion

It’s sent only by controls that allow editing of text (such as a text field or a form field). Return true if the control’s fieldEditor should be allowed to end its edit session, false otherwise.

controlTextViewCompletionsForPartialWordRange

Sent to the delegate to allow you to control the list of proposed text completions generated by text fields and other controls.

public abstract NSArray controlTextViewCompletionsForPartialWordRange(NSControl control, NSTextView textView, NSArray words, NSRange charRange)

Discussion

Arguments include the text view for which the list was generated, the list of potential completions, and the partial word range (that is, the number of characters the user has already typed). The array you return is used for the completions list in place of the potential list passed to this method.

The completions list is an array of strings, in the order in which they should be presented. Each string should be a complete word that the user might be trying to type. The strings must be complete words rather than just the remainder of the word, in case completion requires some slight modification of what the user has already typed—for example, the addition of an accent, or a change in capitalization. You can also use this method to support abbreviations that complete into words that don't start with the characters of the abbreviation.

Availability

Available in Mac OS X v10.3 and later.

controlTextViewDoCommandBySelector

Invoked when users press keys with predefined bindings in a cell of the control or selected cell, as communicated to the control by the cell’s field editor (textView).

public abstract boolean controlTextViewDoCommandBySelector(NSControl control, NSTextView textView, NSSelector command)

Discussion

The delegate returns true if it handles the key binding, and false otherwise. These bindings are usually implemented as methods (command) defined in NSResponder; examples of such key bindings are arrow keys (for directional movement) and the Escape key (for name completion). By implementing this method, the delegate can override the default implementation of command and supply its own behavior.

Notifications

NSControl posts the following notifications to interested observers and its delegate.

ControlTextDidBeginEditingNotification

The field editor of the edited cell originally sends a TextDidBeginEditingNotification to the control, which passes it on in this form to its delegate. The notification object is the NSControl posting the notification. The userInfo dictionary contains the following information:

Key	Value
`"NSFieldEditor"`	The edited cell’s field editor

See the description of controlTextDidBeginEditing for details.

ControlTextDidChangeNotification

The field editor of the edited cell originally sends a TextDidChangeNotification to the control, which passes it on in this form to its delegate. The notification object is the NSControl posting the notification. The userInfo dictionary contains the following information:

Key	Value
`"NSFieldEditor"`	The edited cell’s field editor

See the description of controlTextDidChange for details.

ControlTextDidEndEditingNotification

The field editor of the edited cell originally sends a ControlTextDidEndEditingNotification to the control, which passes it on in this form to its delegate. The notification object is the NSControl posting the notification. The userInfo dictionary contains the following information:

Key	Value
`"NSFieldEditor"`	The edited cell’s field editor

See the description of controlTextDidEndEditing for details.

Next Page >

Hide TOC

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.

Legacy Document

NSControl

Overview

Tasks

Constructors

Setting the Control’s Cell

Enabling and Disabling the Control

Identifying the Selected Cell

Setting the Control’s Value

Interacting with Other Controls

Formatting Text

Managing the Field Editor

Resizing the Control

Displaying a Cell

Implementing the Target/action Mechanism

Getting and Setting Tags

Activating from the Keyboard

Tracking the Mouse

Validating the contents of a control

Editing text in a control

Getting error information from a formatter

Working with key bindings

Working with text completion

Constructors

NSControl

Discussion

Discussion

Static Methods

cellClass

Discussion

See Also

setCellClass

See Also

Instance Methods

abortEditing

Discussion

See Also

action

Discussion

See Also

alignment

Discussion

See Also

attributedStringValue

Discussion

See Also

calcSize

Discussion

See Also

cell

Discussion

See Also

currentEditor

Discussion

See Also

doubleValue

Discussion

See Also

drawCell

Discussion

See Also

drawCellInside

Discussion

See Also

floatValue

Discussion

See Also

font

See Also

formatter

See Also

ignoresMultiClick

Discussion

intValue

Discussion

See Also

isContinuous

See Also

isEnabled

See Also