Inherits from: NSActionCell : NSCell : NSObject
Conforms to: NSCoding
(from NSCell)
NSCopying (from NSCell)
NSObject (from 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
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.See Also: - imagePosition, - keyEquivalent, - setButtonType:, - image(NSCell)
- (NSString *)alternateMnemonic
See Also: - alternateMnemonicLocation, - setAlternateTitleWithMnemonic:, - mnemonic(NSCell)
- (unsigned)alternateMnemonicLocation
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
See Also: - setButtonType:
- (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
nil
if
the button cell doesn't have a key equivalent. The
default font is the same as that used to draw the title.See Also: - setFont:
- (unsigned int)keyEquivalentModifierMask
See Also: - keyEquivalent
- (void) mouseEntered:(NSEvent
*)event
YES
.- (void) mouseExited:(NSEvent
*)event
YES
.- (void)performClick:(id)sender
- (void)setAlternateImage:(NSImage
*)image
See Also: - setButtonType:, - setImage:(NSCell)
- (void)setAlternateMnemonicLocation:(unsigned)location
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 |
NSNeXTBezelStyle | A rectangular button with a 2 pixel border. It looks like OPENSTEP 4.2 button and is available for backwards compatibility only. |
NSPushButtonBezelStyle | A rounded rectangle button, designed for text. |
NSSmallIconButtonBezelStyle | A rectangular button with a 2 pixel border, designed for icons. |
NSMediumIconButtonBezelStyle | A rectangular button with a 3 pixel border, designed for icons. |
NSLargeIconButtonBezelStyle | 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 |
NSMomentaryLight | 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 Light" in Interface Builder's Button Inspector. This is the default button type. |
NSMomentaryPushButton | 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 Push" 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 contants:
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.
- (void)setImageDimsWhenDisabled:(BOOL)flag
- (void)setImagePosition:(NSCellImagePosition)aPosition
- (void)setKeyEquivalent:(NSString
*)aKeyEquivalent
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
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
YES
, the border is displayed
only when the mouse is within the button cell's border and the
the button is active. If show is NO
,
the button's border continues to be displayed when the mouse is
outside button's bounds.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.
- setHighlightsBy:, - showsStateBy
- (void)setSound:(NSSound
*)aSound
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
- (int)showsStateBy
See Also: - highlightsBy, - setShowsStateBy:
- (BOOL)
showsBorderOnlyWhileMouseInside
YES
the
button's border is displayed only when the mouse is over the button
and the button is active. By default, this method
returns NO
.See Also: - setShowsBorderOnlyWhileMouseInside:
- (NSSound *)sound
See Also: - setSound:
- (NSString *)title
See Also: - alternateTitle, - setButtonType:, - mnemonic(NSCell) - mnemonicLocation(NSCell)