Mac Developer Library

Developer

AppKit Framework Reference NSButtonCell Class Reference

Options
Deployment Target:

On This Page
Language:

NSButtonCell

Conforms To


Import Statement


Swift

import AppKit

Objective-C

@import AppKit;

Availability


Available in OS X v10.0 and later.

The NSButtonCell class is a subclass of NSActionCell. An NSButtonCell object defines the user interface of a button, checkbox (switch), radio button, and any other clickable region of a view. For example, the NSButton subclass of NSControl uses a single NSButtonCell object to implement its user interface. The configuration of the NSButtonCell object controls how the NSButton object appears and behaves, but the NSButton object is what sends a message when clicked.

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, for most button types, 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 accelerator buttons (type NSAcceleratorButton or NSMultiLevelAcceleratorButton) on systems that support pressure sensitivity, querying doubleValue returns the amount of pressure applied while pressing the button.

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.

  • 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 button 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 button 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.

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

    Declaration

    Swift

    var alternateTitle: String

    Objective-C

    @property(copy) NSString *alternateTitle

    Discussion

    The value of this property is the string that appears on the button when it's in its alternate state, or the empty string if the button doesn’t display an alternate title. 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.

  • 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

    Discussion

    The value of this property is the attributed string that appears on the button when it's in its alternate state, or the empty string if the button doesn’t display an alternate title. Note that some button types don’t display an alternate title. By default, a button’s alternate title is “Button.”

    Graphics attributes that are set on the cell (such as backgroundColor, alignment, font, and so on) 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.

  • 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

    Discussion

    The value of this property is the attributes string that appears on the button when it's in its normal state, or an empty attributed string if the button 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.” Setting this property redraws the button if necessary.

    Graphics attributes configured for the cell (such as backgroundColor, alignment, font, and so on) 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 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 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.

  • 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 button 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 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.

  • 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

    If the button doesn’t display a title, the value of this property is the empty string. 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 this property may redraw the button if necessary.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • The image the button displays in its alternate state.

    Declaration

    Swift

    var alternateImage: NSImage?

    Objective-C

    @property(strong) NSImage *alternateImage

    Discussion

    The value of this property is the image displayed by the button when it's in its alternate state, or 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. Setting this property may redraw the contents of the button.

    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

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

  • The scale factor for the button’s image.

    Declaration

    Swift

    var imageScaling: NSImageScaling

    Objective-C

    @property NSImageScaling imageScaling

    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 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 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 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: (NSCell)

  • The button’s key-equivalent character.

    Declaration

    Swift

    var keyEquivalent: String

    Objective-C

    @property(copy) NSString *keyEquivalent

    Discussion

    The value of this property is the string that contains the key equivalent character of the button, or the empty string if one hasn't been defined. Buttons don't have a default key equivalent.

    Setting this property redraws the button’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.

  • The font used to draw the button’s key equivalent.

    Declaration

    Swift

    var keyEquivalentFont: NSFont?

    Objective-C

    @property(strong) NSFont *keyEquivalentFont

    Discussion

    The value of this property is the font object that describes the font used to draw the button's key equivalent. If the property value is nil, the button doesn’t have a key equivalent. Setting this property redraws the button if necessary. Setting this property on a button that has no key equivalent does nothing.

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • The mask that identifies the modifier keys for the button's key equivalent.

    Declaration

    Swift

    var keyEquivalentModifierMask: Int

    Objective-C

    @property NSUInteger keyEquivalentModifierMask

    Discussion

    The value of this property is a mask that indicates the modifier keys that are applied to the button’s key equivalent. Mask bits are defined in NSEvent.h. The only mask bits that are 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.

    See Also

    keyEquivalent

  • 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 button if necessary. It does nothing if the button 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.

  • The background color of the button.

    Declaration

    Swift

    @NSCopying var backgroundColor: NSColor?

    Objective-C

    @property(copy) NSColor *backgroundColor

    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.

  • The appearance of the button’s border, if it has one.

    Declaration

    Swift

    var bezelStyle: NSBezelStyle

    Objective-C

    @property NSBezelStyle bezelStyle

    Discussion

    The value of this property is a constant that specifies the bezel style used by the button. See NSBezelStyle for a list of possible values. If a button is borderless, the value of this property is ignored.

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • The gradient of the button’s border.

    Declaration

    Swift

    var gradientType: NSGradientType

    Objective-C

    @property NSGradientType gradientType

    Discussion

    The value of this property is a constant that specifies the gradient used for the button's border. See NSGradientType for a list of possible values.

    If the button has no border, setting this property has no effect on the button’s 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.

  • A Boolean value that indicates if the button’s image and text appear “dim” when the button is disabled.

    Declaration

    Swift

    var imageDimsWhenDisabled: Bool

    Objective-C

    @property BOOL imageDimsWhenDisabled

    Discussion

    When the value of this property is YEStrue, the button's image and text are dimmed when the button is disabled; when it is NOfalse, the image and text are not dimmed in the disabled state. By default, all button types except NSSwitchButton and NSRadioButton dim when disabled. When buttons of type NSSwitchButton and NSRadioButton are disabled, only the associated text dims.

    The default setting for this state is reasserted whenever you invoke setButtonType:, so be sure to specify the button cell’s type before you set imageDimsWhenDisabled.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • opaque opaque Property

    A Boolean value that indicates if the button is opaque. (read-only)

    Declaration

    Swift

    var opaque: Bool { get }

    Objective-C

    @property(getter=isOpaque, readonly) BOOL opaque

    Discussion

    When the value of this property is YEStrue, the button draws over every pixel in its frame. Note that a button cell is opaque only if it isn’t transparent and if it has a border. The default value of this property is YEStrue.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.10 and later.

    See Also

    transparent

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

    Declaration

    Swift

    var transparent: Bool

    Objective-C

    @property(getter=isTransparent) BOOL transparent

    Discussion

    When the value of this property is YEStrue, the button is transparent, when it is NOfalse, the button is not transparent. The default value is NOfalse.

    Setting this property redraws the button 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.10 and later.

    See Also

    opaque

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

    Declaration

    Swift

    var showsBorderOnlyWhileMouseInside: Bool

    Objective-C

    @property BOOL showsBorderOnlyWhileMouseInside

    Discussion

    When 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. When it is NOfalse, the border continues to display when the pointer is outside of the button’s bounds.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • A set of flags that indicate how the button highlights when it receives a mouse-down event (that is, when the button is pressed).

    Declaration

    Swift

    var highlightsBy: NSCellStyleMask

    Objective-C

    @property NSCellStyleMask highlightsBy

    Discussion

    The value of this property is the logical OR of one or more of flags described in the "Constants” section of NSCell Class Reference.

    If both NSChangeGrayCellMask and NSChangeBackgroundCellMask are specified, both are recorded, but the resulting 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 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.

    See Also

    showsStateBy

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

    Discussion

    The setButtonType: method 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 highlightsBy and showsStateBy properties.

    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
    – setImage: (NSCell)

  • The flags that indicate how the button cell shows its alternate state.

    Declaration

    Swift

    var showsStateBy: NSCellStyleMask

    Objective-C

    @property NSCellStyleMask showsStateBy

    Discussion

    The value of this property is the logical OR of one or more of the cell masks described in the "Constants” section of NSCell Class Reference.

    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.

    See Also

    highlightsBy

  • sound sound Property

    The sound that’s played when the user presses the button (that is during a mouse-down event).

    Declaration

    Swift

    var sound: NSSound?

    Objective-C

    @property(strong) NSSound *sound

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Draws the button’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 pointer moves onto the button and the value of showsBorderOnlyWhileMouseInside is YEStrue.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Erases the button’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 pointer moves off the button and the value of showsBorderOnlyWhileMouseInside is YEStrue.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Simulates the user clicking the button with the pointer.

    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.

    See Also

    bezelStyle

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

    See Also

    alternateImage

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

  • Bezel styles used by the bezelStyle property.

    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 two-point border, designed for icons.

      Available in OS X v10.0 and later.

    • ThickSquareBezelStyle

      NSThickSquareBezelStyle

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

      Available in OS X v10.0 and later.

    • ThickerSquareBezelStyle

      NSThickerSquareBezelStyle

      A rectangular button with a four-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.

  • 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 case AcceleratorButton case MultiLevelAcceleratorButton }

    Objective-C

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

    Constants

    • MomentaryLightButton

      NSMomentaryLightButton

      When the button is clicked (on state), it appears illuminated. If the button has borders, it may also appear recessed. When the button is released, it returns to its normal (off) state.

      This type of button is best for simply triggering actions because 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

      When the button is clicked (on state), it appears illuminated. If the button has borders, it may also appear recessed. A second click returns it to its normal (off) 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 (on state); a second click returns the button to its normal (off) 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 typically used to represent a checkbox.

      A checkbox button type is available as an Object Library item in Interface Builder.

      Available in OS X v10.0 and later.

    • RadioButton

      NSRadioButton

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

      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

      When the button is clicked, the alternate (on state) image and alternate title are displayed.

      Otherwise, the normal (off state) image and title are displayed. 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.

    • AcceleratorButton

      NSAcceleratorButton

      On pressure-sensitive systems, such as systems with the Force Touch trackpad, an accelerator button sends repeating actions as pressure changes occur. It stops sending actions when the user releases pressure entirely. A media player app, for example, might implement an accelerator button in order to allow a user to adjust the speed of fast forward or rewind with variable pressure. In this case, actions are sent to the app to indicate when pressure on the button has changed. The app would then determine the amount of pressure currently applied, and adjust playback speed accordingly.

      An accelerator button sends an action when the user first clicks the button and continues sending actions until pressure on the button is released entirely.

      For continuous accelerator buttons (see setContinuous:), the interval between repeating actions (a rate typically specified with setPeriodicDelay:interval:) automatically adjusts to match the applied pressure. As the user force clicks (presses harder), actions are sent more rapidly. As the user reduces pressure on the button, actions slow down. As such, the user has direct control over how fast actions are sent. Continuous accelerator buttons are intended for continuously advancing through a series of discrete objects, such as photos in an album or pages in a book.

      For noncontinuous accelerator buttons, actions are sent whenever a change in force occurs. Noncontinuous accelerator buttons are intended for adjusting the speed of navigation, such as playback speed in a media player, based on pressure. Once the button is released, a final action is sent.

      For buttons that are not accelerator buttons, the value of the button matches its state. For accelerator buttons, the value of the button is distinct from its state, and indicates pressure level. While the user force clicks the button, doubleValue is a measurement of pressure between 1.0 and approaching 2.0. When released, doubleValue is 0.0.

      An accelerator button appears like any other button and does not provide any visual indication that it supports variable pressure. To provide this type of visual indication, you can apply a custom image to the button.

      On a system that doesn’t support pressure sensitivity, an accelerator button behaves like a button of type NSMomentaryLightButton.

      Available in OS X v10.10.3 and later.

    • MultiLevelAcceleratorButton

      NSMultiLevelAcceleratorButton

      A multilevel accelerator button is a variation of a normal accelerator button that allows for a configurable number of stepped pressure levels. As each one is reached, the user receives light tactile feedback and an action is sent.

      The number of pressure levels for a multilevel accelerator button is configured by adjusting the value of the maxAcceleratorLevel property of NSButton. 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.

      Like a normal accelerator button, the button sends an action when the user first clicks it. If configured as continuous (see setContinuous:), while pressed, it then sends actions at repeating intervals that are based on pressure. If not configured as continuous, actions are sent as the user force clicks (presses harder) and reaches different levels of pressure. Once released, a final action is sent.

      The value of a multilevel accelerator button is distinct from its state. The integerValue of a multilevel button is 0 when not clicked, or 1 through 5 when clicked, depending on the level of pressure. If the value of a multilevel accelerator button is explicitly set, actions are not sent until pressure reaches the specified level.

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

      Available in OS X v10.10.3 and later.

    • MomentaryPushInButton

      NSMomentaryPushInButton

      When the user clicks the button (on state), the button appears illuminated.

      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.

      Most buttons in OS X, such as Cancel button in many dialogs, are momentary light buttons. If you click one, it highlights briefly, triggers an action, and returns to its original state.

      This button type is the default.

      Available in OS X v10.0 and later.

    • NSMomentaryPushButton

      NSMomentaryPushButton

      When the button is clicked (on state), it appears illuminated. If the button has a bordered, it may also appear recessed. When the button is released, it returns to its normal (off) state.

      Use NSMomentaryLightButton instead.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.9.

    • NSMomentaryLight

      NSMomentaryLight

      When the button is clicked (on state), it appears illuminated.

      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 the gradientType property.

    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.