NSControl Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.0 and later.
Companion guide
Declared in
NSControl.h
NSLayoutConstraint.h
Related sample code

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 the NSCell class.

About Delegate Methods

The NSControl class provides several delegate methods for its subclasses that allow text editing, such as NSTextField and NSMatrix. These include: controlTextDidBeginEditing:, controlTextDidChange:, and controlTextDidEndEditing:.

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. In addition, a formal delegate protocol NSControlTextEditingDelegate Protocol also defines delegate methods used by control delegates.

Tasks

Initializing an NSControl

Setting the Control’s Cell

Enabling and Disabling the Control

Identifying the Selected Cell

Getting and Setting the Control’s Value

Interacting with Other Controls

Formatting Text

Getting and Setting Expansion Tool Tips

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

Control Editing Notifications

Managing User Interface Layout Direction

Supporting Constraint-Based Layout

Class Methods

cellClass

Returns the type of cell used by the receiver.

+ (Class)cellClass
Return Value

The class of the cell used to manage the receiver's contents, or nil if no cell class has been set for the receiver or its superclasses (up to NSControl).

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSControl.h

setCellClass:

Sets the type of cell used by the receiver.

+ (void)setCellClass:(Class)class
Parameters
class

The class of the cell to use with this control.

Discussion

If you have a custom cell subclass that you would like to substitute for the class of a cell object in a nib file, you should set the cell class in the awakeFromNib method (NSNibAwaking protocol). You cannot change the class programmatically after the cell object has been unarchived from the nib and instantiated, which occurs immediately after awakeFromNib returns. If you are going to be using your custom cell frequently, consider creating your own Interface Builder palette containing the cell.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSControl.h

Instance Methods

abortEditing

Terminates the current editing operation and discards any edited text.

- (BOOL)abortEditing
Return Value

YES if there was a field editor associated with the control; otherwise, NO.

Discussion

If there was a field editor, this method removes the field editor’s delegate.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSControl.h

action

Returns the default action-message selector associated with the control.

- (SEL)action
Return Value

The selector associated with the receiver's cell.

Discussion

The NSControl implementation of this method returns the action message selector of the receiver's cell. Controls that support multiple cells (such as NSMatrix and NSForm) must override this method to return the appropriate action-message selector.

If you want the action-message selector for a control that has multiple cells, it is better to use the get the selector directly from the cell's own action method, as shown in the following example:

SEL someAction = [[theControl selectedCell] action];
Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSControl.h

alignment

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

- (NSTextAlignment)alignment
Availability
  • Available in OS X v10.0 and later.
Declared In
NSControl.h

allowsExpansionToolTips

Whether expansion tool tips are shown when the control is hovered over.

- (BOOL)allowsExpansionToolTips
Return Value

YES if the expansion tool tip will expand; NO otherwise.

Discussion

Expansion tooltips are shown when the cell can not show the full content and the user hovers over the control with the mouse. This is controlled by the NSCell class method expansionFrameWithFrame:inView: and is drawn by drawWithExpansionFrame:inView:. This value is encoded along with the control.

In general, it is recommended to turn this on for NSTextField instances in a view-based NSTableView.

The default value is NO.

Availability
  • Available in OS X v10.8 and later.
Declared In
NSControl.h

attributedStringValue

Returns the value of the receiver’s cell as an attributed string.

- (NSAttributedString *)attributedStringValue
Return Value

The value of the cell interpreted as an attributed string, or an empty attributed string if the receiver has no cell.

Discussion

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

Availability
  • Available in OS X v10.0 and later.
Declared In
NSControl.h

baseWritingDirection

Returns the initial writing direction used to determine the actual writing direction for text.

- (NSWritingDirection)baseWritingDirection
Return Value

One of the following values: NSWritingDirectionNatural, NSWritingDirectionLeftToRight, or NSWritingDirectionRightToLeft. The default value is NSWritingDirectionNatural.

Discussion

The Text system uses this value as a hint for calculating the actual direction for displaying Unicode characters. You should not need to call this method directly.

Availability
  • Available in OS X v10.4 and later.
Declared In
NSControl.h

calcSize

Recomputes any internal sizing information for the receiver, if necessary.

- (void)calcSize
Discussion

This method uses the calcDrawInfo: method of its cell to perform the calculations. Most controls 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, this method is automatically invoked before the control is displayed. You should never need to invoke it yourself.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSControl.h

cell

Returns the receiver’s cell object.

