- Inherits from:
- NSActionCell : NSCell : NSObject
- Conforms to:
- NSCoding
- (NSCell)
- NSCopying (NSCell)
- NSObject (NSObject)
Declared in:
- AppKit/NSButtonCell.h
NSButtonCell is a subclass of NSActionCell used to implement the user interfaces of push buttons, 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. To create groups of switches or radio buttons, use an NSMatrix holding a set of NSButtonCells.
An NSButtonCell is a two-state cell; it's either "off" or "on," and can be configured to display the two states differently, with a separate title and/or image for either state. The two states are more often referred to as "normal" and "alternate." An NSButtonCell's state is also used as its value, so NSCell methods that set the value ( setIntValue: and so on) actually set the NSButtonCell's state to "on" if the value provided is non-zero (or non-null for strings), and to "off" if the value is zero or null. Similarly, methods that retrieve the value return 1 for the "on" or alternate state ( stringValue returns an NSString containing a single character "1"), or 0 for the "off" or normal state ( stringValue returns an NSString containing a single character "0"). You can also use NSCell's setState: and state methods to set or retrieve the state directly. After changing the state, send a display message to show the NSButtonCell's new appearance. (NSButton does this automatically.)
An NSButtonCell sends its action message to its target once if its view is clicked and it gets the mouse-down event, but can also send the action message continuously as long as the mouse is held down with the cursor inside the NSButtonCell. The NSButtonCell can show that it's being pressed by highlighting in several ways-for example, a bordered NSButtonCell can appear pushed into the screen, or the image or title can change to an alternate form while the NSButtonCell is pressed.
An NSButtonCell can also have a key equivalent (like a menu item). If the NSButtonCell is displayed in the key window, the NSButtonCell gets the first chance to receive events related to key equivalents. This feature is used quite often in modal panels that have an "OK" button. An NSButtonCell can either display a graphical image representing the key equivalent, or you can mark the keyboard "mnemonic" character in the NSButtonCell's title using setTitleWithMnemonic:, setAlternateTitleWithMnemonic:, or setAlternateMnemonicLocation:.
For more information on NSButtonCell's behavior, see the NSButton and NSMatrix class specifications.
In its implementation of the compare: method (declared in NSCell), NSButtonCell raises an NSBadComparisonException if the otherCell argument is not of the NSButtonCell class.
- Setting the titles
- - alternateMnemonic
- - alternateMnemonicLocation
- - alternateTitle
- - attributedAlternateTitle
- - attributedTitle
- - setAlternateMnemonicLocation:
- - setAlternateTitle:
- - setAlternateTitleWithMnemonic:
- - setAttributedAlternateTitle:
- - setAttributedTitle:
- - setFont:
- - setTitle:
- - setTitleWithMnemonic:
- - title
- Setting the images
- - alternateImage
- - imagePosition
- - setAlternateImage:
- - setImagePosition:
- Setting the repeat interval
- - getPeriodicDelay:interval:
- - setPeriodicDelay:interval:
- Setting the key equivalent
- - keyEquivalent
- - keyEquivalentFont
- - keyEquivalentModifierMask
- - setKeyEquivalent:
- - setKeyEquivalentModifierMask:
- - setKeyEquivalentFont:
- - setKeyEquivalentFont:size:
- Modifying graphic attributes
- - bezelStyle
- - gradientType
- - imageDimsWhenDisabled
- - isOpaque
- - isTransparent
- - setBezelStyle:
- - setShowsBorderOnlyWhileMouseInside:
- - setGradientType:
- - setImageDimsWhenDisabled:
- - setTransparent:
- - showsBorderOnlyWhileMouseInside
- Displaying
- - highlightsBy
- - setHighlightsBy:
- - setShowsStateBy:
- - setButtonType:
- - showsStateBy
- Playing sound
- - setSound:
- - sound
- Handling events and action messages
- - mouseEntered:
- - mouseExited:
- - performClick:
- (NSImage *)alternateImage
See Also: - imagePosition, - keyEquivalent, - setButtonType:, - image (NSCell)
- (NSString *)alternateMnemonic
See Also: - alternateMnemonicLocation, - setAlternateTitleWithMnemonic:, - mnemonic( NSCell)
- (unsigned)alternateMnemonicLocation
NSNotFound
is
returned.See Also: - alternateMnemonic, - setAlternateTitleWithMnemonic:, - mnemonicLocation (NSCell)
- (NSString *)alternateTitle
See Also: - alternateMnemonic, - attributedAlternateTitle, - setButtonType:, - title
- (NSAttributedString *)attributedAlternateTitle
See Also: - alternateMnemonic, - attributedTitle, - setButtonType:
- (NSAttributedString *)attributedTitle
See Also: - attributedAlternateTitle, - setButtonType:, - mnemonic (NSCell)
- (NSBezelStyle)bezelStyle
See Also: - setBezelStyle:
- (void)getPeriodicDelay:(float
*)delay
interval:(float *)interval
Default delay and interval values are taken from a user's defaults (60 seconds maximum for each); if the user hasn't specified default values, delay defaults to 0.4 seconds and interval defaults to 0.075 seconds.
See Also: - isContinuous, - isContinuous (NSCell)
- (NSGradientType)gradientType
- (int)highlightsBy
See Also: - showsStateBy
- (BOOL)imageDimsWhenDisabled
NSSwitchButton
and NSRadioButton
do
dim when disabled. When NSSwitchButtons
and NSRadioButtons
are
disabled, only the associated text dims.See Also: - setButtonType:, - setImageDimsWhenDisabled:
- (NSCellImagePosition)imagePosition
If the title is above, below, or overlapping the image, or if there is no image, the text is horizontally centered within the button.
See Also: - setButtonType:, - setTitle:, - setImage: (NSCell)
- (BOOL)isOpaque
See Also: - isTransparent
- (BOOL)isTransparent
See Also: - isOpaque
- (NSString *)keyEquivalent
See Also: - keyEquivalentFont
- (NSFont *)keyEquivalentFont
See Also: - setFont:
- (unsigned int)keyEquivalentModifierMask
NSControlKeyMask
, NSAlternateKeyMask
,
and NSCommandKeyMask
bits.See Also: - keyEquivalent
- (void)mouseEntered:(NSEvent
*)event
- (void)mouseExited:(NSEvent
*)event
- (void)performClick:(id)sender
- (void)setAlternateImage:(NSImage
*)image
See Also: - setButtonType:, - setImage: (NSCell)
- (void)setAlternateMnemonicLocation:(unsigned)location
NSNotFound
.setAlternateMnemonicLocation: doesn't cause the button cell to be redisplayed.
See Also: - setAlternateTitleWithMnemonic:
- (void)setAlternateTitle:(NSString
*)aString
See Also: - setAlternateMnemonicLocation:, - setAlternateTitleWithMnemonic:, - setTitle:, - setButtonType:, - setFont:
- (void)setAlternateTitleWithMnemonic:(NSString
*)aString
If necessary, setAlternateTitleWithMnemonic: redraws the button cell. Note that some button types don't display an alternate title.
See Also: - setAlternateMnemonicLocation:, - setTitleWithMnemonic:
- (void)setAttributedAlternateTitle:(NSAttributedString
*)aString
See Also: - setAlternateMnemonicLocation:, - setAlternateTitleWithMnemonic:, - setAttributedTitle:, - setButtonType:, - setFont:
- (void)setAttributedTitle:(NSAttributedString
*)aString
See Also: - setAttributedAlternateTitle:, - setButtonType:, - setFont:, - setMnemonicLocation: (NSCell)
- (void)setBezelStyle:(NSBezelStyle)bezelStyle
Bezel Style | Description |
NSRoundedBezelStyle |
A rounded rectangle button, designed for text. |
NSRegularSquareBezelStyle |
A rectangular button with a 2 pixel border, designed for icons. |
NSThickSquareBezelStyle |
A rectangular button with a 3 pixel border, designed for icons. |
NSThickerSquareBezelStyle |
A rectangular button with a 4 pixel border, designed for icons. |
The button uses shading to look like it's sticking out or pushed in. You can set the shading with setGradientType:.
If the button is not bordered, the bezel style is ignored.
See Also: - bezelStyle
- (void)setButtonType:(NSButtonType)aType
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.
aType can be one of eight constants:
Button Type | Description |
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 is the default button type. |
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. |
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. |
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. |
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. |
NSToggleButton |
The first click highlights the button, while a second click returns it to its normal state. Highlighting is performed by changing to the alternate title or image and showing the button as "pushed in" if the button is bordered. This option is called "Toggle" in Interface Builder's Button Inspector. |
NSSwitchButton |
This is a variant of NSToggleButton that
has no border, with the default image set to "NSSwitch ,"
and the alternate image set to "NSHighlightedSwitch "
(these are system bitmaps). This type of button is available as
a separate palette item in Interface Builder. |
NSRadioButton |
Like NSSwitchButton , but
the default image is set to "NSRadioButton "
and the alternate image is set to "NSHighlightedRadioButton "
(these are system bitmaps). This type of button is available as
a separate palette item in Interface Builder. |
See Also: - setAlternateImage:, - setImage: (NSCell)
- (void)setFont:(NSFont
*)fontObj
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.
See Also: - setKeyEquivalentFont:, - setKeyEquivalentFont:size:, - font (NSCell)
- (void)setGradientType:(NSGradientType)gradientType
gradientType can be one of the following constants:
Value | Description |
NSGradientNone |
There is no gradient, so the button looks flat. |
NSGradientConcanveWeak |
The top left corner is light gray and the bottom right corner is dark gray, so the button appears to be pushed in. |
NSGradientConcaveStrong |
As with NSGradientConcanveWeak ,
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. |
NSGradientConvexWeak |
The top left corner is dark gray and the bottom right corner is light gray, so the button appears to be sticking out. |
NSGradientConcaveStrong |
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. |
See Also: - gradientType
- (void)setHighlightsBy:(int)aType
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 allows the color swap of the background to show through the
image's transparent pixels.
See Also: - setShowsStateBy:
- (void)setImageDimsWhenDisabled:(BOOL)flag
NSSwitchButton
and NSRadioButton
do
dim when disabled. When NSSwitchButtons
and NSRadioButtons
are
disabled, only the associated text associated 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:.- (void)setImagePosition:(NSCellImagePosition)aPosition
- (void)setKeyEquivalent:(NSString
*)aKeyEquivalent
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.
See Also: - setAlternateImage:, - setImagePosition:, - setKeyEquivalentFont:, - setImage: (NSCell)
- (void)setKeyEquivalentFont:(NSFont
*)fontObj
See Also: - setFont:
- (void)setKeyEquivalentFont:(NSString
*)fontName
size:(float)
See Also: - setFont:
- (void)setKeyEquivalentModifierMask:(unsigned
int)mask
NSControlKeyMask
, NSAlternateKeyMask
,
and NSCommandKeyMask
bits.See Also: - setKeyEquivalent:
- (void)setPeriodicDelay:(float)delay
interval:(float)interval
The maximum value allowed for both delay and interval is 60.0 seconds; if a larger value is supplied, it's ignored and 60.0 seconds is used.
See Also: - setContinuous: (NSCell)
- (void)setShowsBorderOnlyWhileMouseInside:(BOOL)show
See Also: - showsBorderOnlyWhileMouseInside
- (void)setShowsStateBy:(int)aType
Value | Description |
NSNoCellMask |
The button cell doesn't change. This mask is ignored if any others are set in aType. This is the default. |
NSContentsCellMask |
The button cell displays its alternate icon and/or title. |
NSChangeGrayCellMask |
The button cell swaps the "control color" (NSColor's controlColor) and white pixels on its background and icon. |
NSChangeBackgroundCellMask |
Same as NSChangeGrayCellMask ,
but only the background pixels are changed. |
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 allows the color swap of the background to show through the
image's transparent pixels.
See Also: - setHighlightsBy:, - showsStateBy
- (void)setSound:(NSSound
*)aSound
NSLeftMouseDown
.See Also: - sound
- (void)setTitle:(NSString
*)aString
See Also: - setAlternateTitle:, - setButtonType:, - setFont:, - setTitleWithMnemonic:
- (void)setTitleWithMnemonic:(NSString
*)aString
See Also: - setAlternateTitleWithMnemonic:, - setTitleWithMnemonic: (NSCell), - setMnemonicLocation: (NSCell)
- (void)setTransparent:(BOOL)flag
- (BOOL)showsBorderOnlyWhileMouseInside
See Also: - setShowsBorderOnlyWhileMouseInside:
- (int)showsStateBy
See Also: - highlightsBy, - setShowsStateBy:
- (NSSound *)sound
See Also: - setSound:
- (NSString *)title
See Also: - alternateTitle, - setButtonType:, - mnemonic (NSCell), - mnemonicLocation (NSCell)