Class

NSButton

A control that defines an area on the screen that can be used to trigger actions.

Overview

Buttons are a standard control used to initiate actions within your app. You can configure buttons with many different visual styles, but the behavior is the same. When clicked, a button calls the action method of its associated target object. (If you configure a button as continuous, it calls its action method at timed intervals until the user releases the mouse button or the cursor leaves the button boundaries.) You use the action method to perform your app-specific tasks.

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.

Topics

Configuring the Cell

class NSButtonCell

An object that defines the user interface of a button or other clickable region of a view.

Configuring Buttons

func setButtonType(NSButton.ButtonType)

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

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

The appearance of the button’s border.

var bezelColor: NSColor?

The color of the button's bezel, in appearances that support it.

var showsBorderOnlyWhileMouseInside: Bool

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

var imageHugsTitle: Bool

A Boolean value that determines how the button’s image and title are positioned together within the button bezel.

var imageScaling: NSImageScaling

The scaling mode applied to make the cell’s image fit the frame of the image view.

Managing Button State

var allowsMixedState: Bool

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

var state: NSControl.StateValue

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

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.

See Also

Controls

class NSColorWell

A control that displays a color value and lets the user change that color value.

Date Picker

Display a calendar date and provide controls for editing the date value.

class NSImageView

A display of image data from an NSImage object in a frame.

class NSLevelIndicator

A visual representation of a level or quantity, using discrete values.

Path Control

A display of a file system path or virtual path information.

class NSPopUpButton

A display of a single item from a list of items, and provide an interface for selecting items from the list.

class NSProgressIndicator

An interface that provides visual feedback to the user about the status of an ongoing task.

class NSRuleEditor

An interface for configuring a rule-based list of options.

class NSPredicateEditor

A defined set of rules that allows the editing of predicate objects.

Search Field

Provide a text field that is optimized for text-based search interfaces.

class NSSegmentedControl

Display one or more buttons in a single horizontal group.

Slider

Display a range of values from which the user selects a single value.

class NSStepper

An interface with up and down arrow buttons for incrementing or decrementing a value.

Text Field

Provide a simple interface for displaying and editing text, including support for password fields and secure forms of text entry.

Token Field

Provide a text field whose text can be rendered in a visually distinct way so that users can recognize portions more easily.

Toolbar

Provide a space for controls under a window's title bar and above your custom content.

Combo Box

Display a list of values in a pop-up menu that lets the user select a value or type in a custom value.

class NSMatrix

A legacy interface for grouping radio buttons or other types of cells together.