- (id)cell
Return Value

The cell object of the receiver.

Discussion

For controls with multiple cells (such as NSMatrix or NSForm), use the selectedCell method or a similar method to retrieve a specific cell.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSControl.h

currentEditor

Returns the current field editor for the control.

- (NSText *)currentEditor
Return Value

The field editor for the current control, or nil if the receiver does not have a field editor.

Discussion

When the receiver is a control displaying editable text (for example, a text field) and it is the first responder, it has a field editor, which is returned by this method. 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.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSControl.h

doubleValue

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

- (double)doubleValue
Return Value

The value of the cell interpreted as a double-precision floating-point number.

Discussion

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

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSControl.h

drawCell:

Draws the specified cell, as long as it belongs to the receiver.

- (void)drawCell:(NSCell *)aCell
Parameters
aCell

The cell to draw. If the cell does not belong to the receiver, this method does nothing.

Discussion

This method is provided primarily to support a consistent set of methods between NSControl objects with single and multiple cells, because a control with multiple cells needs to be able to draw individual cells.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSControl.h

drawCellInside:

Draws the inside of the receiver’s cell (the area within the bezel or border)

- (void)drawCellInside:(NSCell *)aCell
Parameters
aCell

The cell to draw. If the cell does not belong to the receiver, this method does nothing.

Discussion

If the receiver is transparent, the method causes the superview to draw itself. This method invokes the drawInteriorWithFrame:inView: method of NSCell. This method has no effect on controls (such as NSMatrix and NSForm) that have multiple cells.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSControl.h

floatValue

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

- (float)floatValue
Return Value

The value of the cell interpreted as a single-precision floating-point number.

Discussion

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

Availability
  • Available in OS X v10.0 and later.
Declared In
NSControl.h

font

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

- (NSFont *)font
Return Value

The font object used for drawing text.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSControl.h

formatter

Returns the receiver’s formatter.

- (id)formatter
Return Value

The formatter object.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSControl.h

ignoresMultiClick

Returns a Boolean value indicating whether the receiver ignores multiple clicks made in rapid succession.

- (BOOL)ignoresMultiClick
Return Value

YES if the receiver ignores multiple clicks; otherwise, NO.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSControl.h

initWithFrame:

Returns an NSControl object initialized with the specified frame rectangle.

- (id)initWithFrame:(NSRect)frameRect
Parameters
frameRect

The rectangle of the control, specified in points in the coordinate space of the enclosing view.

Return Value

An initialized control object, or nil if the object could not be initialized.

Discussion

If a cell has been specified for controls of this type, this method also creates an instance of the cell. Because NSControl is an abstract class, invocations of this method should appear only in the designated initializers of subclasses; that is, there should always be a more specific designated initializer for the subclass, as this method is the designated initializer for NSControl.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSControl.h

integerValue

Returns the value of the receiver’s cell as an NSInteger value.

- (NSInteger)integerValue
Return Value

The value of the cell interpreted as an NSInteger value.

Discussion

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

Availability
  • Available in OS X v10.5 and later.
Related Sample Code
Declared In
NSControl.h

intValue

Returns the value of the receiver’s cell as an integer.

- (int)intValue
Return Value

The value of the cell interpreted as an integer.

Discussion

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

Availability
  • Available in OS X v10.0 and later.
Declared In
NSControl.h

invalidateIntrinsicContentSizeForCell:

Notifies the control that the intrinsic content size for its cell is no longer valid.

- (void)invalidateIntrinsicContentSizeForCell:(NSCell *)cell
Parameters
cell

The cell whose intrinsic content size has changed.

Discussion

Controls determine their intrinsic content size based on the cell size for a given bounds returned by their cell. When the content of the cell changes in a way that would change the return value of cellSizeForBounds:, the cell needs to call this method to notify its control that its intrinsic size is no longer valid.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSLayoutConstraint.h

isContinuous

Returns a Boolean value indicating whether the receiver’s cell sends its action message continuously to its target during mouse tracking.

- (BOOL)isContinuous
Return Value

YES if the action message is sent continuously; otherwise, NO.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSControl.h

isEnabled

Returns whether the receiver reacts to mouse events.

- (BOOL)isEnabled
Return Value

YES if the receiver responds to mouse events; otherwise, NO.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSControl.h

mouseDown:

Informs the receiver that the user has pressed the left mouse button.

- (void)mouseDown:(NSEvent *)theEvent
Parameters
theEvent

