Mac Developer Library

Developer

AppKit Framework Reference NSButton Class Reference

Options
Deployment Target:

On This Page
Language:

NSButton

The NSButton class is a subclass of NSControl that intercepts mouse-down events and sends an action message to a target object when it’s clicked or pressed. More...

Inheritance


Import Statement


import AppKit @import AppKit;

Availability


Available in OS X v10.0 and later.
  • Sets how the receiver button highlights while pressed and how it shows its state.

    Declaration

    Swift

    func setButtonType(_ aType: NSButtonType)

    Objective-C

    - (void)setButtonType:(NSButtonType)aType

    Parameters

    aType

    A constant specifying the type of the button—one of the constants described in the Constants section of NSButtonCell.

    Discussion

    setButtonType: redisplays the button before returning.

    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

    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) between each action message that is sent. 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

    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) between 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

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – setContinuous: (NSControl)

  • The title that the button displays when it’s in its alternate state.

    Declaration

    Swift

    var alternateTitle: String

    Objective-C

    @property(copy) NSString *alternateTitle

    Discussion

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

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • The title that the button displays in its normal state as an attributed string.

    Declaration

    Swift

    @NSCopying var attributedTitle: NSAttributedString

    Objective-C

    @property(copy) NSAttributedString *attributedTitle

    Discussion

    This property contains the string that appears on the receiver when it’s in its normal state as an NSAttributedString, or an empty attributed string if the receiver doesn’t display a title.

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

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • The title that the button displays when it’s in its alternate state as an attributed string.

    Declaration

    Swift

    @NSCopying var attributedAlternateTitle: NSAttributedString

    Objective-C

    @property(copy) NSAttributedString *attributedAlternateTitle

    Discussion

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

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • title title Property

    The title displayed on the button when it’s in its normal state.

    Declaration

    Swift

    var title: String

    Objective-C

    @property(copy) NSString *title

    Discussion

    This property contains the title displayed on the receiver when it’s in its normal 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 alternate state. By default, a button’s title is “Button.” Setting the value of this property redraws the button’s contents, if necessary.

    Import Statement

    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

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.8.

  • sound sound Property

    The sound that’s played when the user presses 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-down event, such as NSLeftMouseDown.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • image image Property

    The image that appears on the receiver when it’s in its normal 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 its alternate state. Buttons don’t display images by default.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • The image that appears on the button when it’s in its alternate 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. Note that some button types don’t display an alternate image. 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

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • The position of the receiver’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. The value of this property is one of the image positions described in the Constants section of NSCell in NSCell Class Reference.

    Import Statement

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

    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 receiver is transparent, NOfalse otherwise. A transparent button never draws itself, but it receives mouse-down 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 receiver to redraw if necessary.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.10 and later.

  • The appearance of the receiver’s border.

    Declaration

    Swift

    var bezelStyle: NSBezelStyle

    Objective-C

    @property NSBezelStyle bezelStyle

    Import Statement

    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 receiver’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

    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 receiver has three states (on, off, and mixed) or NOfalse if the receiver has two states (on and off). The default value is NOfalse.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • state state Property

    The receiver’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 NSOffState (the normal or unpressed state) or NSOnState (the alternate or pressed state). If it has three, this value can be NSOnState (the feature is in effect everywhere), NSOffState (the feature is in effect nowhere), or NSMixedState (the feature is in effect somewhere). Note that if the button has only two states and you set the value of state to NSMixedState, the button’s state becomes NSOnState. 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

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets the receiver 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

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    allowsMixedState

  • Highlights (or unhighlights) the receiver.

    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 may involve the button appearing “pushed in” to the screen, displaying its alternate title or image, or causing the button to appear to be “lit.”

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • The key-equivalent character of the receiver.

    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

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • The mask specifying the modifier keys for the receiver’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 in NSEvent Class Reference. The only mask bits relevant in button key-equivalent modifier masks are NSControlKeyMask, NSAlternateKeyMask, and NSCommandKeyMask.

    Import Statement

    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 he receiver is blocked by a modal panel or the button is disabled.

    Discussion

    If the character in anEvent matches the receiver’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

    import AppKit

    Availability

    Available in OS X v10.0 and later.