Mac Developer Library

Developer

AppKit Framework Reference NSButton Class Reference

Options
Deployment Target:

On This Page
Language:

NSButton

Inheritance


Conforms To


Import Statement


Swift

import AppKit

Objective-C

@import AppKit;

Availability


Available in OS X v10.0 and later.

NSButton is a subclass of the NSControl class. An NSButton object sends an action message to a target object, such as a view controller, when the button is clicked. When configured as continuous, the button continues to send repeating action messages at timed intervals until released.

There are multiple types of buttons, each with a different user interface and behavior. Button types are defined in the NSButtonCell class, and are configured by calling the setButtonType: method.

If you configure it as an accelerator button (type NSAcceleratorButton or NSMultiLevelAcceleratorButton), a button can be set to send action messages when changes in pressure occur when the user clicks on the button.

Buttons can either have two states (on and off) or three states (on, off, and mixed). You enable a three-state button by calling the allowsMixedState method. On and off states (also referred to as alternate and normal) indicate that the button is either clicked or not clicked. Mixed state is typically used for checkboxes or radio buttons, which allow for an additional intermediate state. For example, suppose the state of a checkbox denotes whether a text field contains bold text. If all of the text in the text field is bold, then the checkbox is on. If none of the text is bold, then the checkbox is off. If some of the text is bold, then the checkbox is mixed.

For most types of buttons, the value of the button matches its state—the value is 1 for on, 0 for off, or -1 for mixed. For pressure-sensitive buttons, the value of the button indicates pressure level instead.

