Mac Developer Library

Developer

AppKit Framework Reference NSButtonCell Class Reference

Options
Deployment Target:

On This Page
Language:

NSButtonCell

The NSButtonCell class is a subclass of NSActionCell used to implement the user interfaces of push buttons, checkboxes (switches), and radio buttons. It can also be used for any other region of a view that’s designed to send a message to a target when clicked. The NSButton subclass of NSControl uses a single NSButtonCell.

The NSButtonCell class implements the user interface of NSButton.

Setting the integer, float, double, or object value of an NSButtonCell object results in a call to setState: with the value converted to integer. In the case of setObjectValue:, nil is equivalent to 0, and a non-nil object that doesn't respond to intValue sets the state to 1. Otherwise, the state is set to the object's intValue. Similarly, querying the integer, float, double, or object value of an NSButtonCell returns the current state in the requested representation. In the case of objectValue, this is an NSNumber containing YEStrue for on, NOfalse for off, and integer value -1 for the mixed state.

For more information on the behavior of NSButtonCell, see the NSButton and NSMatrix class specifications, and Button Programming Topics.

Exceptions

In its implementation of the compare: method (declared in NSCell), NSButtonCell raises an NSBadComparisonException if the otherCell argument is not of the NSButtonCell class.

Import Statement


Swift

import AppKit

Objective-C

@import AppKit;

Availability


