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

Table of Contents

NSControl


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


Class Description


NSControl is an abstract superclass that provides three fundamental features for implementing user-interface devices. First, as a subclass of NSView, NSControl draws, or coordinates the drawing of, the on-screen representation of the device. Second, it receives and responds to user-generated events within its bounds by overriding NSResponder's moveDown: method and providing a position in the responder chain. Third, it implements the sendActionToTarget method to send an action message to the NSControl's target object. Subclasses of NSControl defined in the Application Kit are NSBrowser, NSButton (and its subclass NSPopUpButton), NSColorWell, NSImageView, NSMatrix (and its subclass NSForm), NSScroller, NSSlider, NSTableView, and NSTextField. Instances of concrete NSControl subclasses are often referred to as, simply, controls.


Controls and Cells


Controls are usually associated with one or more cells-instances of a subclass of the abstract class NSCell. A control's cell (or cells) usually fit just inside the bounds of the control. Cells are objects that can draw themselves and respond to events, but they can do so only indirectly, upon instruction from their control, which acts as a kind of coordinating backdrop.

Controls manage the behavior of their cells. By inheritance from NSView, controls derive the ability for responding to user actions and rendering their on-screen representation. When users click on a control, it responds in part by sending trackMouse:inRect:ofView:untilMouseUp: to the cell that was clicked. Upon receiving this message, the cell tracks the mouse and may have the control send the cell's action message to its target (either upon mouse-up or continuously, depending on the cell's attributes). When controls receive a display request, they, in turn, send their cell (or cells) a drawWithFrame:inView: message to have the cells draw themselves.

This relationship of control and cell makes two things possible: A control can manage cells of different types and with different targets and actions (see below), and a single control can manage multiple cells. Most Application Kit controls, like NSButtons and NSTextFields, manage only a single cell. But some controls, notably NSMatrix and NSForm, manage multiple cells (usually of the same size and attributes, and arranged in a regular pattern). Because cells are lighter-weight than controls, in terms of inherited data and behavior, it is more efficient to use a multi-cell control rather than multiple controls.

Many methods of NSControl-particularly methods that set or obtain values and attributes-have corresponding methods in NSCell. Sending a message to the control causes it to be forwarded to the control's cell or (if a multi-cell control) its selected cell. However, many NSControl methods are effective only in controls with single cells (these are noted in the method descriptions).

An NSControl subclass doesn't have to use an NSCell subclass to implement itself-NSScroller and NSColorWell are examples of NSControls that don't. However, such subclasses have to take care of details NSCell would otherwise handle. Specifically, they have to override methods designed to work with a cell. What's more, the lack of a cell means you can't make use of NSMatrix capability for managing multi-cell arrays such as radio buttons.


Target and Action


Target objects and action methods (or messages) are part of the mechanism by which controls respond to user actions and enable users to communicate their intentions to an application. A target is an object a control uses as the receiver of action messages. The target's class defines an action method to enable its instances to respond to these messages, which are sent as users click or otherwise manipulate the control. NSControl's sendActionToTarget asks the NSApplication object, NSApp, to send an action message to the control's target object.

NSControl provides methods for setting and obtaining the target object and the action method. However, these methods require that an NSControl's cell (or cells) either inherit from NSActionCell, or have action and target instance variables and respond to the NSControl methods.

See the NSActionCell class specification for more on the implementation of target and action behavior, particularly how action messages with null targets travel up the responder chain.


Field Validation and Entry Error-Handling


NSControl provides the delegation method controlIsValidObject for validating the contents of cells embedded in controls (instances of NSTextField and NSMatrix in particular). In validating you check for values that are permissible as objects, but that are undesirable in a given context, such as a date field in which dates should never be in the future, or zip codes that are valid for a certain state.

The method controlIsValidObject is invoked when the insertion point leaves a cell (that is, the associated control relinquishes first-responder status) but before the string value of the cell's object is displayed. Return true to allow display of the string and false to reject display and return the cursor to the cell.

NSControl provides several delegate methods for its subclasses that allow text editing, such as NSTextField and NSMatrix. Some are invoked when formatters for a control's cells cannot format a string ( controlDidFailToFormatStringErrorDescription) or reject a partial string entry ( controlDidFailToValidatePartialString). NSControl also provides controlTextViewDoCommandBySelector, which allows delegates the opportunity to detect and respond to key bindings, such as complete: (name completion). Note that although NSControl defines delegate methods, it does not itself have a delegate. Any subclass that uses the delegate methods must contain a delegate and the methods to get and set it.


