Inherits from: NSView : NSResponder : NSObject
Conforms to: NSCoding
(NSResponder)
NSObject (NSObject)
Declared in: <
AppKit/NSControl.h
>
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 sendAction:to: 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 sendAction:to: 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 nil
targets travel
up the responder chain.
NSControl provides the delegation method control:isValidObject: 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 methodcontrol:isValidObject: 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 YES
to
allow display of the string and NO
to
reject display and return the cursor to the cell. The following example
evaluates an object (an NSDate) and rejects it if the date is in
the future:
- (BOOL)control:(NSControl *)control isValidObject:(id)obj { if (control == contactsForm) { if (![obj isKindOfClass:[NSDate class]]) return NO; if ([[obj laterDate:[NSDate date]] isEqual:obj]) { NSRunAlertPanel(@"Date not valid", @"Reason: date in future", NULL, NULL, NULL); return NO; } } return YES; }
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 ( control:didFailToFormatString:errorDescription:) or reject a partial string entry ( control:didFailToValidatePartialString:errorDescription:). NSControl also provides control:textView:doCommandBySelector:, 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:
+ (Class) cellClass { return [MyCellSubclass class]; }
NSControl's initWithFrame: method will use the return value of cellClass to allocate and initialize an NSCell of the correct type.
Override the designated initializer (initWithFrame:) 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
- - takeDoubleValueFrom:
- - takeFloatValueFrom:
- - takeIntValueFrom:
- - takeObjectValueFrom:
- - takeStringValueFrom:
- Formating text
- - alignment
- - setAlignment:
- - font
- - setFont:
- - setFloatingPointFormat:left:right:
- 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:
- - sendAction:to:
- - sendActionOn:
- 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:
+ (Class)cellClass
nil
if
no cell class has been specified for the receiving class or any
of its superclasses (up to NSControl).See Also: - cell, - setCell:
+ (void)setCellClass:(Class)class
See Also: - cell, - setCell:
- (BOOL)abortEditing
YES
if
there was a field editor associated with the control, NO
otherwise. See Also: - currentEditor, - validateEditing
- (SEL)action
someAction = [[theControl selectedCell] action];
See Also: - setAction:, - setTarget:, - target
- (NSTextAlignment)alignment
NSLeftTextAlignment
, NSRightTextAlignment
, NSCenterTextAlignment
, NSJustifiedTextAlignment
,
or NSNaturalTextAlignment
(the default
alignment).See Also: - setAlignment:
- (NSAttributedString *)attributedStringValue
See Also: - setAttributedStringValue:
- (void)calcSize
See Also: - sizeToFit
- (id)cell
See Also: + cellClass, + setCellClass:, - setCell:
- (NSText *)currentEditor
nil
.See Also: - abortEditing, - validateEditing
- (double)doubleValue
See Also: - doubleValue, - floatValue, - intValue, - objectValue, - stringValue, - setDoubleValue:
- (void)drawCell:(NSCell
*)aCell
See Also: - selectCell:, - updateCell:, - updateCellInside:
- (void)drawCellInside:(NSCell
*)aCell
See Also: - selectCell:, - updateCell:, - updateCellInside:
- (float)floatValue
See Also: - doubleValue, - intValue, - objectValue, - stringValue, setFloatValue:
- (NSFont *)font
See Also: - setFont:
- (BOOL)ignoresMultiClick
- (id)initWithFrame:(NSRect)frameRect
- (int)intValue
See Also: - doubleValue, - floatValue, - objectValue, - stringValue, setIntValue:
- (BOOL)isContinuous
See Also: - setContinuous:
- (BOOL)isEnabled
See Also: - setEnabled:
- (void)mouseDown:(NSEvent *)theEvent
See Also: - ignoresMultiClick, - trackMouse:inRect:ofView:untilMouseUp:(NSCell)
- (id)objectValue
See Also: - doubleValue, - floatValue, - intValue, - stringValue, setObjectValue:
- (void)performClick:(id)sender
- (BOOL)refusesFirstResponder
See Also: - setRefusesFirstResponder:
- (void)selectCell:(NSCell
*)aCell
YES
) and redraws
the NSControl if aCell is a cell
of the receiving NSControl and is unselected. See Also: - selectedCell
- (id)selectedCell
nil
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:
- (int)selectedTag
- (BOOL)sendAction:(SEL)theAction to:(id)theTarget
NXApp
,
which in turn sends a message to theTarget to
perform theAction, adding the receiver
as the last parameter. sendAction:to: is invoked primarily
by NSCell's trackMouse:inRect:ofView:untilMouseUp:.If theAction is nil
,
no message is sent. If theTarget is nil
, 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 nil
if no object
that responds to theAction could
be found.
- (int)sendActionOn:(int)mask
See Also: - sendAction:to:, - sendActionOn:(NSCell)
- (void)setAction:(SEL)aSelector
nil
,
then no action messages will be sent from the NSControl.See Also: - action, - setTarget:, - target
- (void)setAlignment:(NSTextAlignment)mode
NSLeftTextAlignment
, NSRightTextAlignment
, NSCenterTextAlignment
, NSJustifiedTextAlignment
, NSNaturalTextAlignment
(the
default alignment for the text).See Also: - alignment
- (void)setAttributedStringValue:(NSAttributedString
*)object
See Also: - attributedStringValue
- (void)setCell:(NSCell
*)aCell
See Also: - cell, - selectedCell
- (void)setContinuous:(BOOL)flag
See Also: - isContinuous
- (void)setDoubleValue:(double)aDouble
See Also: - doubleValue, - setFloatValue:, - setIntValue:, - setObjectValue:, - setStringValue:
- (void)setEnabled:(BOOL)flag
NO
,
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
- (void)setFloatValue:(float)aFloat
See Also: - floatValue, - setDoubleValue:, - setIntValue:, - setObjectValue:, - setStringValue:
- (void)setFloatingPointFormat:(BOOL)autoRange left:(unsigned)leftDigits right:(unsigned)rightDigits
See Also: - setFloatingPointFormat:left:right:(NSCell)
- (void)setFont:(NSFont
*)fontObject
See Also: - setFont:
- (void)setIgnoresMultiClick:(BOOL)flag
YES
to
this method receives multiple clicks (within a predetermined interval),
each mouseDown event after the first is
passed on to super.See Also: - ignoresMultiClick
- (void)setIntValue:(int)anInt
See Also: - intValue, - setDoubleValue:, - setFloatValue:, - setObjectValue:, - setStringValue:
- (void)setNeedsDisplay
See Also: - setNeedsDisplay: (NSView)
- (void)setObjectValue:(id)object
See Also: - objectValue, - setDoubleValue:, - setFloatValue:, - setIntValue:, - setStringValue:
- (void)setRefusesFirstResponder:(BOOL)flag
See Also: - refusesFirstResponder, - objectValue, - setDoubleValue:, - setFloatValue:
- (void)setStringValue:(NSString
*)aString
See Also: - setDoubleValue:, - setFloatValue:, - setIntValue:, - setObjectValue:, - stringValue
- (void)setTag:(int)anInt
See Also: - tag
- (void)setTarget:(id)anObject
nil
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)
- (void)sizeToFit
See Also: - calcSize
- (NSString *)stringValue
See Also: - doubleValue, - floatValue, - intValue, - objectValue, setStringValue:
- (int)tag
See Also: - setTag:
- (void)takeDoubleValueFrom:(id)sender
- (void)takeFloatValueFrom:(id)sender
- (void)takeIntValueFrom:(id)sender
- (void)takeObjectValueFrom:(id)sender
- (void)takeStringValueFrom:(id)sender
- (id)target
See Also: - action, - setAction:, - setTarget:
- (void)updateCell:(NSCell
*)aCell
- (void)updateCellInside:(NSCell
*)aCell
- (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.
- (BOOL)control:(NSControl
*)control didFailToFormatString:(NSString
*)string errorDescription:(NSString
*)error
YES
if string should
be accepted as-is, or NO
if string should be
rejected.See Also: - getObjectValue:forString:errorDescription:(NSFormatter)
- (void)control:(NSControl
*)control didFailToValidatePartialString:(NSString
*)string errorDescription:(NSString
*)error
See Also: - isPartialStringValid:newEditingString:errorDescription:(NSFormatter)
- (BOOL)control:(NSControl
*)control isValidObject:(id)object
YES
to
allow display of the string and NO
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.- (BOOL)control:(NSControl
*)control textShouldBeginEditing:(NSText
*)fieldEditor
YES
if
the NSControl's fieldEditor should
be allowed to start editing the text, NO
otherwise.- (BOOL)control:(NSControl
*)control textShouldEndEditing:(NSText
*)fieldEditor
YES
if the
control's fieldEditor should be
allowed to end its edit session, NO
otherwise.- (BOOL)control:(NSControl
*)control textView:(NSTextView *)textView doCommandBySelector:(SEL)command
YES
if it handles
the key binding, and NO
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.
- (void)controlTextDidBeginEditing:(NSNotification *)aNotification
- (void)controlTextDidEndEditing:(NSNotification *)aNotification
- (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.