Available in OS X v10.0 and later.
  • Returns the character in the alternate title that’s marked as the “keyboard mnemonic.”

    Declaration

    Objective-C

    - (NSString *)alternateMnemonic

    Return Value

    The character in the alternate title (the title displayed on the receiver when it's in its alternate state) marked as the "keyboard mnemonic."

    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.

  • Returns an unsigned integer indicating the character in the alternate title that’s marked as the “keyboard mnemonic.”

    Declaration

    Objective-C

    - (NSUInteger)alternateMnemonicLocation

    Return Value

    An unsigned integer indicating the character in the alternate title (the title displayed on the receiver when it’s in its alternate state) that’s marked as the “keyboard mnemonic.” If the alternate title doesn’t have a keyboard mnemonic, returns NSNotFound.

    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.

  • Returns the string displayed by the button when it’s in its alternate state.

    Declaration

    Swift

    var alternateTitle: String

    Objective-C

    @property(copy) NSString *alternateTitle

    Return Value

    The string that appears on the button when it's in its alternate state, or the empty string if the receiver doesn’t display an alternate title.

    Discussion

    Note that some button types don’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.

  • Returns the title displayed by the button when it’s in its alternate state, as an attributed string.

    Declaration

    Swift

    @NSCopying var attributedAlternateTitle: NSAttributedString

    Objective-C

    @property(copy) NSAttributedString *attributedAlternateTitle

    Return Value

    The attributed string that appears on the button when it's in its alternate state, or the empty string if the receiver doesn’t display an alternate title.

    Discussion

    Note that some button types don’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.

  • Returns the title displayed by the button when it’s in its normal state as an attributed string.

    Declaration

    Swift

    @NSCopying var attributedTitle: NSAttributedString

    Objective-C

    @property(copy) NSAttributedString *attributedTitle

    Return Value

    The attributes string that appears on the button when it's in its normal state, or an empty attributed string if the receiver doesn’t display a title.

    Discussion

    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

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets the character in the alternate title that should be the “keyboard mnemonic.”

    Declaration

    Objective-C

    - (void)setAlternateMnemonicLocation:(NSUInteger)location

    Parameters

    location

    An unsigned integer indicating the character in the alternate title that should be marked as the "keyboard mnemonic." If you don’t want the alternate title to have a keyboard mnemonic, specify a location of NSNotFound.

    Discussion

    Mnemonics are not supported in OS X.

    The setAlternateMnemonicLocation: method doesn’t cause the button cell to be redisplayed.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.8.

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

    Declaration

    Swift

    var alternateTitle: String

    Objective-C

    @property(copy) NSString *alternateTitle

    Parameters

    aString

    The string to set as the button's title when it's in its alternate state.

    Discussion

    Note that some button types don’t display an alternate title.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets the title the button displays when it’s in its alternate state to the given string with an embedded mnemonic.

    Declaration

    Objective-C

    - (void)setAlternateTitleWithMnemonic:(NSString *)aString

    Parameters

    aString

    The string to set as the button's alternate title, taking into account the fact that an embedded “&” character is not a literal but instead marks the alternate state’s “keyboard mnemonic.”

    Discussion

    Mnemonics are not supported in OS X.

    If necessary, setAlternateTitleWithMnemonic: redraws the button cell. Note that some button types don’t display an alternate title.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.8.

  • Sets the string the button displays when it’s in its alternate state to the given attributed string.

    Declaration

    Swift

    @NSCopying var attributedAlternateTitle: NSAttributedString

    Objective-C

    @property(copy) NSAttributedString *attributedAlternateTitle

    Parameters

    aString

    The attributed string to set as the button's alternate title.

    Discussion

    Note that some button types don’t display an alternate title.

    Graphics attributes that are set on the cell (backgroundColor, alignment, font, etc.) are overridden when corresponding properties are set for the attributed string.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets the string the button displays when it’s in its normal state to the given attributed string and redraws the button.

    Declaration

    Swift

    @NSCopying var attributedTitle: NSAttributedString

    Objective-C

    @property(copy) NSAttributedString *attributedTitle

    Parameters

    aString

    The attributed string to set as the button's title.

    Discussion

    The title is always shown on buttons that don’t use their alternate contents when highlighting or displaying their alternate state.

    Graphics attributes configured for the cell (backgroundColor, alignment, font, etc.) are overridden when corresponding properties are set for the attributed string.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • setFont: - setFont: Available in OS X v10.0 through OS X v10.9

    Sets the font used to display the button's title and alternate title.

    Declaration

    Objective-C

    - (void)setFont:(NSFont *)fontObj

    Parameters

    fontObj

    The font object specifying the font to use.

    Discussion

    This method does nothing if the receiver has no title or alternate title.

    If the button cell has a key equivalent, its font is not changed, but the key equivalent’s font size is changed to match the new title font.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 through OS X v10.9.

  • Sets the title the button displays when in its normal state and, if necessary, redraws the receiver’s contents.

    Declaration

    Swift

    var title: String!

    Objective-C

    @property(copy) NSString *title

    Parameters

    aString

    The string to set as the button's title.

    Discussion

    The title is always shown on buttons that don’t use their alternate contents when highlighting or displaying their alternate state.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets the title the button displays when it’s in its normal state to the given string with an embedded mnemonic.

    Declaration

    Objective-C

    - (void)setTitleWithMnemonic:(NSString *)aString

    Parameters

    aString

    The string to set as the button's title, taking into account the fact that an embedded “&” character is not a literal but instead marks the alternate state’s “keyboard mnemonic.” This title is always shown on buttons that don’t use their alternate contents when highlighting or displaying their alternate state.

    Discussion

    If necessary, setTitleWithMnemonic: redraws the button cell. 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.

  • Returns the title displayed on the receiver when it’s in its normal state.

    Declaration

    Swift

    var title: String!

    Objective-C

    @property(copy) NSString *title

    Return Value

    The title displayed by the button in its normal state, or the empty string if the button doesn’t display a title.

    Discussion

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the image the button displays in its alternate state.

    Declaration

    Swift

    var alternateImage: NSImage?

    Objective-C

    @property(strong) NSImage *alternateImage

    Return Value

    The image displayed by the button when it's in its alternate state, or nil if there is no alternate image.

    Discussion

    Note that some button types don’t display an alternate image. 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.

  • Returns the position of the receiver’s image relative to its title.

    Declaration

    Swift

    var imagePosition: NSCellImagePosition

    Objective-C

    @property NSCellImagePosition imagePosition

    Return Value

    The position of the button's image. This is one of the image positions described in the Constants section of NSCell.

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets the image the button displays in its alternate state and, if necessary, redraws its contents.

    Declaration

    Swift

    var alternateImage: NSImage?

    Objective-C

    @property(strong) NSImage *alternateImage

    Parameters

    image

    The image displayed by the button when it's in its alternate state.

    Discussion

    Note that some button types don’t display an alternate image.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets the position of the receiver’s image relative to its title.

    Declaration

    Swift

    var imagePosition: NSCellImagePosition

    Objective-C

    @property NSCellImagePosition imagePosition

    Parameters

    aPosition

    A constant specifying the position of the button's image. See the Constants section of NSCell for a listing of possible values.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the scale factor for the receiver’s image.

    Declaration

    Swift

    var imageScaling: NSImageScaling

    Objective-C

    @property NSImageScaling imageScaling

    Return Value

    The scale factor for the receiver’s image.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Sets the scale factor for the receiver’s image.

    Declaration

    Swift

    var imageScaling: NSImageScaling

    Objective-C

    @property NSImageScaling imageScaling

    Parameters

    scaling

    The scale factor for the receiver’s image.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • 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) that the button will pause before starting to periodically send action messages to the target object. Default values are taken from the user's defaults (60 seconds maximum); if the user hasn't specified a default value, this defaults to 0.4 seconds.

    interval

    On return, the amount of time (in seconds) between each action message. Default values are taken from the user's defaults (60 seconds maximum); if the user hasn't specified a default value, this 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
    isContinuous (NSCell)

  • Sets the message delay and interval for the receiver.

    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 value is 60.0 seconds; if a larger value is supplied, it’s 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’s ignored, and 60.0 seconds is used.

    Discussion

    These values are used if the receiver 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: (NSCell)

  • Returns the receiver's key-equivalent character.

    Declaration

    Swift

    var keyEquivalent: String

    Objective-C

    @property(copy) NSString *keyEquivalent

    Return Value

    The string containing the key equivalent character of the button, or the empty string if one hasn't been defined.

    Discussion

    Buttons don't have a default key equivalent.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the font used to draw the key equivalent.

    Declaration

    Swift

    var keyEquivalentFont: NSFont?

    Objective-C

    @property(strong) NSFont *keyEquivalentFont

    Return Value

    The font object describing the font used to draw the button's key equivalent, or nil if the receiver doesn’t have a key equivalent.

    Discussion

    The default font is the same as that used to draw the title.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the mask identifying the modifier keys for the button's key equivalent.

    Declaration

    Swift

    var keyEquivalentModifierMask: Int

    Objective-C

    @property NSUInteger keyEquivalentModifierMask

    Return Value

    A mask indicating the modifier keys that are applied to the receiver's key equivalent.

    Mask bits are defined in NSEvent.h. The only mask bits relevant in button key-equivalent modifier masks are NSControlKeyMask, NSAlternateKeyMask, and NSCommandKeyMask bits.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets the key equivalent character of the receiver.

    Declaration

    Swift

    var keyEquivalent: String

    Objective-C

    @property(copy) NSString *keyEquivalent

    Parameters

    aKeyEquivalent

    The key equivalent character.

    Discussion

    This method redraws the receiver’s inside if it displays a key equivalent instead of an image. 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” (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, then set the key equivalent, then set the image position.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets the mask identifying the modifier keys to use with the button's key equivalent.

    Declaration

    Swift

    var keyEquivalentModifierMask: Int

    Objective-C

    @property NSUInteger keyEquivalentModifierMask

    Parameters

    mask

    The mask indicating the modifier keys to be applied to the receiver's key equivalent.

    Mask bits are defined in NSEvent.h. 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.

  • Sets the font used to draw the key equivalent and redisplays the receiver if necessary.

    Declaration

    Swift

    var keyEquivalentFont: NSFont?

    Objective-C

    @property(strong) NSFont *keyEquivalentFont

    Parameters

    fontObj

    The font object specifying the font to use for the receiver's key equivalent.

    Discussion

    This method does nothing if the receiver doesn’t have a key equivalent associated with it.

    The default font is the same as that used to draw the title.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets by name and size of the font used to draw the key equivalent.

    Declaration

    Swift

    func setKeyEquivalentFont(_ fontName: String, size fontSize: CGFloat)

    Objective-C

    - (void)setKeyEquivalentFont:(NSString *)fontName size:(CGFloat)fontSize

    Parameters

    fontName

    The name of the font to use to draw the key equivalent.

    fontSize

    The font size to use to draw the key equivalent.

    Discussion

    This method redisplays the receiver if necessary. It does nothing if the receiver doesn’t have a key equivalent associated with it. The default font is the same as that used to draw the title.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the background color of the receiver.

    Declaration

    Swift

    @NSCopying var backgroundColor: NSColor?

    Objective-C

    @property(copy) NSColor *backgroundColor

    Return Value

    The receiver’s background color.

    Discussion

    The background color is used only when drawing borderless buttons.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Sets the background color of the receiver.

    Declaration

    Swift

    @NSCopying var backgroundColor: NSColor?

    Objective-C

    @property(copy) NSColor *backgroundColor

    Parameters

    color

    The color to use for the receiver’s background.

    Discussion

    The background color is used only when drawing borderless buttons.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Returns the appearance of the receiver’s border.

    Declaration

    Swift

    var bezelStyle: NSBezelStyle

    Objective-C

    @property NSBezelStyle bezelStyle

    Return Value

    A constant specifying the bezel style used by the button. See NSBezelStyle for a list of possible values.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets the appearance of the border, if the receiver has one.

    Declaration

    Swift

    var bezelStyle: NSBezelStyle

    Objective-C

    @property NSBezelStyle bezelStyle

    Parameters

    bezelStyle

    A constant specifying the bezel style to use for the button. This must be one of the values specified in NSBezelStyle.

    If the receiver is not bordered, the bezel style is ignored.

    Discussion

    A button uses shading to look like it’s sticking out or pushed in. You can set the shading with setGradientType:.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – bezelStyle

  • Returns the gradient of the receiver’s border.

    Declaration

    Swift

    var gradientType: NSGradientType

    Objective-C

    @property NSGradientType gradientType

    Return Value

    A constant specifying the gradient used for the button's border. See NSGradientType for a list of possible values.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets the type of gradient to use for the receiver.

    Declaration

    Swift

    var gradientType: NSGradientType

    Objective-C

    @property NSGradientType gradientType

    Parameters

    gradientType

    A constant specifying the gradient to use for the button's border. This can be one of the constants defined in NSGradientType.

    Discussion

    If the receiver has no border, this method has no effect on its appearance. A concave gradient is darkest in the top-left corner; a convex gradient is darkest in the bottom-right corner. Weak versus strong is how much contrast exists between the colors used in opposite corners.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns a Boolean value that indicates whether the receiver’s image and text appear “dim” when the receiver is disabled.

    Declaration

    Swift

    var imageDimsWhenDisabled: Bool

    Objective-C

    @property BOOL imageDimsWhenDisabled

    Return Value

    YEStrue if the button's image and text are dimmed when the button is disabled, otherwise NOfalse.

    Discussion

    By default, all button types except NSSwitchButton and NSRadioButton do dim when disabled. When buttons of type NSSwitchButton and NSRadioButton are disabled, only the associated text dims.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets whether the receiver’s image appears “dim” when the button cell is disabled.

    Declaration

    Swift

    var imageDimsWhenDisabled: Bool

    Objective-C

    @property BOOL imageDimsWhenDisabled

    Parameters

    flag

    YEStrue to indicate that the button's image should dim when the button is disabled.

    Discussion

    By default, all button types except NSSwitchButton and NSRadioButton do dim when disabled. When NSSwitchButtons and NSRadioButtons are disabled, only the associated text dims. The default setting for this condition is reasserted whenever you invoke setButtonType:, so be sure to specify the button cell’s type before you invoke setImageDimsWhenDisabled:.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • isOpaque - isOpaque Available in OS X v10.0 through OS X v10.9

    Returns a Boolean value that indicates whether the receiver is opaque.

    Declaration

    Objective-C

    - (BOOL)isOpaque

    Return Value

    YEStrue if the receiver draws over every pixel in its frame, otherwise NOfalse.

    Discussion

    A button cell is opaque only if it isn’t transparent and if it has a border.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 through OS X v10.9.

  • isTransparent - isTransparent Available in OS X v10.0 through OS X v10.9

    Returns a Boolean value that indicates whether the receiver is transparent.

    Declaration

    Objective-C

    - (BOOL)isTransparent

    Return Value

    YEStrue if the receiver is transparent, NOfalse otherwise.

    Discussion

    A transparent button never draws itself, but it receives mouse-down events and tracks the mouse properly.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 through OS X v10.9.

  • Sets whether the receiver is transparent.

    Declaration

    Swift

    var transparent: Bool

    Objective-C

    @property(getter=isTransparent) BOOL transparent

    Parameters

    flag

    YEStrue to make the button cell transparent.

    Discussion

    This method redraws the receiver if necessary. A transparent button tracks the mouse and sends its action, but doesn’t draw. A transparent button is useful for sensitizing an area on the screen so that an action gets sent to a target when the area receives a mouse click.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns a Boolean value indicating whether the button displays its border only when the cursor is over it.

    Declaration

    Swift

    var showsBorderOnlyWhileMouseInside: Bool

    Objective-C

    @property BOOL showsBorderOnlyWhileMouseInside

    Return Value

    YEStrue if the receiver’s border is displayed only when the cursor is over the button and the button is active.

    Discussion

    By default, this method returns NOfalse.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets whether the receiver’s border is displayed only when the cursor is over the button.

    Declaration

    Swift

    var showsBorderOnlyWhileMouseInside: Bool

    Objective-C

    @property BOOL showsBorderOnlyWhileMouseInside

    Parameters

    show

    YEStrue to display the button's border only when the cursor is within the receiver’s border and the button is active. NOfalse to continue to display the border when the cursor is outside button’s bounds.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns flags indicating how the button highlights when it receives a mouse-down event.

    Declaration

    Swift

    var highlightsBy: NSCellStyleMask

    Objective-C

    @property NSCellStyleMask highlightsBy

    Return Value

    The logical OR of flags that indicate the way the receiver highlights when it receivers a mouse-down event. See the Constants section of NSCell for the list of flags.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets the way the receiver highlights itself while pressed.

    Declaration

    Swift

    var highlightsBy: NSCellStyleMask

    Objective-C

    @property NSCellStyleMask highlightsBy

    Parameters

    aType

    The logical OR of one or more of the cell masks described in the Constants section of NSCell.

    Discussion

    If both NSChangeGrayCellMask and NSChangeBackgroundCellMask are specified, both are recorded, but which behavior is used depends on the button cell’s image. If the button has no image, or if the image has no alpha (transparency) data, NSChangeGrayCellMask is used. If the image does have alpha data, NSChangeBackgroundCellMask is used; this arrangement allows the color swap of the background to show through the image’s transparent pixels.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets the way the receiver indicates its alternate state.

    Declaration

    Swift

    var showsStateBy: NSCellStyleMask

    Objective-C

    @property NSCellStyleMask showsStateBy

    Parameters

    aType

    The logical OR of one or more of the cell masks described in the Constants section of NSCell.

    Discussion

    If both NSChangeGrayCellMask and NSChangeBackgroundCellMask are specified, both are recorded, but the actual behavior depends on the button cell’s image. If the button has no image, or if the image has no alpha (transparency) data, NSChangeGrayCellMask is used. If the image exists and has alpha data, NSChangeBackgroundCellMask is used; this arrangement allows the color swap of the background to show through the image’s transparent pixels.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets how the receiver 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 button. This can be one of the constants defined in NSButtonType.

    Discussion

    The setButtonType: method redisplays the receiver 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 setHighlightsBy: and setShowsStateBy: methods.

    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.

  • Returns the flags indicating how the button cell shows its alternate state.

    Declaration

    Swift

    var showsStateBy: NSCellStyleMask

    Objective-C

    @property NSCellStyleMask showsStateBy

    Return Value

    The logical OR of flags that indicate the way the receiver shows its alternate state. See the Constants section of NSCell for the list of flags.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the sound that’s played when the user presses the receiver.

    Declaration

    Swift

    var sound: NSSound?

    Objective-C

    @property(strong) NSSound *sound

    Return Value

    The sound played when the receiver is pressed.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – setSound:

  • Sets the sound that’s played when the user presses the receiver.

    Declaration

    Swift

    var sound: NSSound?

    Objective-C

    @property(strong) NSSound *sound

    Parameters

    aSound

    The sound to play when the button is pressed.

    Discussion

    The sound is played during a mouse-down event, such as NSLeftMouseDown.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – sound

  • Draws the receiver’s border.

    Declaration

    Swift

    func mouseEntered(_ event: NSEvent)

    Objective-C

    - (void)mouseEntered:(NSEvent *)event

    Parameters

    event

    The event object generated by the mouse movement.

    Discussion

    This method is called only when the cursor moves onto the receiver and showsBorderOnlyWhileMouseInside returns YEStrue.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Erases the receiver’s border.

    Declaration

    Swift

    func mouseExited(_ event: NSEvent)

    Objective-C

    - (void)mouseExited:(NSEvent *)event

    Parameters

    event

    The event object generated by the mouse movement.

    Discussion

    This method is called only when the cursor moves off the receiver and showsBorderOnlyWhileMouseInside returns YEStrue.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Simulates the user clicking the receiver with the cursor.

    Declaration

    Swift

    func performClick(_ sender: AnyObject?)

    Objective-C

    - (void)performClick:(id)sender

    Parameters

    sender

    The sender of the message.

    Discussion

    This method essentially highlights the button, sends the button’s action message to the target object, and then unhighlights the button.

    If an exception is raised while the target object is processing the action message, the button is unhighlighted before the exception is propagated out of performClick:.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Draws the border of the button using the current bezel style.

    Declaration

    Swift

    func drawBezelWithFrame(_ frame: NSRect, inView controlView: NSView)

    Objective-C

    - (void)drawBezelWithFrame:(NSRect)frame inView:(NSView *)controlView

    Parameters

    frame

    The bounding rectangle of the button.

    controlView

    The control being drawn.

    Discussion

    This method is called automatically when the button is redrawn; you should not call it directly.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Draws the image associated with the button’s current state.

    Declaration

    Swift

    func drawImage(_ image: NSImage, withFrame frame: NSRect, inView controlView: NSView)

    Objective-C

    - (void)drawImage:(NSImage *)image withFrame:(NSRect)frame inView:(NSView *)controlView

    Parameters

    image

    The image associated with the button's current state.

    frame

    The bounding rectangle of the button.

    controlView

    The control being drawn.

    Discussion

    This method is called automatically when the button is redrawn; you should not call it directly.

    You specify the primary and alternate images for the button using Interface Builder.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Draws the button’s title centered vertically in a specified rectangle.

    Declaration

    Swift

    func drawTitle(_ title: NSAttributedString, withFrame frame: NSRect, inView controlView: NSView) -> NSRect

    Objective-C

    - (NSRect)drawTitle:(NSAttributedString *)title withFrame:(NSRect)frame inView:(NSView *)controlView

    Parameters

    title

    The title of the button.

    frame

    The rectangle in which to draw the title.

    controlView

    The control being drawn.

    Return Value

    The bounding rectangle for the text of the title.

    Discussion

    This method is called automatically when the button is redrawn; you should not call it directly.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Define the bezel styles used by bezelStyle and setBezelStyle:.

    Declaration

    Swift

    enum NSBezelStyle : UInt { case RoundedBezelStyle case RegularSquareBezelStyle case ThickSquareBezelStyle case ThickerSquareBezelStyle case DisclosureBezelStyle case ShadowlessSquareBezelStyle case CircularBezelStyle case TexturedSquareBezelStyle case HelpButtonBezelStyle case SmallSquareBezelStyle case TexturedRoundedBezelStyle case RoundRectBezelStyle case RecessedBezelStyle case RoundedDisclosureBezelStyle case InlineBezelStyle }

    Objective-C

    enum { NSRoundedBezelStyle = 1, NSRegularSquareBezelStyle = 2, NSThickSquareBezelStyle = 3, NSThickerSquareBezelStyle = 4, NSDisclosureBezelStyle = 5, NSShadowlessSquareBezelStyle = 6, NSCircularBezelStyle = 7, NSTexturedSquareBezelStyle = 8, NSHelpButtonBezelStyle = 9, NSSmallSquareBezelStyle = 10, NSTexturedRoundedBezelStyle = 11, NSRoundRectBezelStyle = 12, NSRecessedBezelStyle = 13, NSRoundedDisclosureBezelStyle = 14, NSInlineBezelStyle = 15, NSSmallIconButtonBezelStyle = 2 } typedef NSUInteger NSBezelStyle;

    Constants

    • RoundedBezelStyle

      NSRoundedBezelStyle

      A rounded rectangle button, designed for text.

      Available in OS X v10.0 and later.

    • RegularSquareBezelStyle

      NSRegularSquareBezelStyle

      A rectangular button with a 2 point border, designed for icons.

      Available in OS X v10.0 and later.

    • ThickSquareBezelStyle

      NSThickSquareBezelStyle

      A rectangular button with a 3 point border, designed for icons.

      Available in OS X v10.0 and later.

    • ThickerSquareBezelStyle

      NSThickerSquareBezelStyle

      A rectangular button with a 4 point border, designed for icons.

      Available in OS X v10.0 and later.

    • DisclosureBezelStyle

      NSDisclosureBezelStyle

      A bezel style for use with a disclosure triangle.

      To create the disclosure triangle, set the button bezel style to NSDisclosureBezelStyle and the button type to NSOnOffButton.

      Available in OS X v10.3 and later.

    • ShadowlessSquareBezelStyle

      NSShadowlessSquareBezelStyle

      Similar to NSRegularSquareBezelStyle, but has no shadow so you can abut the cells without overlapping shadows.

      This style would be used in a tool palette, for example.

      Available in OS X v10.0 and later.

    • CircularBezelStyle

      NSCircularBezelStyle

      A round button with room for a small icon or a single character.

      This style has both regular and small variants, but the large variant is available only in gray at this time.

      Available in OS X v10.0 and later.

    • TexturedSquareBezelStyle

      NSTexturedSquareBezelStyle

      A bezel style appropriate for use with textured (metal) windows.

      Available in OS X v10.3 and later.

    • HelpButtonBezelStyle

      NSHelpButtonBezelStyle

      A round button with a question mark providing the standard help button look.

      Available in OS X v10.3 and later.

    • SmallSquareBezelStyle

      NSSmallSquareBezelStyle

      A simple square bezel style. Buttons using this style can be scaled to any size.

      Available in OS X v10.4 and later.

    • TexturedRoundedBezelStyle

      NSTexturedRoundedBezelStyle

      A textured (metal) bezel style similar in appearance to the Finder’s action (gear) button.

      The height of this button is fixed.

      Available in OS X v10.4 and later.

    • RoundRectBezelStyle

      NSRoundRectBezelStyle

      A bezel style that matches the search buttons in Finder and Mail.

      Available in OS X v10.4 and later.

    • RecessedBezelStyle

      NSRecessedBezelStyle

      A bezel style that matches the recessed buttons in Mail, Finder and Safari.

      Available in OS X v10.4 and later.

    • InlineBezelStyle

      NSInlineBezelStyle

      The inline bezel style contains a solid round-rect border background. It can be used to create an "unread" indicator in an outline view, or another inline button in a tableview, such as a stop progress button in a download panel. Use text for an unread indicator, and a template image for other buttons.

      Available in OS X v10.7 and later.

    • NSSmallIconButtonBezelStyle

      NSSmallIconButtonBezelStyle

      This bezel style is obsolete and should not be used.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.0.

    Discussion

    For examples of how these styles are displayed, see Button Programming Topics.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Represent the button types that can be specified using setButtonType:.

    Declaration

    Swift

    enum NSButtonType : UInt { case MomentaryLightButton case PushOnPushOffButton case ToggleButton case SwitchButton case RadioButton case MomentaryChangeButton case OnOffButton case MomentaryPushInButton }

    Objective-C

    enum { NSMomentaryLightButton = 0, NSPushOnPushOffButton = 1, NSToggleButton = 2, NSSwitchButton = 3, NSRadioButton = 4, NSMomentaryChangeButton = 5, NSOnOffButton = 6, NSMomentaryPushInButton = 7, NSMomentaryPushButton = 0, NSMomentaryLight = 7 }; typedef NSUInteger NSButtonType;

    Constants

    • MomentaryLightButton

      NSMomentaryLightButton

      While the button is held down it’s shown as “lit,” and also “pushed in” to the screen if the button is bordered.

      This type of button is best for simply triggering actions, as it doesn’t show its state; it always displays its normal image or title. This option is called “Momentary Light” in Interface Builder’s Button Inspector.

      Available in OS X v10.0 and later.

    • PushOnPushOffButton

      NSPushOnPushOffButton

      The first click both highlights and causes the button to be “pushed in” if the button is bordered; a second click returns it to its normal state.

      This option is called “Push On Push Off” in Interface Builder’s Button Inspector.

      Available in OS X v10.0 and later.

    • ToggleButton

      NSToggleButton

      After the first click, the button displays its alternate image or title; a second click returns the button to its normal state.

      This option is called “Toggle” in Interface Builder’s Button Inspector.

      Available in OS X v10.0 and later.

    • SwitchButton

      NSSwitchButton

      This style is a variant of NSToggleButton that has no border and is used to represent a checkbox.

      This type of button is available as a separate Library item in Interface Builder.

      Available in OS X v10.0 and later.

    • RadioButton

      NSRadioButton

      This style is similar to NSSwitchButton, but it used to constrain a selection to a single element from several.

      You typically use this type of button in a group formed by an instance of NSMatrix. In Interface Builder, a matrix of this type of button is available as a separate Library item.

      Available in OS X v10.0 and later.

    • MomentaryChangeButton

      NSMomentaryChangeButton

      While the button is held down, the alternate image and alternate title are displayed.

      The normal image and title are displayed when the button isn’t pressed. This option is called “Momentary Change” in Interface Builder’s Button Inspector.

      Available in OS X v10.0 and later.

    • OnOffButton

      NSOnOffButton

      The first click highlights the button; a second click returns it to the normal (unhighlighted) state.

      This option is called “On Off” in Interface Builder’s Button Inspector.

      Available in OS X v10.0 and later.

    • MomentaryPushInButton

      NSMomentaryPushInButton

      While the button is held down it’s shown as “lit.”

      This type of button is best for simply triggering actions, as it doesn’t show its state; it always displays its normal image or title. This option is called “Momentary Push In” in Interface Builder’s Button Inspector.

      This button type is the default.

      Available in OS X v10.0 and later.

    • NSMomentaryPushButton

      NSMomentaryPushButton

      While the button is held down it’s shown as “lit,” and also “pushed in” to the screen if the button is bordered.

      Use NSMomentaryLight instead.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.9.

    • NSMomentaryLight

      NSMomentaryLight

      While the button is held down it’s shown as “lit.”

      Use NSMomentaryPushInButton instead.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.9.

    Discussion

    For examples of how these types behave, see Button Programming Topics.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Specify the gradients used by gradientType and setGradientType:.

    Declaration

    Swift

    enum NSGradientType : UInt { case None case ConcaveWeak case ConcaveStrong case ConvexWeak case ConvexStrong }

    Objective-C

    enum { NSGradientNone = 0, NSGradientConcaveWeak = 1, NSGradientConcaveStrong = 2, NSGradientConvexWeak = 3, NSGradientConvexStrong = 4 }; typedef NSUInteger NSGradientType;

    Constants

    • None

      NSGradientNone

      There is no gradient, so the button looks flat.

      Available in OS X v10.0 and later.

    • ConcaveWeak

      NSGradientConcaveWeak

      The top-left corner is light gray, and the bottom-right corner is dark gray, so the button appears to be pushed in.

      Available in OS X v10.0 and later.

    • ConcaveStrong

      NSGradientConcaveStrong

      As with NSGradientConcaveWeak, the top-left corner is light gray, and the bottom-right corner is dark gray, but the difference between the grays is greater, so the appearance of being pushed in is stronger.

      Available in OS X v10.0 and later.

    • ConvexWeak

      NSGradientConvexWeak

      The top-left corner is dark gray, and the bottom-right corner is light gray, so the button appears to be sticking out.

      Available in OS X v10.0 and later.

    • ConvexStrong

      NSGradientConvexStrong

      As with NSGradientConvexWeak, the top-left corner is dark gray, and the bottom-right corner is light gray, but the difference between the grays is greater, so the appearance of sticking out is stronger.

      Available in OS X v10.0 and later.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.