Changing the NSCell Class


Because NSControl uses objects derived from the NSCell class to implement most of its functionality, you can usually implement a unique user interface device by creating a subclass of NSCell rather than NSControl. As an example, let's say you want all your application's NSSliders to have a type of cell other than the generic NSSliderCell. First, you create a subclass of NSCell, NSActionCell, or NSSliderCell. (Let's call it MyCellSubclass.) Then, you can simply invoke NSSlider's setCellClass class method:

NSSlider.setCellClass(MyCellSubclass.class);

All NSSliders created thereafter will use MyCellSubclass, until you call setCellClass: again.

If you want to create generic NSSliders (ones that use NSSliderCell) in the same application as the customized NSSliders that use MyCellSubclass, there are two possible approaches. One is to invoke setCellClass: as above whenever you're about to create a custom NSSlider, resetting the cell class to NSSliderCell afterwards. The other approach is to create a custom subclass of NSSlider that automatically uses MyCellSubclass, as explained below.


Creating New NSControls


If you create a custom NSControl subclass that uses a custom subclass of NSCell, you should override NSControl's cellClass method:

public static Class cellClass()
{
    return MyCellSubclass;
}

NSControl's constructors will use the return value of cellClass to allocate and initialize an NSCell of the correct type.

Override the constructors if you create a subclass of NSControl that performs its own initialization.




Method Types


Constructors
NSControl
Setting the control's cell
cellClass
setCellClass
cell
setCell
Enabling and disabling the control
isEnabled
setEnabled
Identifying the selected cell
selectedCell
selectedTag
Setting the control's value
doubleValue
setDoubleValue
floatValue
setFloatValue
intValue
setIntValue
objectValue
setObjectValue
stringValue
setStringValue
setNeedsDisplay
Interacting with other controls
takeDoubleValue
takeFloatValue
takeIntValue
takeObjectValue
takeStringValue
Formatting text
alignment
setAlignment
font
setFont
setFloatingPointFormat
Managing the field editor
abortEditing
currentEditor
validateEditing
Resizing the control
calcSize
sizeToFit
Displaying a cell
selectCell
drawCell
drawCellInside
updateCell
updateCellInside
Implementing the target/action mechanism
action
setAction
target
setTarget
isContinuous
setContinuous
sendActionToTarget
setEventMaskForSendingAction
Getting and setting attributed-string values
attributedStringValue
setAttributedStringValue
Getting and setting tags
tag
setTag
Activating from the keyboard
performClick
refusesFirstResponder
setRefusesFirstResponder
Tracking the mouse
mouseDown
ignoresMultiClick
setIgnoresMultiClick


Constructors



NSControl

public NSControl()

Description forthcoming.

public NSControl(NSRect frameRect)

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. Because NSControl is an abstract class, you should call this method 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.


Static Methods



cellClass

public static Class cellClass()

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

See Also: cell, setCell



setCellClass

public static void setCellClass(Class class)

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

See Also: cell, setCell




Instance Methods



abortEditing

public boolean abortEditing()

Terminates and discards any editing of text displayed by the receiving control and removes the field editor's delegate. Returns true if there was a field editor associated with the control, false otherwise.

See Also: currentEditor, validateEditing



action

public NSSelector 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). For controls with multiple cells, it's better to get the action-message selector for a particular cell.

See Also: setAction, setTarget, target



alignment

public int alignment()

Returns the alignment mode of the text in the receiver's cell. The return value can be one of these constants: LeftTextAlignment, RightTextAlignment, CenterTextAlignment, JustifiedTextAlignment, or NaturalTextAlignment (the default alignment).

See Also: setAlignment



attributedStringValue

public NSAttributedString attributedStringValue()

Returns the object value of the receiver's cell (or selected cell) as an attributed string after validating any editing currently being done. If no cell is associated with the receiver, returns an empty attributed string.

See Also: setAttributedStringValue



calcSize

public void calcSize()

Recomputes any internal sizing information for the NSControl, if necessary, by invoking its NSCell's calcDrawInfo method. 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 this happens, calcSize is automatically invoked whenever the NSControl is displayed; you never need to invoke it yourself.