The event resulting from the user action.

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 cell and sends it a trackMouse:inRect:ofView:untilMouseUp: message. Whenever the cell 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:inRect:ofView:untilMouseUp: 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.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSControl.h

objectValue

Returns the value of the receiver’s cell as an Objective-C object.

- (id)objectValue
Return Value

The value of the cell interpreted as an Objective-C object.

Discussion

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

Availability
  • Available in OS X v10.0 and later.
Declared In
NSControl.h

performClick:

Simulates a single mouse click on the receiver.

- (void)performClick:(id)sender
Parameters
sender

The object requesting the action. This parameter is ignored.

Discussion

This method calls the performClick: method of the receiver's cell with the sender being the control itself. This method raises an exception if the action message cannot be successfully sent.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSControl.h

refusesFirstResponder

Returns a Boolean value indicating whether the receiver refuses the first responder role.

- (BOOL)refusesFirstResponder
Return Value

YES if the receiver refuses the first responder role; otherwise, NO.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSControl.h

selectCell:

Selects the specified cell and redraws the control as needed.

- (void)selectCell:(NSCell *)aCell
Parameters
aCell

The cell to select. The cell must belong to the receiver.

Discussion

If the cell is already selected (or does not belong to the receiver), this method does nothing. If the cell belongs to the receiver and is not selected, this method changes its state to NSOnState and redraws the cell.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSControl.h

selectedCell

Returns the receiver’s selected cell.

- (id)selectedCell
Return Value

The selected cell object.

Discussion

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

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSControl.h

selectedTag

Returns the tag of the receiver’s selected cell.

- (NSInteger)selectedTag
Return Value

The tag of the selected cell, or -1 if no cell is selected.

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.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSControl.h

sendAction:to:

Causes the specified action to be sent the target.

- (BOOL)sendAction:(SEL)theAction to:(id)theTarget
Parameters
theAction

The selector to invoke on the target. If the selector is NULL, no message is sent.

theTarget

The target object to receive the message. If the object is nil, the application searches the responder chain for an object capable of handling the message. For more information on dispatching actions, see the class description for NSActionCell.

Return Value

YES if the message was successfully sent; otherwise, NO.

Discussion

This method uses the sendAction:to:from: method of NSApplication to invoke the specified method on an object. The receiver is passed as the parameter to the action message. This method is invoked primarily by the trackMouse:inRect:ofView:untilMouseUp: method of NSCell.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSControl.h

sendActionOn:

Sets the conditions on which the receiver sends action messages to its target.

- (NSInteger)sendActionOn:(NSInteger)mask
Parameters
mask

A bit mask containing the conditions for sending the action. The only conditions that are actually checked are associated with the NSLeftMouseDownMask, NSLeftMouseUpMask, NSLeftMouseDraggedMask, and NSPeriodicMask bits.

Return Value

A bit mask containing the previous settings. This bit mask uses the same values as specified in the mask parameter.

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. Because of this, the only bits checked in mask are NSLeftMouseDownMask, NSLeftMouseUpMask, NSLeftMouseDraggedMask, and NSPeriodicMask, which are declared in the NSEvent class reference.

The default implementation of this method simply invokes the sendActionOn: method of its associated cell.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSControl.h

setAction:

Sets the receiver's action method to the specified selector.

- (void)setAction:(SEL)aSelector
Parameters
aSelector

The new action-message selector to associate with the receiver's cell. Specify NULL to prevent action messages from being sent to the receiver's target.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSControl.h

setAlignment:

Sets the alignment of text in the receiver’s cell.

- (void)setAlignment:(NSTextAlignment)mode
Discussion

If the cell is currently being edited, this method aborts the edits to change the alignment.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSControl.h

setAllowsExpansionToolTips:

Sets whether expansion tool tips are shown when the control is hovered over.

- (void)setAllowsExpansionToolTips:(BOOL)value
Parameters
value

YES if the expansion tool tip should expand; NO otherwise.

Discussion

Expansion tooltips are shown when the cell can not show the full content and the user hovers over the control with the mouse. This is controlled by the NSCell class method expansionFrameWithFrame:inView: and is drawn by drawWithExpansionFrame:inView:. This value is encoded along with the control.

In general, it is recommended to turn this on for NSTextField instances in a view-based NSTableView.

The default value is NO.

Availability
  • Available in OS X v10.8 and later.
Declared In
NSControl.h

