Mac Developer Library

Developer

AppKit Framework Reference NSControl Class Reference

Options
Deployment Target:

On This Page
Language:

NSControl

Conforms To


Import Statement


Swift

import AppKit

Objective-C

@import AppKit;

Availability


Available in OS X v10.0 and later.

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.

  • init(frame:) - initWithFrame: Designated Initializer

    Returns an NSControl object initialized with the specified frame rectangle.

    Declaration

    Swift

    init(frame frameRect: NSRect)

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • cellClass() + cellClass (OS X v10.10)

    Returns the type of cell used by the receiver.

    Declaration

    Swift

    class func cellClass() -> AnyClass?

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.10.

  • Sets the type of cell used by the receiver.

    Declaration

    Swift

    class func setCellClass(_ class: AnyClass?)

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.10.

  • cell() - cell (OS X v10.10)

    Returns the receiver’s cell object.

    Declaration

    Swift

    func cell() -> AnyObject?

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.10.

  • setCell(_:) - setCell: (OS X v10.10)

    Sets the receiver’s cell

    Declaration

    Swift

    func setCell(_ aCell: NSCell?)

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.10.

  • isEnabled - isEnabled Available in OS X v10.0 through OS X v10.9

    Returns whether the receiver reacts to mouse events.

    Declaration

    Objective-C

    - (BOOL)isEnabled

    Return Value

    YEStrue if the receiver responds to mouse events; otherwise, NOfalse.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 through OS X v10.9.

    See Also

    – setEnabled:

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

    Declaration

    Swift

    var enabled: Bool

    Objective-C

    @property(getter=isEnabled) BOOL enabled

    Parameters

    flag

    YEStrue if you want the receiver to react to mouse events; otherwise, NOfalse.

    Discussion

    If flag is NOfalse, 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – isEnabled

  • Returns the receiver’s selected cell.

    Declaration

    Swift

    func selectedCell() -> AnyObject?

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.10.

  • Returns the tag of the receiver’s selected cell.

    Declaration

    Swift

    func selectedTag() -> Int

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.10.

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

    Declaration

    Swift

    var doubleValue: Double

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    var doubleValue: Double

    Objective-C

    @property double doubleValue

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    var floatValue: Float

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    var floatValue: Float

    Objective-C

    @property float floatValue

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    var intValue: Int32

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    var intValue: Int32

    Objective-C

    @property int intValue

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    var integerValue: Int

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    var integerValue: Int

    Objective-C

    @property NSInteger integerValue

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    @NSCopying var objectValue: AnyObject?

    Objective-C

    @property(copy) 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    @NSCopying var objectValue: AnyObject?

    Objective-C

    @property(copy) id objectValue

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    var stringValue: String

    Objective-C

    @property(copy) 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    var stringValue: String

    Objective-C

    @property(copy) NSString *stringValue

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func setNeedsDisplay()

    Objective-C

    - (void)setNeedsDisplay

    Discussion

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.10.

    See Also

    setNeedsDisplay: (NSView)

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

    Declaration

    Swift

    @NSCopying var attributedStringValue: NSAttributedString

    Objective-C

    @property(copy) 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    @NSCopying var attributedStringValue: NSAttributedString

    Objective-C

    @property(copy) NSAttributedString *attributedStringValue

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func takeDoubleValueFrom(_ sender: AnyObject?)

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func takeFloatValueFrom(_ sender: AnyObject?)

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func takeIntValueFrom(_ sender: AnyObject?)

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func takeIntegerValueFrom(_ sender: AnyObject?)

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    func takeObjectValueFrom(_ sender: AnyObject?)

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func takeStringValueFrom(_ sender: AnyObject?)

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    var alignment: NSTextAlignment

    Objective-C

    @property NSTextAlignment alignment

    Return Value

    One of the following constants: NSLeftTextAlignment, NSRightTextAlignment,NSCenterTextAlignment, NSJustifiedTextAlignment, or NSNaturalTextAlignment. The default value is NSNaturalTextAlignment.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    var alignment: NSTextAlignment

    Objective-C

    @property NSTextAlignment alignment

    Parameters

    mode

    One of the following constants: NSLeftTextAlignment, NSRightTextAlignment,NSCenterTextAlignment, NSJustifiedTextAlignment, or NSNaturalTextAlignment.

    Discussion

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – alignment

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

    Declaration

    Swift

    @NSCopying var font: NSFont?

    Objective-C

    @property(copy) NSFont *font

    Return Value

    The font object used for drawing text.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – setFont:

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

    Declaration

    Swift

    @NSCopying var font: NSFont?

    Objective-C

    @property(copy) NSFont *font

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – font

  • Sets the auto-ranging and floating point number format of the receiver’s cell.

    Declaration

    Objective-C

    - (void)setFloatingPointFormat:(BOOL)autoRange left:(NSUInteger)leftDigits right:(NSUInteger)rightDigits

    Parameters

    autoRange

    YEStrue to enable auto-ranging; otherwise, NOfalse.

    leftDigits

    The number of digits to display to the left of the decimal point.

    rightDigits

    The number of digits to display to the right of the decimal point.

    Discussion

    For more information about auto-ranging and how it works, see the description of this method in the NSCell class specification. If the cell is being edited, the current edits are discarded and the cell’s interior is redrawn.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.0.

  • Returns the receiver’s formatter.

    Declaration

    Swift

    var formatter: AnyObject?

    Objective-C

    @property(strong) id formatter

    Return Value

    The formatter object.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets the receiver’s formatter

    Declaration

    Swift

    var formatter: AnyObject?

    Objective-C

    @property(strong) id formatter

    Parameters

    newFormatter

    The new formatter object to use with the control.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – formatter

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

    Declaration

    Swift

    var baseWritingDirection: NSWritingDirection

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    var baseWritingDirection: NSWritingDirection

    Objective-C

    @property NSWritingDirection baseWritingDirection

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    var allowsExpansionToolTips: Bool

    Objective-C

    @property BOOL allowsExpansionToolTips

    Return Value

    YEStrue if the expansion tool tip will expand; NOfalse 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 NOfalse.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.8 and later.

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

    Declaration

    Swift

    var allowsExpansionToolTips: Bool

    Objective-C

    @property BOOL allowsExpansionToolTips

    Parameters

    value

    YEStrue if the expansion tool tip should expand; NOfalse 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 NOfalse.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.8 and later.

  • Terminates the current editing operation and discards any edited text.

    Declaration

    Swift

    func abortEditing() -> Bool

    Objective-C

    - (BOOL)abortEditing

    Return Value

    YEStrue if there was a field editor associated with the control; otherwise, NOfalse.

    Discussion

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the current field editor for the control.

    Declaration

    Swift

    func currentEditor() -> NSText?

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Validates changes to any user-typed text.

    Declaration

    Swift

    func validateEditing()

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • calcSize() - calcSize (OS X v10.10)

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

    Declaration

    Swift

    func calcSize()

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.10.

    See Also

    – sizeToFit

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

    Declaration

    Swift

    func sizeToFit()

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – calcSize

  • Selects the specified cell and redraws the control as needed.

    Declaration

    Swift

    func selectCell(_ aCell: NSCell)

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.10.

  • drawCell(_:) - drawCell: (OS X v10.10)

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

    Declaration

    Swift

    func drawCell(_ aCell: NSCell)

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.10.

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

    Declaration

    Swift

    func drawCellInside(_ aCell: NSCell)

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.10.

  • Marks the specified cell as in need of redrawing.

    Declaration

    Swift

    func updateCell(_ aCell: NSCell)

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.10.

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

    Declaration

    Swift

    func updateCellInside(_ aCell: NSCell)

    Objective-C

    - (void)updateCellInside:(NSCell *)aCell

    Parameters

    aCell

    The cell to redraw.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.10.

    See Also

    – updateCell:

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

    Declaration

    Swift

    var action: Selector

    Objective-C

    @property 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];

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    var action: Selector

    Objective-C

    @property SEL action

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the target object of the receiver’s cell.

    Declaration

    Swift

    weak var target: AnyObject?

    Objective-C

    @property(weak) id target

    Return Value

    The target object that receives action messages from the cell.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    weak var target: AnyObject?

    Objective-C

    @property(weak) id target

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • isContinuous - isContinuous Available in OS X v10.0 through OS X v10.9

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

    Declaration

    Objective-C

    - (BOOL)isContinuous

    Return Value

    YEStrue if the action message is sent continuously; otherwise, NOfalse.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 through OS X v10.9.

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

    Declaration

    Swift

    var continuous: Bool

    Objective-C

    @property(getter=isContinuous) BOOL continuous

    Parameters

    flag

    YEStrue if the action message should be sent continuously; otherwise, NOfalse.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Causes the specified action to be sent the target.

    Declaration

    Swift

    func sendAction(_ theAction: Selector, to theTarget: AnyObject?) -> Bool

    Objective-C

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

    YEStrue if the message was successfully sent; otherwise, NOfalse.

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func sendActionOn(_ mask: Int) -> Int

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    var tag: Int

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets the tag of the receiver.

    Declaration

    Swift

    var tag: Int

    Objective-C

    @property NSInteger tag

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Simulates a single mouse click on the receiver.

    Declaration

    Swift

    func performClick(_ sender: AnyObject?)

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func refusesFirstResponder() -> Bool

    Objective-C

    - (BOOL)refusesFirstResponder

    Return Value

    YEStrue if the receiver refuses the first responder role; otherwise, NOfalse.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets whether the receiver refuses first responder role.

    Declaration

    Swift

    func setRefusesFirstResponder(_ flag: Bool)

    Objective-C

    - (void)setRefusesFirstResponder:(BOOL)flag

    Parameters

    flag

    YEStrue if the receiver should refuse the first responder role; otherwise, NOfalse.

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func mouseDown(_ theEvent: NSEvent)

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    var ignoresMultiClick: Bool

    Objective-C

    @property BOOL ignoresMultiClick

    Return Value

    YEStrue if the receiver ignores multiple clicks; otherwise, NOfalse.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    var ignoresMultiClick: Bool

    Objective-C

    @property BOOL ignoresMultiClick

    Parameters

    flag

    YEStrue if the receiver should ignore multiple clicks; otherwise, NOfalse.

    Discussion

    By default, controls treat double clicks as two distinct clicks, triple clicks as three distinct clicks, and so on. However, if you pass YEStrue 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func controlTextDidBeginEditing(_ aNotification: NSNotification)

    Objective-C

    - (void)controlTextDidBeginEditing:(NSNotification *)aNotification

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sent when the text in the receiving control changes.

    Declaration

    Swift

    func controlTextDidChange(_ aNotification: NSNotification)

    Objective-C

    - (void)controlTextDidChange:(NSNotification *)aNotification

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func controlTextDidEndEditing(_ aNotification: NSNotification)

    Objective-C

    - (void)controlTextDidEndEditing:(NSNotification *)aNotification

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func invalidateIntrinsicContentSizeForCell(_ cell: NSCell)

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.