Class

NSButtonCell

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

Declaration

@interface NSButtonCell : NSActionCell

Overview

Setting the integer, float, double, or object value of an NSButtonCell object results in a call to state with the value converted to integer. In the case of objectValue, 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 YES for on, NO 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.

The configuration of an NSButtonCell object controls how the button object appears and behaves, but it's NSButton that sends a message when the control is clicked. 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.

Topics

Setting Titles

- alternateMnemonic

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

Deprecated
- alternateMnemonicLocation

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

Deprecated
alternateTitle

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

attributedAlternateTitle

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

attributedTitle

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

- setAlternateMnemonicLocation:

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

Deprecated
- setAlternateTitleWithMnemonic:

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

Deprecated
- setFont:

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

- setTitleWithMnemonic:

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

Deprecated
title

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

Managing Images

alternateImage

The image the button displays in its alternate state.

imagePosition

The position of the button’s image relative to its title.

imageScaling

The scale factor for the button’s image.

Managing the Repeat Interval

- getPeriodicDelay:interval:

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

- setPeriodicDelay:interval:

Sets the message delay and interval for the button.

Managing the Key Equivalent

keyEquivalent

The button’s key-equivalent character.

keyEquivalentFont

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

Deprecated
keyEquivalentModifierMask

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

- setKeyEquivalentFont:size:

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

Deprecated

Managing Graphics Attributes

backgroundColor

The background color of the button.

bezelStyle

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

gradientType

The gradient of the button’s border.

Deprecated
imageDimsWhenDisabled

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

opaque

A Boolean value that indicates if the button is opaque.

transparent

A Boolean value that indicates if the button is transparent.

showsBorderOnlyWhileMouseInside

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

Displaying the Cell

highlightsBy

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

- setButtonType:

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

showsStateBy

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

Managing the Sound

sound

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

Handling Events and Action Messages

- mouseEntered:

Draws the button’s border.

- mouseExited:

Erases the button’s border.

- performClick:

Simulates the user clicking the button with the pointer.

Drawing the Button Content

- drawBezelWithFrame:inView:

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

- drawImage:withFrame:inView:

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

- drawTitle:withFrame:inView:

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

Constants

NSBezelStyle

Bezel styles used by the bezelStyle property.

NSButtonType

Button types that can be specified using setButtonType:.

NSGradientType

Specify the gradients used by the gradientType property.

Deprecated

Relationships

Inherits From