NSButton and NSMatrix both provide a control view, which displays an NSButtonCell object. However, while a matrix requires you to access the button cell objects directly, most button class methods act as “covers” for identically declared button cell methods. In other words, the implementation of the button method invokes the corresponding button cell method for you, allowing you to be unconcerned with the existence of the button cell. The only button cell methods that don’t have covers relate to the font used to display the key equivalent and to specific methods for highlighting or showing the state of the button.

  • Sets the button’s type, which affects its user interface and behavior when clicked.

    Declaration

    Swift

    func setButtonType(_ aType: NSButtonType)

    Objective-C

    - (void)setButtonType:(NSButtonType)aType

    Parameters

    aType

    A constant specifying the type of the button. The available button types are listed under NSButtonType in the NSButtonCell class.

    Discussion

    This method causes the button to update to reflect the new type before the method finishes executing.

    The types available are for the most common button types, which are also accessible in Interface Builder. You can configure different behavior with the NSButtonCell methods setHighlightsBy: and setShowsStateBy:.

    Note that there is no -buttonType method. The set method sets various button properties that together establish the behavior of the type.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    alternateImage
    image
    – setButtonType: (NSButtonCell)

  • Returns by reference the delay and interval periods for a continuous button.

    Declaration

    Swift

    func getPeriodicDelay(_ delay: UnsafeMutablePointer<Float>, interval interval: UnsafeMutablePointer<Float>)

    Objective-C

    - (void)getPeriodicDelay:(float *)delay interval:(float *)interval

    Parameters

    delay

    On return, the amount of time (in seconds) the button will pause before starting to periodically send action messages to the target object. The default delay is taken from a user's default (60 seconds maximum). If the user hasn’t specified a default value, delay defaults to 0.4 seconds,

    interval

    On return, the amount of time (in seconds) the button will pause between sending each action message. The default interval is taken from a user's default (60 seconds maximum). If the user hasn’t specified a default value, interval defaults to 0.075 seconds.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – isContinuous (NSControl)

  • Sets the message delay and interval periods for a continuous button.

    Declaration

    Swift

    func setPeriodicDelay(_ delay: Float, interval interval: Float)

    Objective-C

    - (void)setPeriodicDelay:(float)delay interval:(float)interval

    Parameters

    delay

    The amount of time (in seconds) that a continuous button will pause before starting to periodically send action messages to the target object. The maximum allowed value is 60.0 seconds; if a larger value is supplied, it is ignored, and 60.0 seconds is used.

    interval

    The amount of time (in seconds) the continuous button will pause between sending each action message. The maximum value is 60.0 seconds; if a larger value is supplied, it is ignored, and 60.0 seconds is used.

    Discussion

    The delay and interval values are used if the button is configured (by a setContinuous: message) to continuously send the action message to the target object while tracking the mouse.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – setContinuous: (NSControl)

  • The title that the button displays when the button is in an on state.

    Declaration

    Swift

    var alternateTitle: String

    Objective-C

    @property(copy) NSString *alternateTitle

    Discussion

    This property contains the string that appears on the button when the button is in an on state, or the empty string if the button doesn't display an alternate title. By default, a button’s alternate title is Button.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • The title that the button displays in an off state, as an attributed string.

    Declaration

    Swift

    @NSCopying var attributedTitle: NSAttributedString

    Objective-C

    @property(copy) NSAttributedString *attributedTitle

    Discussion

    This property contains an string of class NSAttributedString, which appears on the button when the button is in an off state. If the button doesn’t display a title, then this property contains an empty attributed string.

    A button’s title is always displayed if the button doesn’t use its alternate contents for highlighting or displaying the on state. By default, a button’s title is Button.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • The title that the button displays as an attributed string when the button is in an on state.

    Declaration

    Swift

    @NSCopying var attributedAlternateTitle: NSAttributedString

    Objective-C

    @property(copy) NSAttributedString *attributedAlternateTitle

    Discussion

    This property contains the string that appears on the button when it's in an on state, as an NSAttributedString, or the empty string if the button doesn't display an alternate title. By default, a button’s alternate title is Button.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • title title Property

    The title displayed on the button when it’s in an off state.

    Declaration

    Swift

    var title: String

    Objective-C

    @property(copy) NSString *title

    Discussion

    This property contains the title displayed on the button when it’s in an off state or the empty string if the button doesn’t display a title. This title is always displayed if the button doesn’t use its alternate contents for highlighting or displaying the on state. By default, a button’s title is Button. Setting the value of this property redraws the button’s contents, if necessary.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets the title of a button with a character denoting an access key.

    Declaration

    Objective-C

    - (void)setTitleWithMnemonic:(NSString *)stringWithAmpersand

    Discussion

    Mnemonics are not supported in OS X.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.8.

  • sound sound Property

    The sound that plays when the user clicks the button.

    Declaration

    Swift

    var sound: NSSound?

    Objective-C

    @property(strong) NSSound *sound

    Discussion

    The sound represented by this property is played during a mouse event, such as NSLeftMouseDown.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • A Boolean value that indicates whether spring loading is enabled for the button.

    Declaration

    Swift

    var springLoaded: Bool

    Objective-C

    @property(getter=isSpringLoaded) BOOL springLoaded

    Discussion

    The value of this property is YEStrue if spring loading is enabled for the button, and NOfalse if it is not. The default is NOfalse.

    On pressure-sensitive systems, such as systems with the Force Touch trackpad, spring loading is a feature that allows a user to activate a button by dragging selected items over it and force clicking—pressing harder—without dropping the selected items. The user can then continue dragging the items, possibly to perform additional actions.

    A practical example of this feature can be found in the Calendar app. A selected calendar event can be dragged over the Calendars button in the toolbar. Force clicking on the button displays the calendar list without releasing the selected event. The event can then be dropped onto a calendar in the list, which assigns it to that calendar.

    If spring loading is enabled on a button and a user drags items over it, the button highlights to indicate that it responds to force clicking. If the user presses harder, additional highlighting occurs to indicate that the button was fully activated.

    On systems that don’t support pressure sensitivity, simply hovering over the button for a short period of time is sufficient to activate the button.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.10.3 and later.

  • An integer value indicating the maximum pressure level for a button of type NSMultiLevelAcceleratorButton.

    Declaration

    Swift

    var maxAcceleratorLevel: Int

    Objective-C

    @property NSInteger maxAcceleratorLevel

    Discussion

    A multilevel accelerator button is a variation of a standard accelerator button that allows for a configurable number of stepped pressure levels in a system that supports pressure-sensitivity, such as the Force Touch trackpad. As each level is reached, the user receives light tactile feedback, and an action is sent.

    You configure the number of pressure levels for a multilevel accelerator button by adjusting the value of maxAcceleratorLevel. For other types of buttons, this property value defaults to 1. For multilevel accelerator buttons, this property value defaults to 2, and may be set to a value between 1 and 5.

    The behavior of a multilevel accelerator button is reliant on a system that supports pressure sensitivity. On a system that doesn’t support pressure sensitivity, a multilevel accelerator button always has a value of 1 when the user clicks it.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.10.3 and later.

  • image image Property

    The image that appears on the button when it’s in an off state, or nil if there is no such image.

    Declaration

    Swift

    var image: NSImage?

    Objective-C

    @property(strong) NSImage *image

    Discussion

    The image contained in this property is always displayed on a button that doesn’t change its contents when highlighting or showing an on state. Buttons don’t display images by default.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • An alternate image that appears on the button when the button is in an on state.

    Declaration

    Swift

    var alternateImage: NSImage?

    Objective-C

    @property(strong) NSImage *alternateImage

    Discussion

    The value of this property is nil if there is no alternate image for the button. Note that some button types don’t display an alternate image, and buttons don’t display images by default. If you use this property to set an image, the button redraws its contents if necessary.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • The position of the button’s image relative to its title.

    Declaration

    Swift

    var imagePosition: NSCellImagePosition

    Objective-C

    @property NSCellImagePosition imagePosition

    Discussion

    If the title is above, below, or overlapping the image, or if there is no image, the text is horizontally centered within the button. See NSCellImagePosition in NSCell Class Reference for the list of possible image positions.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • bordered bordered Property

    A Boolean value that determines whether the button has a border.

    Declaration

    Swift

    var bordered: Bool

    Objective-C

    @property(getter=isBordered) BOOL bordered

    Discussion

    The value of this property is YEStrue if the button has a border, NOfalse otherwise. A button’s border isn’t the single line of most other controls’ borders—instead, it’s a raised bezel. By default, buttons are bordered. If the bordered state of a button changes, it gets redrawn.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.10 and later.

  • A Boolean value that indicates whether the button is transparent.

    Declaration

    Swift

    var transparent: Bool

    Objective-C

    @property(getter=isTransparent) BOOL transparent

    Discussion

    The value of this property is YEStrue if the button is transparent, NOfalse otherwise. A transparent button never draws itself, but it receives mouse events, sends its action, and tracks the mouse properly. A transparent button can be useful for sensitizing an area on the screen so that an action gets sent to a target when the area receives a mouse click. Setting this property causes the button to redraw if necessary.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.10 and later.

  • The appearance of the button’s border.

    Declaration

    Swift

    var bezelStyle: NSBezelStyle

    Objective-C

    @property NSBezelStyle bezelStyle

    Return Value

    The bezel style of the button. See NSBezelStyle in NSButtonCell Class Reference for the list of possible values.

    Note that if the button is not bordered, the bezel style is ignored.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • A Boolean value that determines whether the button displays its border only when the pointer is over it.

    Declaration

    Swift

    var showsBorderOnlyWhileMouseInside: Bool

    Objective-C

    @property BOOL showsBorderOnlyWhileMouseInside

    Discussion

    The value of this property is YEStrue if the button’s border is displayed only when the pointer is over the button and the button is active. The value is NOfalse if the border is displayed all the time, regardless of the position of the pointer. By default, this method returns NOfalse.

    If bordered is NOfalse, the border is never displayed, regardless of the value of showsBorderOnlyWhileMouseInside.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • A Boolean value that indicates whether the button allows a mixed state.

    Declaration

    Swift

    var allowsMixedState: Bool

    Objective-C

    @property BOOL allowsMixedState

    Discussion

    The value of this property is YEStrue if the button has three states (on, off, and mixed), or NOfalse if the button has two states (on and off). The default value is NOfalse. On and off states (also referred to as alternate and normal) indicate that the button is either clicked or not clicked. Mixed state is typically used for checkboxes or radio buttons. For example, suppose the state of a checkbox is used to denote whether a text field contains bold text. If all of the text in the text field is bold, then the checkbox appears checked (on). If none of the text is bold, then the checkbox appears unchecked (off). If some of the text is bold, then the checkbox contains a dash (mixed).

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • state state Property

    The button’s state.

    Declaration

    Swift

    var state: Int

    Objective-C

    @property NSInteger state

    Discussion

    The value of this property represents the button's state. A button can have two or three states. If it has two, this value is either on (NSOnState) or off (NSOffState). If it has three, this value is on, off, or mixed (NSMixedState). A three-state button can be enabled by calling the allowsMixedState method. On and off states (also referred to as alternate and normal) indicate that the button is either clicked or not clicked. Mixed state is typically used for checkboxes or radio buttons, which allow for an additional intermediate state. For example, suppose the state of a checkbox is used to denote whether a text field contains bold text. If all of the text in the text field is bold, then the checkbox appears checked (on). If none of the text is bold, then the checkbox appears unchecked (off). If some of the text is bold, then the checkbox contains a dash (mixed).

    Note that if the button has only two states and you set the value of state to mixed, the button’s state changes to on. Setting this property redraws the button, if necessary.

    Although using the enumerated constants is preferred, you can also set state to an integer value. If the button has two states, 0 is treated as NSOffState, and a nonzero value is treated as NSOnState. If the button has three states, 0 is treated as NSOffState; a negative value, as NSMixedState; and a positive value, as NSOnState.

    To check whether the button uses the mixed state, use the allowsMixedState property.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets the button to its next state.

    Declaration

    Swift

    func setNextState()

    Objective-C

    - (void)setNextState

    Discussion

    If the button has three states, it cycles through them in this order: on, off, mixed, on, and so forth. If the button has two states, it toggles between them.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    allowsMixedState

  • Highlights (or unhighlights) the button.

    Declaration

    Swift

    func highlight(_ flag: Bool)

    Objective-C

    - (void)highlight:(BOOL)flag

    Parameters

    flag

    YEStrue to highlight the button; NOfalse to unhighlight the button. If the current state of the button matches flag, no action is taken.

    Discussion

    Highlighting makes the button appear recessed, displays its alternate title or image, or causes the button to appear illuminated.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • The key-equivalent character of the button.

    Declaration

    Swift

    var keyEquivalent: String

    Objective-C

    @property(copy) NSString *keyEquivalent

    Discussion

    This property contains the button's key equivalent, or the empty string if no equivalent has been defined. Buttons don’t have a default key equivalent.

    If you set a key equivalent instead of an image, the button’s interior is redrawn. However, the key equivalent isn’t displayed if the image position is set to NSNoImage, NSImageOnly, or NSImageOverlaps; that is, the button must display both its title and its “image” (which is the key equivalent in this case), and they must not overlap.

    To display a key equivalent on a button, set the image and alternate image to nil, set the key equivalent, and then set the image position.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • The mask specifying the modifier keys for the button’s key equivalent.

    Declaration

    Swift

    var keyEquivalentModifierMask: Int

    Objective-C

    @property NSUInteger keyEquivalentModifierMask

    Discussion

    This property contains the mask specifying the modifier keys that are applied to the button's key equivalent. Mask bits are defined in Modifier Flags. The only mask bits relevant in button key-equivalent modifier masks are NSControlKeyMask, NSAlternateKeyMask, and NSCommandKeyMask.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    keyEquivalent

  • Checks the button's key equivalent against the specified event and, if they match, simulates the button being clicked.

    Declaration

    Swift

    func performKeyEquivalent(_ anEvent: NSEvent) -> Bool

    Objective-C

    - (BOOL)performKeyEquivalent:(NSEvent *)anEvent

    Parameters

    anEvent

    The event containing the key equivalent.

    Return Value

    YEStrue if the key equivalent in anEvent matches the button's key equivalent; NOfalse if it does not. This method also returns NOfalse if the button is blocked by a modal panel or the button is disabled.

    Discussion

    If the character in anEvent matches the button’s key equivalent, and the modifier flags in anEvent match the key-equivalent modifier mask, performKeyEquivalent: simulates the user clicking the button and returning YEStrue. Otherwise, performKeyEquivalent: does nothing and returns NOfalse.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.