Inherits from: NSView : NSResponder : NSObject
Package: com.apple.yellow.application
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 mouseDown: 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 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 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.
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 methodcontrolIsValidObject 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.
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.
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 constructor will use the return value of cellClass to allocate and initialize an NSCell of the correct type.
Override the constructor if you create a subclass of NSControl that performs its own initialization.
- Initializing an NSControl
- initWithFrame:
- 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
- Formating 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
public NSControl(NSRect frameRect)
public static Class cellClass()
null
if
no cell class has been specified for the receiving class or any
of its superclasses (up to NSControl).public static void setCellClass(Class class)
public boolean abortEditing()
true
if
there was a field editor associated with the control, false
otherwise. See Also: currentEditor, validateEditing
public NSSelector action()
See Also: setAction, setTarget, target
public int alignment()
LeftTextAlignment
, RightTextAlignment
, CenterTextAlignment
, JustifiedTextAlignment
,
or NaturalTextAlignment
(the default
alignment).See Also: setAlignment
public NSAttributedString attributedStringValue()
See Also: setAttributedStringValue
public void calcSize()
See Also: sizeToFit
public NSCell cell()
See Also: cellClass, setCellClass, setCell
public NSText currentEditor()
null
.See Also: abortEditing, validateEditing
public double doubleValue()
See Also: doubleValue, floatValue, intValue, objectValue, stringValue, setDoubleValue
public void drawCell(NSCell aCell)
See Also: selectCell, updateCell, updateCellInside
public void drawCellInside(NSCell aCell)
See Also: - selectCell:, - updateCell:, - updateCellInside:
public float floatValue()
See Also: doubleValue, intValue, objectValue, stringValue, setFloatValue:
public NSFont font()
See Also: - setFont:
public boolean ignoresMultiClick()
public int intValue()
See Also: doubleValue, floatValue, objectValue, stringValue, setIntValue:
public boolean isContinuous()
See Also: setContinuous
public boolean isEnabled()
See Also: setEnabled
public void mouseDown(NSEvent theEvent)
See Also: ignoresMultiClick, - trackMouse:inRect:ofView:untilMouseUp:(NSCell)
public Object objectValue()
See Also: doubleValue, floatValue, intValue, stringValue, setObjectValue:
public void performClick(Object sender)
public boolean refusesFirstResponder()
See Also: setRefusesFirstResponder
public void selectCell(NSCell aCell)
true
) and redraws
the NSControl if aCell is a cell
of the receiving NSControl and is unselected. See Also: selectedCell
public NSCell selectedCell()
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. public int selectedTag()
public boolean sendActionToTarget(NSSelector theAction, Object theTarget)
NXApp
,
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:inRect:ofView:untilMouseUp:.If theAction is null
,
no message is sent. If theTarget is null
, NXApp
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.
public int setEventMaskForSendingAction(int mask)
See Also: sendActionToTarget, - sendActionOn:(NSCell)
public void setAction(NSSelector aSelector)
null
,
then no action messages will be sent from the NSControl.See Also: action, setTarget, target
public void setAlignment(int mode)
LeftTextAlignment
, RightTextAlignment
, CenterTextAlignment
, JustifiedTextAlignment
, NaturalTextAlignment
(the
default alignment for the text).See Also: alignment
public void setAttributedStringValue(NSAttributedString object)
See Also: attributedStringValue
public void setCell(NSCell aCell)
See Also: cell, selectedCell
public void setContinuous(boolean flag)
See Also: isContinuous
public void setDoubleValue(double aDouble)
See Also: doubleValue, setFloatValue, setIntValue, setObjectValue, setStringValue
public void setEnabled(boolean flag)
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
public void setFloatValue(float aFloat)
See Also: floatValue, setDoubleValue, setIntValue, setObjectValue, setStringValue
public void setFloatingPointFormat(boolean autoRange, int leftDigits, int rightDigits)
See Also: - setFloatingPointFormat:left:right:(NSCell)
public void setFont(NSFont fontObject)
See Also: setFont
public void setIgnoresMultiClick(boolean flag)
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
public void setIntValue(int anInt)
See Also: intValue, setDoubleValue, setFloatValue, setObjectValue, setStringValue
public void setNeedsDisplay()
See Also: - setNeedsDisplay: (NSView)
public void setObjectValue(Object object)
See Also: objectValue, setDoubleValue, setFloatValue, setIntValue, setStringValue
public void setRefusesFirstResponder(boolean flag)
See Also: refusesFirstResponder, objectValue, setDoubleValue, setFloatValue
public void setStringValue(String aString)
See Also: setDoubleValue, setFloatValue, setIntValue, setObjectValue, stringValue
public void setTag(int anInt)
See Also: tag
public void setTarget(Object anObject)
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)
public void sizeToFit()
See Also: calcSize
public String stringValue()
See Also: doubleValue, floatValue, intValue, objectValue, setStringValue:
public int tag()
See Also: setTag
public void takeDoubleValue(java.lang.Object sender)
public void takeFloatValue(Object sender)
public void takeIntValue(Object sender)
public void takeObjectValue(Object sender)
public void takeStringValue(Object sender)
public Object target()
See Also: action, setAction, setTarget
public void updateCell(NSCell aCell)
public void updateCellInside(NSCell aCell)
public void validateEditing()
See Also: abortEditing, currentEditor
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.
public abstract boolean controlDidFailToFormatStringErrorDescription (NSControl control, String string, String error)
true
if string should
be accepted as-is, or false
if string should
be rejected.See Also: - getObjectValue:forString:errorDescription:(NSFormatter)
public abstract void controlDidFailToValidatePartialString (NSControl control, String string, String error)
See Also: - isPartialStringValid:newEditingString:errorDescription:(NSFormatter)
public abstract boolean controlIsValidObject (NSControl control, Object object)
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.public abstract boolean controlTextShouldBeginEditing (NSControl control, NSText fieldEditor)
true
if
the NSControl's fieldEditor should
be allowed to start editing the text, false
otherwise.public abstract boolean controlTextShouldEndEditing (NSControl control, NSText fieldEditor)
true
if the
control's fieldEditor should be
allowed to end its edit session, false
otherwise.public abstract boolean controlTextViewDoCommandBySelector (NSControl control,
NSTextView textView, NSSelector command)
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.
public abstract void controlTextDidBeginEditing (NSNotification aNotification)
public abstract void controlTextDidEndEditing (NSNotification aNotification)
public abstract void controlTextDidChange (NSNotification aNotification)
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.
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 NSTextDidBeginEditingNotification 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.
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 NSTextDidChangeNotification 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.
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 NSTextDidEndEditingNotification 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.