setAttributedStringValue:

Sets the value of the receiver’s cell using an attributed string.

- (void)setAttributedStringValue:(NSAttributedString *)object
Parameters
object

The value of the cell interpreted as an attributed string.

Discussion

If the cell is being edited, this method aborts all editing before setting the value. If the cell does not inherit from NSActionCell, the method marks the cell’s interior as needing to be redisplayed; NSActionCell performs its own updating of cells.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSControl.h

setBaseWritingDirection:

Sets the initial writing direction used to determine the actual writing direction for text .

- (void)setBaseWritingDirection:(NSWritingDirection)writingDirection
Parameters
writingDirection

One of the following values: NSWritingDirectionNatural, NSWritingDirectionLeftToRight, or NSWritingDirectionRightToLeft.

Discussion

If you know the base writing direction of the text you are rendering, you can use this method to specify that direction to the text system.

Availability
  • Available in OS X v10.4 and later.
Declared In
NSControl.h

setCell:

Sets the receiver’s cell

- (void)setCell:(NSCell *)aCell
Parameters
aCell

The new cell for the receiver.

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.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSControl.h

setContinuous:

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

- (void)setContinuous:(BOOL)flag
Parameters
flag

YES if the action message should be sent continuously; otherwise, NO.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSControl.h

setDoubleValue:

Sets the value of the receiver’s cell using a double-precision floating-point number.

- (void)setDoubleValue:(double)aDouble
Parameters
aDouble

The value of the cell interpreted as a double-precision floating-point number.

Discussion

If the cell is being edited, this method aborts all editing before setting the value. If the cell does not inherit from NSActionCell, the method marks the cell’s interior as needing to be redisplayed; NSActionCell performs its own updating of cells.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSControl.h

setEnabled:

Sets whether the receiver (and its cell) reacts to mouse events.

- (void)setEnabled:(BOOL)flag
Parameters
flag

YES if you want the receiver to react to mouse events; otherwise, NO.

Discussion

If flag is NO, any editing is aborted. This method 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; NSButton and NSSlider do this.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSControl.h

setFloatValue:

Sets the value of the receiver’s cell using a single-precision floating-point number.

- (void)setFloatValue:(float)aFloat
Parameters
aFloat

The value of the cell interpreted as a single-precision floating-point number.

Discussion

If the cell is being edited, this method aborts all editing before setting the value. If the cell does not inherit from NSActionCell, the method marks the cell’s interior as needing to be redisplayed; NSActionCell performs its own updating of cells.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSControl.h

setFont:

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

- (void)setFont:(NSFont *)fontObject
Parameters
fontObject

The font object to use.

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

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSControl.h

setFormatter:

Sets the receiver’s formatter

- (void)setFormatter:(NSFormatter *)newFormatter
Parameters
newFormatter

The new formatter object to use with the control.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSControl.h

setIgnoresMultiClick:

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

- (void)setIgnoresMultiClick:(BOOL)flag
Parameters
flag

YES if the receiver should ignore multiple clicks; otherwise, NO.

Discussion

By default, controls treat double clicks as two distinct clicks, triple clicks as three distinct clicks, and so on. However, if you pass YES to this method, additional clicks (within a predetermined interval after the first) occurring after the first click are not processed by the receiver, and are instead passed on to super.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSControl.h

setIntegerValue:

Sets the value of the receiver’s cell using an NSInteger value.

- (void)setIntegerValue:(NSInteger)anInteger
Parameters
anInteger

The value of the cell interpreted as an NSInteger value.

Discussion

If the cell is being edited, this method aborts all editing before setting the value. If the cell does not inherit from NSActionCell, the method marks the cell’s interior as needing to be redisplayed; NSActionCell performs its own updating of cells.

Availability
  • Available in OS X v10.5 and later.
Related Sample Code
Declared In
NSControl.h

setIntValue:

Sets the value of the receiver’s cell using an integer.

- (void)setIntValue:(int)anInt
Parameters
anInt

The value of the cell interpreted as an integer.

Discussion

If the cell is being edited, this method aborts all editing before setting the value. If the cell does not inherit from NSActionCell, the method marks the cell’s interior as needing to be redisplayed; NSActionCell performs its own updating of cells.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSControl.h

setNeedsDisplay

Marks the receiver as needing redisplay (assuming automatic display is enabled).

- (void)setNeedsDisplay
Discussion

This method also recalculates the dimensions of the control as needed.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSControl.h