See Also: sizeToFit



cell

public NSCell cell()

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

See Also: cellClass, setCellClass, setCell



currentEditor

public NSText currentEditor()

If the receiving NSControl is being edited-that is, it has an NSText object acting as its field editor, and is the first responder of its NSWindow-this method returns the NSText editor; otherwise, it returns null.

See Also: abortEditing, validateEditing



doubleValue

public double doubleValue()

Returns the value of the receiver's cell as a double-precision floating point number. 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.

See Also: doubleValue, floatValue, intValue, objectValue, stringValue, setDoubleValue



drawCell

public void drawCell(NSCell aCell)

If aCell is the cell used to implement this NSControl, then the NSControl is displayed. 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.

See Also: selectCell, updateCell, updateCellInside



drawCellInside

public void drawCellInside(NSCell aCell)

Draws the inside of the receiver's cell (the area within a bezel or border). If the NSControl 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.

See Also: selectCell, updateCell, updateCellInside



floatValue

public float floatValue()

Returns the value of the receiver's cell (or selected cell, if a multiple-cell NSControl) as a single-precision floating point number. See doubleValue for more details.

See Also: doubleValue, intValue, objectValue, stringValue, setFloatValue



font

public NSFont font()

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

See Also: setFont



ignoresMultiClick

public boolean ignoresMultiClick()

Returns whether the receiving NSControl ignores multiple clicks made in rapid succession. See setIgnoresMultiClick for details.

intValue

public int intValue()

Returns the value of the receiver's cell (or selected cell, if a multiple-cell NSControl) as an integer. See doubleValue for more details.

See Also: doubleValue, floatValue, objectValue, stringValue, setIntValue



isContinuous

public boolean isContinuous()

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

See Also: setContinuous



isEnabled

public boolean isEnabled()

Returns whether the receiver reacts to mouse events.

See Also: setEnabled



mouseDown

public void mouseDown(NSEvent theEvent)

Invoked when the mouse button is pressed while the cursor is within the bounds of the NSControl. This method highlights the NSControl'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.

See Also: ignoresMultiClick, trackMouse (NSCell)



objectValue

public Object objectValue()

Returns the value of the receiver's cell (or selected cell, if a multiple-cell NSControl) as an object. See doubleValue for more details.

See Also: doubleValue, floatValue, intValue, stringValue, setObjectValue



performClick

public void performClick(Object sender)

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

refusesFirstResponder

public boolean refusesFirstResponder()

Returns whether the receiver refuses first responder status.

See Also: setRefusesFirstResponder



selectCell

public void selectCell(NSCell aCell)

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

See Also: selectedCell



selectedCell

public NSCell selectedCell()

Returns the receiver's selected cell. 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.

See Also: cell, setCell



selectedTag

public int selectedTag()

Returns the tag integer of the receiver's selected cell (see selectedCell) or -1 if there is no selected cell. When you set the tag of an 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.

See Also: setTag, tag



sendActionToTarget

public boolean sendActionToTarget( NSSelector theAction, Object theTarget)

Sends sendAction:to:from: to NSApp, which in turn sends a message to theTarget to perform theAction, adding the receiver as the last parameter. sendActionToTarget is invoked primarily by NSCell's trackMouse.

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

See Also: action, target



setEventMaskForSendingAction

public int setEventMaskForSendingAction(int mask)

Sets the conditions on which the receiver sends action messages to its target (continuously, mouse up, and others) and returns a bit mask with which to detect the previous settings. NSControl's default implementation simply invokes the setEventMaskForSendingAction method of its associated cell

See Also: sendActionToTarget, setEventMaskForSendingAction (NSCell)



setAction

public void setAction(NSSelector aSelector)

Sets the NSControl's action method to aSelector. If aSelector is null, then no action messages will be sent from the NSControl.

See Also: action, setTarget, target



setAlignment

public void setAlignment(int mode)

Sets the alignment of text in the receiver's cell and, if the cell is being edited, aborts editing and updates the cell. mode is one of five constants: LeftTextAlignment, RightTextAlignment, CenterTextAlignment, JustifiedTextAlignment, NaturalTextAlignment (the default alignment for the text).

See Also: alignment



setAttributedStringValue

public void setAttributedStringValue(NSAttributedString object)

