Class

NSButton

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.

Overview

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.

Symbols

Configuring Buttons

func setButtonType(NSButtonType)

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

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

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

func setPeriodicDelay(Float, interval: Float)

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

var alternateTitle: String

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

var attributedTitle: NSAttributedString

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

var attributedAlternateTitle: NSAttributedString

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

var title: String

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

var sound: NSSound?

The sound that plays when the user clicks the button.

var isSpringLoaded: Bool

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

var maxAcceleratorLevel: Int

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

Configuring Button Images

var image: NSImage?

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

var alternateImage: NSImage?

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

var imagePosition: NSCellImagePosition

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

var isBordered: Bool

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

var isTransparent: Bool

A Boolean value that indicates whether the button is transparent.

var bezelStyle: NSBezelStyle

The appearance of the button’s border.

var showsBorderOnlyWhileMouseInside: Bool

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

Managing Button State

var allowsMixedState: Bool

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

var state: Int

The button’s state.

func setNextState()

Sets the button to its next state.

func highlight(Bool)

Highlights (or unhighlights) the button.

Accessing Key Equivalents

var keyEquivalent: String

The key-equivalent character of the button.

var keyEquivalentModifierMask: NSEventModifierFlags

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

Handling Keyboard Events

func performKeyEquivalent(with: NSEvent)

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