setObjectValue:

Sets the value of the receiver’s cell using an Objective-C object.

- (void)setObjectValue:(id < NSCopying >)object
Parameters
object

The value of the cell interpreted as an Objective-C object.

Discussion

If the cell is being edited, this method aborts all editing before setting the value. If the cell does not inherit from NSActionCell, the method marks the cell’s interior as needing to be redisplayed; NSActionCell performs its own updating of cells.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSControl.h

setRefusesFirstResponder:

Sets whether the receiver refuses first responder role.

- (void)setRefusesFirstResponder:(BOOL)flag
Parameters
flag

YES if the receiver should refuse the first responder role; otherwise, NO.

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 non-text controls, a faint rectangle), the user can activate the control by pressing the Space bar.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSControl.h

setStringValue:

Sets the value of the receiver’s cell using an NSString object.

- (void)setStringValue:(NSString *)aString
Parameters
aString

The value of the cell interpreted as an NSString object.

Discussion

If the cell is being edited, this method aborts all editing before setting the value. If the cell does not inherit from NSActionCell, the method marks the cell’s interior as needing to be redisplayed; NSActionCell performs its own updating of cells.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSControl.h

setTag:

Sets the tag of the receiver.

- (void)setTag:(NSInteger)anInt
Parameters
anInt

The new tag.

Discussion

This method does not 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 and use them at runtime in your application. 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.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSControl.h

setTarget:

Sets the target object to receive action messages from the receiver’s cell.

- (void)setTarget:(id)anObject
Parameters
anObject

The new target object to associate with the receiver's cell, or nil to remove the current target.

Discussion

If anObject is nil but the control still has a valid action message assigned, the application follows the responder chain looking for an object that can respond to the message. See the description of the NSActionCell class for details.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSControl.h

setUserInterfaceLayoutDirection:

Sets the user interface layout direction of the receiver.

- (void)setUserInterfaceLayoutDirection:(NSUserInterfaceLayoutDirection)value
Parameters
value

An NSUserInterfaceLayoutDirection constant to specify the layout direction of the receiver.

Availability
  • Available in OS X v10.8 and later.
Declared In
NSControl.h

sizeToFit

Resizes the receiver’s frame so that it is the minimum size needed to contain its cell.

