- Inherits from:
- NSActionCell : NSCell : NSObject
- Package:
- com.apple.yellow.application
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 a String containing a single character "1"), or 0 for the "off" or normal state ( stringValue returns a String 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 throws a BadComparisonException if the otherCell argument is not of the NSButtonCell class.
- Constructors
- NSButtonCell
- 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
- setPeriodicDelayAndInterval
- Setting the key equivalent
- keyEquivalent
- keyEquivalentFont
- keyEquivalentModifierMask
- setKeyEquivalent
- setKeyEquivalentModifierMask
- setKeyEquivalentFont
- setKeyEquivalentFontAndSize
- 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
public NSButtonCell()
public NSButtonCell(String aString)
public NSButtonCell(NSImage anImage)
public NSImage alternateImage()
See Also: imagePosition, keyEquivalent, setButtonType, image (NSCell)
public String alternateMnemonic()
See Also: alternateMnemonicLocation, setAlternateTitleWithMnemonic, mnemonic( NSCell)
public int alternateMnemonicLocation()
NSArray.NotFound
is
returned.See Also: alternateMnemonic, setAlternateTitleWithMnemonic, mnemonicLocation (NSCell)
public String alternateTitle()
See Also: alternateMnemonic, attributedAlternateTitle, setButtonType, title
public NSAttributedString attributedAlternateTitle()
See Also: alternateMnemonic, attributedTitle, setButtonType
public NSAttributedString attributedTitle()
See Also: attributedAlternateTitle, setButtonType, mnemonic (NSCell)
public int bezelStyle()
See Also: setBezelStyle
public int gradientType()
public int highlightsBy()
See Also: showsStateBy
public boolean imageDimsWhenDisabled()
SwitchButton
and RadioButton
do
dim when disabled. When SwitchButtons
and RadioButtons
are
disabled, only the associated text dims.See Also: setButtonType, setImageDimsWhenDisabled
public int 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)
public boolean isOpaque()
See Also: isTransparent
public boolean isTransparent()
See Also: isOpaque
public String keyEquivalent()
See Also: keyEquivalentFont
public NSFont keyEquivalentFont()
See Also: setFont
public int keyEquivalentModifierMask()
NSEvent.ControlKeyMask
, NSEvent.AlternateKeyMask
,
and NSEvent.CommandKeyMask
bits.See Also: keyEquivalent
public void mouseEntered(NSEvent event)
public void mouseExited(NSEvent event)
public void performClick(Object sender)
public void setAlternateImage(NSImage image)
See Also: setButtonType, setImage (NSCell)
public void setAlternateMnemonicLocation(int location)
NSArray.NotFound
.setAlternateMnemonicLocation doesn't cause the button cell to be redisplayed.
See Also: setAlternateTitleWithMnemonic
public void setAlternateTitle(String aString)
See Also: setAlternateMnemonicLocation, setAlternateTitleWithMnemonic, setTitle, setButtonType, setFont
public void setAlternateTitleWithMnemonic(String aString)
If necessary, setAlternateTitleWithMnemonic redraws the button cell. Note that some button types don't display an alternate title.
See Also: setAlternateMnemonicLocation, setTitleWithMnemonic
public void setAttributedAlternateTitle(NSttributedString aString)
See Also: setAlternateMnemonicLocation, setAlternateTitleWithMnemonic, setAttributedTitle, setButtonType, setFont
public void setAttributedTitle(NSAttributedString aString)
See Also: setAttributedAlternateTitle, setButtonType, setFont, setMnemonicLocation (NSCell)
public void setBezelStyle(int bezelStyle)
Bezel Style | Description |
RoundedBezelStyle |
A rounded rectangle button, designed for text. |
RegularSquareBezelStyle |
A rectangular button with a 2 pixel border, designed for icons. |
ThickSquareBezelStyle |
A rectangular button with a 3 pixel border, designed for icons. |
ThickerSquareBezelStyle |
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
public void setButtonType(int 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 |
MomentaryPushInButton |
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. |
MomentaryLightButton |
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. |
MomentaryChangeButton |
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. |
PushOnPushOffButton |
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. |
OnOffButton |
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. |
ToggleButton |
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. |
SwitchButton |
This is a variant of ToggleButton that
has no border, with the default image set to "Switch ,"
and the alternate image set to "HighlightedSwitch "
(these are system bitmaps). This type of button is available as
a separate palette item in Interface Builder. |
RadioButton |
Like SwitchButton , but
the default image is set to "RadioButton "
and the alternate image is set to "HighlightedRadioButton "
(these are system bitmaps). This type of button is available as
a separate palette item in Interface Builder. |
See Also: setAlternateImage, setImage (NSCell)
public 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, setKeyEquivalentFontAndSize, font (NSCell)
public void setGradientType(int gradientType)
gradientType can be one of the following constants:
Value | Description |
GradientNone |
There is no gradient, so the button looks flat. |
GradientConcanveWeak |
The top left corner is light gray and the bottom right corner is dark gray, so the button appears to be pushed in. |
GradientConcaveStrong |
As with GradientConcanveWeak ,
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. |
GradientConvexWeak |
The top left corner is dark gray and the bottom right corner is light gray, so the button appears to be sticking out. |
GradientConcaveStrong |
As with GradientConvexWeak ,
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
public void setHighlightsBy(int aType)
If
both ChangeGrayCellMask
and ChangeBackgroundCellMask
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, ChangeGrayCellMask
is
used. If the image does have alpha data, ChangeBackgroundCellMask
is
used; this allows the color swap of the background to show through
the image's transparent pixels.
See Also: setShowsStateBy
public void setImageDimsWhenDisabled(boolean flag)
SwitchButton
and RadioButton
do
dim when disabled. When SwitchButtons
and RadioButtons
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.public void setImagePosition(int aPosition)
public void setKeyEquivalent(String aKeyEquivalent)
NSCell.NoImage
, NSCell.ImageOnly
or NSCell.ImageOverlaps
;
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 null, then set the key equivalent, then set the image position.
See Also: setAlternateImage, setImagePosition, setKeyEquivalentFont, setImage (NSCell)
public void setKeyEquivalentFont(NSFont fontObj)
See Also: setFont
public void setKeyEquivalentFontAndSize(
String fontName,
float fontSize)
See Also: setFont
public void setKeyEquivalentModifierMask(int mask)
NSEvent.ControlKeyMask
, NSEvent.AlternateKeyMask
,
and NSEvent.CommandKeyMask
bits.See Also: setKeyEquivalent
public void setPeriodicDelayAndInterval(
float delay,
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)
public void setShowsBorderOnlyWhileMouseInside(boolean show)
See Also: showsBorderOnlyWhileMouseInside
public void setShowsStateBy(int aType)
Value | Description |
NoCellMask |
The button cell doesn't change. This mask is ignored if any others are set in aType. This is the default. |
ContentsCellMask |
The button cell displays its alternate icon and/or title. |
ChangeGrayCellMask |
The button cell swaps the "control color" (NSColor's controlColor) and white pixels on its background and icon. |
ChangeBackgroundCellMask |
Same as ChangeGrayCellMask ,
but only the background pixels are changed. |
If both ChangeGrayCellMask
and ChangeBackgroundCellMask
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, ChangeGrayCellMask
is
used. If the image exists and has alpha data, ChangeBackgroundCellMask
is
used; this allows the color swap of the background to show through
the image's transparent pixels.
See Also: setHighlightsBy, showsStateBy
public void setSound(Object aSound)
NSEvent.LeftMouseDown
.See Also: sound
public void setTitle(String aString)
See Also: setAlternateTitle, setButtonType, setFont, setTitleWithMnemonic
public void setTitleWithMnemonic(String aString)
See Also: setAlternateTitleWithMnemonic, setTitleWithMnemonic (NSCell), setMnemonicLocation (NSCell)
public void setTransparent(boolean flag)
public boolean showsBorderOnlyWhileMouseInside()
See Also: setShowsBorderOnlyWhileMouseInside
public int showsStateBy()
See Also: highlightsBy, setShowsStateBy
public Object sound()
See Also: setSound
public String title()
See Also: alternateTitle, setButtonType, mnemonic (NSCell), mnemonicLocation (NSCell)