Apple Developer Connection
Member Login Log In | Not a Member? Contact ADC

Next Page > Hide TOC

NSButtonCell Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in Mac OS X v10.0 and later.
Companion guide
Declared in
NSButtonCell.h

Overview

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 YES for on, NO 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 for Cocoa.

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.

Tasks

Setting Titles

Managing Images

Managing the Repeat Interval

Managing the Key Equivalent

Managing Graphics Attributes

Displaying the Cell

Managing the Sound

Handling Events and Action Messages

Drawing the Button Content

Instance Methods

alternateImage

Returns the image the button displays in its alternate state.

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

Availability
See Also
Declared In
NSButtonCell.h

alternateMnemonic

Returns the character in the alternate title that’s marked as the “keyboard mnemonic.”

- (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 Mac OS X.

Availability
See Also
Declared In
NSButtonCell.h

alternateMnemonicLocation

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

- (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 Mac OS X.

Availability
See Also
Declared In
NSButtonCell.h

alternateTitle

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

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

Availability
See Also
Declared In
NSButtonCell.h

attributedAlternateTitle

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

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

Availability
See Also
Declared In
NSButtonCell.h

attributedTitle

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

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

Availability
See Also
Declared In
NSButtonCell.h

backgroundColor

Returns the background color of the receiver.

- (NSColor *)backgroundColor

Return Value

The receiver’s background color.

Discussion

The background color is used only when drawing borderless buttons.

Availability
See Also
Declared In
NSButtonCell.h

bezelStyle

Returns the appearance of the receiver’s border.

- (NSBezelStyle)bezelStyle

Return Value

A constant specifying the bezel style used by the button. See “Bezel Styles” for a list of possible values.

Availability
See Also
Declared In
NSButtonCell.h

drawBezelWithFrame:inView:

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

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

Availability
See Also
Declared In
NSButtonCell.h

drawImage:withFrame:inView:

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

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

Availability
See Also
Declared In
NSButtonCell.h

drawTitle:withFrame:inView:

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

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

Availability
See Also
Declared In
NSButtonCell.h

getPeriodicDelay:interval:

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

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

Availability
See Also
Declared In
NSButtonCell.h

gradientType

Returns the gradient of the receiver’s border.

- (NSGradientType)gradientType

Return Value

A constant specifying the gradient used for the button's border. See “Gradient Types” for a list of possible values.

Availability
See Also
Declared In
NSButtonCell.h

highlightsBy

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

- (NSInteger)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.

Availability
See Also
Declared In
NSButtonCell.h

imageDimsWhenDisabled

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

- (BOOL)imageDimsWhenDisabled

Return Value

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

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.

Availability
See Also
Declared In
NSButtonCell.h

imagePosition

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

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

Availability
See Also
Declared In
NSButtonCell.h

imageScaling

Returns the scale factor for the receiver’s image.

- (NSImageScaling)imageScaling

Return Value

The scale factor for the receiver’s image.

Availability
Declared In
NSButtonCell.h

isOpaque

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

- (BOOL)isOpaque

Return Value

YES if the receiver draws over every pixel in its frame, otherwise NO.

Discussion

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

Availability
See Also
Declared In
NSButtonCell.h

isTransparent

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

- (BOOL)isTransparent

Return Value

YES if the receiver is transparent, NO otherwise.

Discussion

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

Availability
See Also
Declared In
NSButtonCell.h

keyEquivalent

Returns the receiver's key-equivalent character.

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

Availability
See Also
Declared In
NSButtonCell.h

keyEquivalentFont

Returns the font used to draw the key equivalent.

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

Availability
See Also
Declared In
NSButtonCell.h

keyEquivalentModifierMask

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

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

Availability
See Also
Declared In
NSButtonCell.h

mouseEntered:

Draws the receiver’s border.

- (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 YES.

Availability
Declared In
NSButtonCell.h

mouseExited:

Erases the receiver’s border.

- (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 YES.

Availability
Declared In
NSButtonCell.h

performClick:

Simulates the user clicking the receiver with the cursor.

- (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:.

Availability
Declared In
NSButtonCell.h

setAlternateImage:

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

- (void)setAlternateImage:(NSImage *)image

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.

Availability
See Also
Declared In
NSButtonCell.h

setAlternateMnemonicLocation:

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

- (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 Mac OS X.

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

Availability
See Also
Declared In
NSButtonCell.h

setAlternateTitle:

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

- (void)setAlternateTitle:(NSString *)aString

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.

Availability
See Also
Declared In
NSButtonCell.h

setAlternateTitleWithMnemonic:

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

- (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 Mac OS X.

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

Availability
See Also
Declared In
NSButtonCell.h

setAttributedAlternateTitle:

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

- (void)setAttributedAlternateTitle:(NSAttributedString *)aString

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.

Availability
See Also
Declared In
NSButtonCell.h

setAttributedTitle:

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

- (void)setAttributedTitle:(NSAttributedString *)aString

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.

Availability
See Also
Declared In
NSButtonCell.h

setBackgroundColor:

Sets the background color of the receiver.

- (void)setBackgroundColor:(NSColor *)color

Parameters
color

The color to use for the receiver’s background.

Discussion

The background color is used only when drawing borderless buttons.

Availability
See Also
Declared In
NSButtonCell.h

setBezelStyle:

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

- (void)setBezelStyle:(NSBezelStyle)bezelStyle

Parameters
bezelStyle

A constant specifying the bezel style to use for the button. This must be one of the values specified in “Bezel Styles.”

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

Availability
See Also
Declared In
NSButtonCell.h

setButtonType:

Sets how the receiver highlights while pressed and how it shows its state.

- (void)setButtonType:(NSButtonType)aType

Parameters
aType

A constant specifying the type of button. This can be one of the constants defined in “Button Types.”

Discussion

setButtonType: 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.

Availability
See Also
Declared In
NSButtonCell.h

setFont:

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

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

Availability
See Also
Declared In
NSButtonCell.h

setGradientType:

Sets the type of gradient to use for the receiver.

- (void)setGradientType:(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 “Gradient Types.”

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.

Availability
See Also
Declared In
NSButtonCell.h

setHighlightsBy:

Sets the way the receiver highlights itself while pressed.

- (void)setHighlightsBy:(NSInteger)aType

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.

Availability
See Also
Declared In
NSButtonCell.h

setImageDimsWhenDisabled:

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

- (void)setImageDimsWhenDisabled:(BOOL)flag

Parameters
flag

YES 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:.

Availability
See Also
Declared In
NSButtonCell.h

setImagePosition:

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

- (void)setImagePosition:(NSCellImagePosition)aPosition

Parameters
aPosition

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

Availability
See Also
Declared In
NSButtonCell.h

setImageScaling:

Sets the scale factor for the receiver’s image.

- (void)setImageScaling:(NSImageScaling)scaling

Parameters
scaling

The scale factor for the receiver’s image.

Availability
Declared In
NSButtonCell.h

setKeyEquivalent:

Sets the key equivalent character of the receiver.

- (void)setKeyEquivalent:(NSString *)aKeyEquivalent

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.

Availability
See Also
Declared In
NSButtonCell.h

setKeyEquivalentFont:

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

- (void)setKeyEquivalentFont:(NSFont *)fontObj

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.

Availability
See Also
Declared In
NSButtonCell.h

setKeyEquivalentFont:size:

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

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

Availability
See Also
Declared In
NSButtonCell.h

setKeyEquivalentModifierMask:

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

- (void)setKeyEquivalentModifierMask:(NSUInteger)mask

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.

Availability
See Also
Declared In
NSButtonCell.h

setPeriodicDelay:interval:

Sets the message delay and interval for the receiver.

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

Availability
See Also
Declared In
NSButtonCell.h

setShowsBorderOnlyWhileMouseInside:

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

- (void)setShowsBorderOnlyWhileMouseInside:(BOOL)show

Parameters
show

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

Availability
See Also
Declared In
NSButtonCell.h

setShowsStateBy:

Sets the way the receiver indicates its alternate state.

- (void)setShowsStateBy:(NSInteger)aType

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.

Availability
See Also
Declared In
NSButtonCell.h

setSound:

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

- (void)setSound:(NSSound *)aSound

Parameters
aSound

The sound to play when the button is pressed.

Discussion

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

Availability
See Also
Declared In
NSButtonCell.h

setTitle:

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

- (void)setTitle:(NSString *)aString

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.

Availability
See Also
Declared In
NSButtonCell.h

setTitleWithMnemonic:

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

- (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 Mac OS X.

Availability
See Also
Declared In
NSButtonCell.h

setTransparent:

Sets whether the receiver is transparent.

- (void)setTransparent:(BOOL)flag

Parameters
flag

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

Availability