- (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 thedisplay or setNeedsDisplay method.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSControl.h

stringValue

Returns the value of the receiver’s cell as an NSString object.

- (NSString *)stringValue
Return Value

The value of the cell interpreted as an NSString object.

Discussion

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

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSControl.h

tag

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

- (NSInteger)tag
Return Value

The tag of this control object.

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 and use them at runtime in your application. 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.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSControl.h

takeDoubleValueFrom:

Sets the value of the receiver’s cell to a double-precision floating-point value obtained from the specified object.

- (void)takeDoubleValueFrom:(id)sender
Parameters
sender

The object from which to take the value. This object must respond to the doubleValue message.

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 sends this message to the text field. The text field then obtains the slider’s value, turns it into a text string, and displays it.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSControl.h

takeFloatValueFrom:

Sets the value of the receiver’s cell to a single-precision floating-point value obtained from the specified object.

- (void)takeFloatValueFrom:(id)sender
Parameters
sender

The object from which to take the value. This object must respond to the floatValue message.

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 sends this message to the text field. The text field then obtains the slider’s value, turns it into a text string, and displays it.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSControl.h

takeIntegerValueFrom:

Sets the value of the receiver’s cell to an NSInteger value obtained from the specified object.

- (void)takeIntegerValueFrom:(id)sender
Parameters
sender

The object from which to take the value. This object must respond to the integerValue message.

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 sends this message to the text field. The text field then obtains the slider’s value, turns it into a text string, and displays it.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSControl.h

takeIntValueFrom:

Sets the value of the receiver’s cell to an integer value obtained from the specified object.

- (void)takeIntValueFrom:(id)sender
Parameters
sender

The object from which to take the value. This object must respond to the intValue message.

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 sends this message to the text field. The text field then obtains the slider’s value, turns it into a text string, and displays it.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSControl.h

takeObjectValueFrom:

Sets the value of the receiver’s cell to the object value obtained from the specified object.

- (void)takeObjectValueFrom:(id)sender
Parameters
sender

The object from which to take the value. This object must respond to the objectValue message.

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 sends this message to the text field. The text field then obtains the slider’s value, turns it into a text string, and displays it.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSControl.h

takeStringValueFrom:

Sets the value of the receiver’s cell to the string value obtained from the specified object.

- (void)takeStringValueFrom:(id)sender
Parameters
sender

The object from which to take the value. This object must respond to the stringValue message.

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 sends this message to the text field. The text field then obtains the slider’s value, turns it into a text string, and displays it.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSControl.h

target

Returns the target object of the receiver’s cell.

- (id)target
Return Value

The target object that receives action messages from the cell.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSControl.h

updateCell:

Marks the specified cell as in need of redrawing.

- (void)updateCell:(NSCell *)aCell
Parameters
aCell

The cell to redraw.

Discussion

If the cell currently has the focus, this method updates the cell's focus ring; otherwise, the entire cell is marked as needing redisplay. The cell is redrawn during the next update cycle.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSControl.h

updateCellInside:

Marks the inside of the specified cell as in need of redrawing.

- (void)updateCellInside:(NSCell *)aCell
Parameters
aCell

The cell to redraw.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSControl.h

userInterfaceLayoutDirection

Returns the user interface layout direction of the receiver.

- (NSUserInterfaceLayoutDirection)userInterfaceLayoutDirection
Return Value

An NSUserInterfaceLayoutDirection constant specifying the layout direction of the receiver.

Discussion

This method is a cover method for userInterfaceLayoutDirection on NSCell. Some subclasses, such as NSOutlineView, may override this and provide more customized behavior.

Availability
  • Available in OS X v10.8 and later.
Declared In
NSControl.h

validateEditing

Validates changes to any user-typed text.

- (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 NSString or an attributed string object based on the attributes of the editor.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSControl.h

Delegate Methods

controlTextDidBeginEditing:

Sent when a control with editable text begins an editing session.

- (void)controlTextDidBeginEditing:(NSNotification *)aNotification
Parameters
aNotification

The notification object. The name of the notification is always NSControlTextDidBeginEditingNotification.

Discussion

This method is invoked when the user begins editing text in a control such as a text field or a form field. The control posts a NSControlTextDidBeginEditingNotification notification, and if the control’s delegate implements this method, it is automatically registered to receive the notification. Use the key @"NSFieldEditor" to obtain the field editor from the userInfo dictionary of the notification object.

See controlTextDidEndEditing: for an explanation of why you may not always get one invocation of controlTextDidBeginEditing: for each invocation of controlTextDidEndEditing:.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSControl.h

controlTextDidChange:

Sent when the text in the receiving control changes.

- (void)controlTextDidChange:(NSNotification *)aNotification
Parameters
aNotification

The notification object. The name of the notification is always NSControlTextDidChangeNotification.

Discussion

This method is invoked when text in a control such as a text field or form changes. The control posts a NSControlTextDidChangeNotification notification, and if the control’s delegate implements this method, it is automatically registered to receive the notification. Use the key @"NSFieldEditor" to obtain the field editor from the userInfo dictionary of the notification object.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSControl.h

controlTextDidEndEditing:

Sent when a control with editable text ends an editing session.

- (void)controlTextDidEndEditing:(NSNotification *)aNotification
Parameters
aNotification

The notification object. The name of the notification is always NSControlTextDidEndEditingNotification.

Discussion

This method is invoked when the user stops editing text in a control such as a text field or form. The control posts a NSControlTextDidEndEditingNotification notification, and if the control’s delegate implements this method, it is automatically registered to receive the notification. Use the key @"NSFieldEditor" to obtain the field editor from the userInfo dictionary of the notification object.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSControl.h

Notifications

An NSControl object posts the following notifications to interested observers and its delegate. Note that although the NSControl class 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.

NSControlTextDidBeginEditingNotification

Sent when a control with editable cells begins an edit session.

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

Key

Value

@"NSFieldEditor"

The edited cell’s field editor

See the controlTextDidEndEditing: method for details.

Availability
Declared In
NSControl.h

NSControlTextDidChangeNotification

Sent when the text in the receiving control changes.

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

Key

Value

@"NSFieldEditor"

The edited cell’s field editor

See the controlTextDidChange: method for details.

Availability
Declared In
NSControl.h

NSControlTextDidEndEditingNotification

Sent when a control with editable cells ends an editing session.

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

Key

Value

@"NSFieldEditor"

The edited cell’s field editor

See the controlTextDidEndEditing: method for details.

Availability
Declared In
NSControl.h