Inherits from: NSActionCell : NSCell : NSObject
Package: com.apple.yellow.application
Implements: NSCoding (from NSCell) NSCopying (from NSCell)
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 throws an exception 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:
- 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(String aString)
public NSButtonCell(NSImage anImage)
public NSImage alternateImage()
null
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)
public String alternateMnemonic()
See Also: alternateMnemonicLocation, setAlternateTitleWithMnemonic, - mnemonic(NSCell)
public int alternateMnemonicLocation()
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()
See Also: setButtonType
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()
null
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
public int keyEquivalentModifierMask()
See Also: keyEquivalent
public void mouseEntered(NSEvent event)
true
.public void mouseExited(NSEvent event)
true
.public void performClick(Object sender)
public void setAlternateImage(NSImage image)
See Also: setButtonType, setImage(NSCell)
public void setAlternateMnemonicLocation(int location)
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 |
NeXTBezelStyle | A rectangular button with a 2 pixel border. It looks like OPENSTEP 4.2 button and is available for backwards compatibility only. |
PushButtonBezelStyle | A rounded rectangle button, designed for text. |
SmallIconButtonBezelStyle | A rectangular button with a 2 pixel border, designed for icons. |
MediumIconButtonBezelStyle | A rectangular button with a 3 pixel border, designed for icons. |
LargeIconButtonBezelStyle | 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 |
MomentaryLight | 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. |
MomentaryPushButton | 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. |
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 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. |
RadioButton | Like SwitchButton, 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)
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 contants:
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.
public void setImageDimsWhenDisabled(boolean flag)
public void setImagePosition(int aPosition)
public void setKeyEquivalent(String aKeyEquivalent)
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)
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)
true
, the border is displayed
only when the mouse is within the button cell's border and the
the button is active. If show is false
,
the button's border continues to be displayed when the mouse is
outside button's bounds.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)
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 int showsStateBy()
See Also: highlightsBy, setShowsStateBy
public boolean showsBorderOnlyWhileMouseInside()
true
the
button's border is displayed only when the mouse is over the button
and the button is active. By default, this method
returns false
.See Also: setShowsBorderOnlyWhileMouseInside
public Object sound()
See Also: setSound
public String
title
()
See Also: alternateTitle, setButtonType, mnemonic(NSCell) mnemonicLocation(NSCell)