Sets the value of the receiver's cell (or selected cell) as an attributed string. 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).

See Also: attributedStringValue



setCell

public void setCell(NSCell aCell)

Sets the receiver's cell to aCell. 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.

See Also: cell, selectedCell



setContinuous

public void setContinuous(boolean flag)

Sets whether the receiver's cell continuously sends its action message to its target as it tracks the mouse.

See Also: isContinuous



setDoubleValue

public void setDoubleValue(double aDouble)

Sets the value of the receiver's cell (or selected cell) to aDouble (a double-precision floating point number). 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 for automatic redisplay (NSActionCell performs its own updating of cells).

See Also: doubleValue, setFloatValue, setIntValue, setObjectValue, setStringValue



setEnabled

public void setEnabled(boolean flag)

Sets whether the receiving NSControl'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). If flag is false, any editing is aborted. Redraws the entire control if autodisplay is enabled. 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.

See Also: isEnabled



setFloatValue

public void setFloatValue(float aFloat)

Sets the value of the receiver's cell (or selected cell) to aFloat (a single-precision floating point number). 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 for automatic redisplay (NSActionCell performs its own updating of cells).

See Also: floatValue, setDoubleValue, setIntValue, setObjectValue, setStringValue



setFloatingPointFormat

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

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

See Also: setFloatingPointFormat (NSCell)



setFont

public void setFont(NSFont fontObject)

Sets the font used to draw text in the receiver's cell to fontObject. 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.

See Also: setFont



setIgnoresMultiClick

public void setIgnoresMultiClick(boolean flag)

Sets whether the receiving NSControl ignores multiple clicks made in rapid succession. 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.

See Also: ignoresMultiClick



setIntValue

public void setIntValue(int anInt)

Sets the value of the receiver's cell (or selected cell) to the integer anInt. 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 for automatic redisplay (NSActionCell performs its own updating of cells).

See Also: intValue, setDoubleValue, setFloatValue, setObjectValue, setStringValue



setNeedsDisplay

public void setNeedsDisplay()

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

See Also: setNeedsDisplay (NSView)



setObjectValue

public void setObjectValue(Object object)

Sets the value of the receiver's cell (or selected cell) to object. 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 for automatic redisplay (NSActionCell performs its own updating of cells).

See Also: objectValue, setDoubleValue, setFloatValue, setIntValue, setStringValue



setRefusesFirstResponder

public void setRefusesFirstResponder(boolean flag)

Sets whether the receiver refuses first responder status. 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 non-text controls, a faint rectangle), the user can activate the control by pressing the space bar.

See Also: refusesFirstResponder, objectValue, setDoubleValue, setFloatValue



setStringValue

public void setStringValue(String aString)

Sets the value of the receiver's cell (or selected cell) to the string aString. 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 for automatic redisplay (NSActionCell performs its own updating of cells).

See Also: setDoubleValue, setFloatValue, setIntValue, setObjectValue, stringValue



setTag

public void setTag(int anInt)

Sets the tag of the receiving NSControl to anInt. It doesn't affect the tag of the receiver's cell.

See Also: tag



setTarget

public void setTarget(Object anObject)

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

See Also: action, setAction, target, setTarget (NSCell)



sizeToFit

public void sizeToFit()

Changes the width and the height of the receiver's frame so they are the minimum needed to contain its cell. If you want a multiple-cell custom subclass of NSControl to size itself to fit its cells, you must override this method.

See Also: calcSize



stringValue

public String stringValue()

Returns the value of the receiver's cell (or selected cell, if a multiple-cell NSControl) as a String. See doubleValue for details.

See Also: doubleValue, floatValue, intValue, objectValue, setStringValue



tag

public int tag()

