Mac Developer Library

Developer

AppKit Framework Reference NSControl Class Reference

Options
Deployment Target:

On This Page
Language:

NSControl

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.

    Availability

    Available in OS X v10.0 and later.

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

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.10.

    See Also

    cell

  • cell cell (OS X v10.11) Property

    The receiver’s cell object.

    Declaration

    Swift

    var cell: NSCell?

    Objective-C

    @property(strong) __kindof NSCell *cell

    Discussion

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

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.11.

    See Also

    + cellClass

  • A Boolean value that indicates whether the receiver reacts to mouse events.

    Declaration

    Swift

    var enabled: Bool

    Objective-C

    @property(getter=isEnabled) BOOL enabled

    Discussion

    The value of this property is YEStrue if the receiver responds to mouse events; otherwise, NOfalse.

    Availability

    Available in OS X v10.0 and later.

  • Returns the receiver’s selected cell.

    Declaration

    Swift

    func selectedCell() -> NSCell?

    Objective-C

    - (__kindofNSCell *)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.

    Deprecated in OS X v10.10.

    See Also

    cell

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

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.10.

    See Also

    tag

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

    Declaration

    Swift

    var doubleValue: Double

    Objective-C

    @property double doubleValue

    Discussion

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

    If the cell is being edited, setting this property aborts all editing before setting the value. If the cell does not inherit from NSActionCell, setting this property 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.

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

    Declaration

    Swift

    var floatValue: Float

    Objective-C

    @property float floatValue

    Discussion

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

    If the cell is being edited, setting this property aborts all editing before setting the value. If the cell does not inherit from NSActionCell, setting this property 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.

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

    Declaration

    Swift

    var intValue: Int32

    Objective-C

    @property int intValue

    Discussion

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

    If the cell is being edited, setting this property aborts all editing before setting the value. If the cell does not inherit from NSActionCell, setting this property 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.

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

    Declaration

    Swift

    var integerValue: Int

    Objective-C

    @property NSInteger integerValue

    Discussion

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

    If the cell is being edited, setting this property aborts all editing before setting the value. If the cell does not inherit from NSActionCell, setting this property 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.

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

    Declaration

    Swift

    @NSCopying var objectValue: AnyObject?

    Objective-C

    @property(copy) id objectValue

    Discussion

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

    If the cell is being edited, setting this property aborts all editing before setting the value. If the cell does not inherit from NSActionCell, setting this property 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.

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

    Declaration

    Swift

    var stringValue: String

    Objective-C

    @property(copy) NSString *stringValue

    Discussion

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

    If the cell is being edited, setting this property aborts all editing before setting the value. If the cell does not inherit from NSActionCell, setting this property 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.

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

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.10.

    See Also

    setNeedsDisplay: (NSView)

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

    Declaration

    Swift

    @NSCopying var attributedStringValue: NSAttributedString

    Objective-C

    @property(copy) NSAttributedString *attributedStringValue

    Discussion

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

    If the cell is being edited, setting this property aborts all editing before setting the value. If the cell does not inherit from NSActionCell, setting the property 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.

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

    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.

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

    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.

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

    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.

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

    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.

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

    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.

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

    Declaration

    Swift

    var alignment: NSTextAlignment

    Objective-C

    @property NSTextAlignment alignment

    Discussion

    The value of this property can be one of the following constants: NSLeftTextAlignment, NSRightTextAlignment,NSCenterTextAlignment, NSJustifiedTextAlignment, or NSNaturalTextAlignment. The default value is NSNaturalTextAlignment. Setting this property while the cell is currently being edited aborts the edits to change the alignment.

    Availability

    Available in OS X v10.0 and later.

  • font font Property

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

    Declaration

    Swift

    @NSCopying var font: NSFont?

    Objective-C

    @property(copy) NSFont *font

    Discussion

    If the cell is being edited, setting this property causes the text in the cell to be 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.

  • The line break mode to use for text in the control’s cell.

    Declaration

    Swift

    var lineBreakMode: NSLineBreakMode

    Objective-C

    @property NSLineBreakMode lineBreakMode

    Discussion

    For a list of possible values, see NSLineBreakMode.

    Availability

    Available in OS X v10.10 and later.

  • A Boolean value that indicates whether the text in the control’s cell uses single line mode.

    Declaration

    Swift

    var usesSingleLineMode: Bool

    Objective-C

    @property BOOL usesSingleLineMode

    Discussion

    See usesSingleLineMode for details.

    Availability

    Available in OS X v10.10 and later.

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

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.0.

  • The receiver’s formatter.

    Declaration

    Swift

    var formatter: NSFormatter?

    Objective-C

    @property(strong) __kindof NSFormatter *formatter

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    var baseWritingDirection: NSWritingDirection

    Objective-C

    @property NSWritingDirection baseWritingDirection

    Discussion

    This property can have one of the following values: NSWritingDirectionNatural, NSWritingDirectionLeftToRight, or NSWritingDirectionRightToLeft. The default value is NSWritingDirectionNatural. The text system uses this value as a hint for calculating the actual direction for displaying Unicode characters. You should not need to access this value directly. If you know the base writing direction of the text you are rendering, you can set this property to specify that direction to the text system.

    Availability

    Available in OS X v10.4 and later.

  • Performs custom expansion tool tip drawing.

    Declaration

    Swift

    func drawWithExpansionFrame(_ contentFrame: NSRect, inView view: NSView)

    Objective-C

    - (void)drawWithExpansionFrame:(NSRect)contentFrame inView:(NSView *)view

    Parameters

    contentFrame

    The frame in which to draw.

    view

    The view in which to draw.

    Discussion

    Note that the view may be different from the original view in which the text appeared.

    Availability

    Available in OS X v10.10 and later.

  • A Boolean value that indicates whether expansion tool tips are shown when the control is hovered over.

    Declaration

    Swift

    var allowsExpansionToolTips: Bool

    Objective-C

    @property BOOL allowsExpansionToolTips

    Discussion

    When the value of this property is YEStrue, the expansion tool tip will expand; NOfalse means the tool tip won’t expand. The default value is NOfalse.

    Expansion tooltips are shown when the cell cannot show the full content and the user hovers the pointer over the control. 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.

    Availability

    Available in OS X v10.8 and later.

  • The frame in which a tool tip can be displayed, if needed.

    Declaration

    Swift

    func expansionFrameWithFrame(_ contentFrame: NSRect) -> NSRect

    Objective-C

    - (NSRect)expansionFrameWithFrame:(NSRect)contentFrame

    Parameters

    contentFrame

    The frame of the control.

    Return Value

    The frame in which the tool tip should be displayed, or NSZeroRect by default.

    Discussion

    This method lets the control return an expansion tool tip frame if contentFrame is too small for the entire contents in the view. When the pointer hovers over the text in certain controls, the full contents will be shown in a special floating tool tip view. If the frame is big enough to display the contents, return an empty rect from this method and no expansion tool tip view will be shown. Note that some subclasses, such as NSTextField, return the proper frame when required.

    Availability

    Available in OS X v10.10 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.

    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.

    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.

    Availability

    Available in OS X v10.0 and later.

  • Begins editing of the receiver’s text using the specified field editor.

    Declaration

    Swift

    func editWithFrame(_ aRect: NSRect, editor textObj: NSText, delegate anObject: AnyObject?, event theEvent: NSEvent)

    Objective-C

    - (void)editWithFrame:(NSRect)aRect editor:(NSText *)textObj delegate:(id)anObject event:(NSEvent *)theEvent

    Parameters

    aRect

    The bounding rectangle of the control’s cell.

    textObj

    The field editor to use.

    anObject

    The object to use as a delegate for the field editor. This delegate object receives various NSText delegation and notification methods during the course of editing the cell's contents.

    theEvent

    The NSLeftMouseDown event that initiated the editing behavior.

    Discussion

    For a receiver that is a control with editable text (such as an NSTextField object), the field editor is sized to aRect and is then activated and editing begins. It’s the responsibility of the delegate to end editing when responding to control:textShouldEndEditing:. Upon ending the editing session, the delegate should remove any data from the field editor.

    Availability

    Available in OS X v10.10 and later.

  • Ends the editing of text in the receiver using the specified field editor.

    Declaration

    Swift

    func endEditing(_ textObj: NSText)

    Objective-C

    - (void)endEditing:(NSText *)textObj

    Parameters

    textObj

    The field editor currently handling the editing of the cell's content.

    Discussion

    Ends any editing of text that began with a call to editWithFrame:editor:delegate:event: or selectWithFrame:editor:delegate:start:length:.

    Availability

    Available in OS X v10.10 and later.

  • Selects the specified text range in the receiver's field editor.

    Declaration

    Swift

    func selectWithFrame(_ aRect: NSRect, editor textObj: NSText, delegate anObject: AnyObject?, start selStart: Int, length selLength: Int)

    Objective-C

    - (void)selectWithFrame:(NSRect)aRect editor:(NSText *)textObj delegate:(id)anObject start:(NSInteger)selStart length:(NSInteger)selLength

    Parameters

    aRect

    The bounding rectangle of the control’s cell.

    textObj

    The field editor to use.

    anObject

    The object to use as a delegate for the field editor. This delegate object receives various NSText delegation and notification methods during the course of editing the cell's contents.

    selStart

    The start of the text selection.

    selLength

    The length of the text range.

    Discussion

    This method is similar to editWithFrame:editor:delegate:event:, except that it can be invoked in any situation, not only on a mouse-down event. This method returns without doing anything if textObj or the receiver is nil, or if the receiver has no font set for it.

    Availability

    Available in OS X v10.10 and later.

  • The size of the control.

    Declaration

    Swift

    var controlSize: NSControlSize

    Objective-C

    @property NSControlSize controlSize

    Availability

    Available in OS X v10.10 and later.

  • Asks the control to calculate and return the size that best fits the specified size.

    Declaration

    Swift

    func sizeThatFits(_ size: NSSize) -> NSSize

    Objective-C

    - (NSSize)sizeThatFits:(NSSize)size

    Parameters

    size

    The size for which the control should calculate its best-fitting size.

    Return Value

    A new size that fits the receiver’s subviews.

    Discussion

    By default, this method returns the intrinsicContentSize of the receiver.

    Availability

    Available in OS X v10.10 and later.

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

    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.

    Availability

    Available in OS X v10.0 and later.

    See Also

    – calcSize

  • A Boolean value that indicates whether the cell is highlighted.

    Declaration

    Swift

    var highlighted: Bool

    Objective-C

    @property(getter=isHighlighted) BOOL highlighted

    Availability

    Available in OS X v10.10 and later.

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

    Availability

    Available in OS X v10.0 and later.

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

    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.

    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.

    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.

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.10.

    See Also

    – updateCell:

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

    Declaration

    Swift

    var action: Selector

    Objective-C

    @property SEL action

    Discussion

    This property contains the action message selector of the receiver's cell. Controls that support multiple cells (such as NSMatrix and NSForm) must supply the appropriate action-message selector in this property. Specify NULL to prevent action messages from being sent to the receiver's target.

    If you want the action-message selector for a control that has multiple cells, it is better to get the selector directly from the cell's own action property.

    Availability

    Available in OS X v10.0 and later.

    See Also

    target

  • The target object that receives action messages from the cell.

    Declaration

    Swift

    weak var target: AnyObject?

    Objective-C

    @property(weak) id target

    Discussion

    When the value of this property is nil, 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.

    See Also

    action

  • A Boolean value indicating 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

    Discussion

    The value of this property is YEStrue if the action message is sent continuously; otherwise, NOfalse.

    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.

    Availability

    Available in OS X v10.0 and later.

    See Also

    action
    target

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

    Availability

    Available in OS X v10.0 and later.

  • tag tag Property

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

    Declaration

    Swift

    var tag: Int

    Objective-C

    @property NSInteger tag

    Discussion

    Tags allow you to identify particular controls. Tag values are not used internally; they are only changed when you set this property. 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.

    See Also

    – selectedTag

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

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    var refusesFirstResponder: Bool

    Objective-C

    @property BOOL refusesFirstResponder

    Discussion

    The value of this property is YEStrue if the receiver refuses the first responder role; otherwise, NOfalse.

    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.

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    var ignoresMultiClick: Bool

    Objective-C

    @property BOOL ignoresMultiClick

    Discussion

    The value of this property is YEStrue if the receiver ignores multiple clicks; otherwise, NOfalse.

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

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

    Declaration

    Swift

    func controlTextDidBeginEditing(_ obj: 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:.

    Availability

    Available in OS X v10.0 and later.

  • Sent when the text in the receiving control changes.

    Declaration

    Swift

    func controlTextDidChange(_ obj: 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.

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func controlTextDidEndEditing(_ obj: 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.

    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.

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    let NSControlTextDidBeginEditingNotification: String

    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.

    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.

    Declaration

    Swift

    let NSControlTextDidChangeNotification: String

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    let NSControlTextDidEndEditingNotification: String

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.