Returns the tag identifying the receiving control (not the tag of the receiver's cell).

See Also: setTag



takeDoubleValue

public void takeDoubleValue(Object sender)

Sets the double-precision floating-point value of the receiving control's cell (or selected cell) to the value obtained by sending a doubleValue message to sender. 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

public void takeFloatValue(Object sender)

Sets the receiving NSControl's selected cell to the value obtained by sending a floatValue message to sender. See takeDoubleValue for more information.

takeIntValue

public void takeIntValue(Object sender)

Sets the receiving NSControl's selected cell to the value obtained by sending a intValue message to sender. See takeDoubleValue for more information.

takeObjectValue

public void takeObjectValue(Object sender)

Sets the receiving NSControl's selected cell to the value obtained by sending an objectValue message to sender. See takeDoubleValue for more information.

takeStringValue

public void takeStringValue(Object sender)

Sets the receiving NSControl's selected cell to the value obtained by sending a stringValue message to sender. See takeDoubleValue for more information.

target

public Object target()

Returns the target object of the receiver's cell.

See Also: action, setAction, setTarget



updateCell

public void updateCell(NSCell aCell)

Redisplays aCell or marks it for redisplay.

updateCellInside

public void updateCellInside(NSCell aCell)

Redisplays the inside of aCell or marks it for redisplay.

validateEditing

public void validateEditing()

Validates the user's changes to text in a cell of the receiving control. 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 simple String or an attributed string object based on the attributes of the editor.

See Also: abortEditing, currentEditor




Methods Implemented By the Delegate

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.


controlDidFailToFormatStringErrorDescription

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

Invoked when the formatter for control's cell (or selected cell) cannot convert a String to an underlying object. 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.

See Also: - getObjectValue:forString:errorDescription: (NSFormatter)



controlDidFailToValidatePartialString

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

Invoked when the formatter for control's cell (or selected cell) rejects a partial string a user is typing into the cell. 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.

See Also: - isPartialStringValid:newEditingString:errorDescription: (NSFormatter)



controlIsValidObject

public abstract boolean controlIsValidObject( NSControl control, Object object)

Invoked when the insertion point leaves a cell but before the string value of the cell's object is displayed. 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 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. An example of an object subject to such an evaluation is an NSDate object that should not represent a future date, or a monetary amount (represented by an NSNumber) that exceeds a predetermined limit.

controlTextShouldBeginEditing

public abstract boolean controlTextShouldBeginEditing( NSControl control, NSText fieldEditor)

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). Return true if the NSControl's fieldEditor should be allowed to start editing the text, false otherwise.

controlTextShouldEndEditing

public abstract boolean controlTextShouldEndEditing( NSControl control, NSText fieldEditor)

Sent directly by control to the delegate when the insertion point tries to leave a cell of the control that has been edited. 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.

controlTextViewDoCommandBySelector

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

Invoked when users press keys with predefined bindings in control's cell or selected cell, as communicated to the control by the cell's field editor (textView). 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.

For example, the default method for completing partially typed path names or symbols (usually when users press the Escape key) is complete:. The default implementation of complete: (in NSResponder) does nothing. The delegate could evaluate command and, if it's complete:, get the current string from textView and then expand it, or display a list of potential completions, or do whatever else is appropriate.



controlTextDidBeginEditing

public abstract void controlTextDidBeginEditing(NSNotification aNotification)

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, form field, or an NSMatrix) begins editing text. The name of the 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.

controlTextDidEndEditing

public abstract void controlTextDidEndEditing(NSNotification aNotification)

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, form field, or an NSMatrix) ends editing text. The name of the 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.

controlTextDidChange

public abstract void controlTextDidChange(NSNotification aNotification)

Sent by the default notification center to the delegate when the text in the receiving control (usually a text field, form, or NSMatrix with editable cells) changes. The name of the 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.


Notifications


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

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.

ControlTextDidBeginEditingNotification

This notification object contains a notification object and a userInfo dictionary. The notification object is the NSControl posting the notification. (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 userInfo dictionary contains these keys and values:


Key Value
"NSFieldEditor" The edited cell's field editor

See the description of controlTextDidBeginEditing, above, for details.

ControlTextDidChangeNotification

This notification object contains a notification object and a userInfo dictionary. The notification object is the NSControl posting the notification. (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 userInfo dictionary contains these keys and values:


Key Value
"NSFieldEditor" The edited cell's field editor

See the description of controlTextDidChange, above, for details.

ControlTextDidEndEditingNotification

This notification object contains a notification object and a userInfo dictionary. The notification object is the NSControl posting the notification. (The field editor of the edited cell originally sends a TextDidEndEditingNotification to the control, which passes it on in this form to its delegate.) The userInfo dictionary contains these keys and values:


Key Value
"NSFieldEditor" The edited cell's field editor

See the description of controlTextDidEndEditing, above.



Table of Contents