ADC Home > Reference Library > Reference > Legacy Documents > Cocoa > Application Kit Reference for Java (Legacy) >

Next Page > Hide TOC

Legacy Documentclose button

Important: The information in this document is obsolete and should not be used for new development.

NSButtonCell

Inherits from
Implements
Package
com.apple.cocoa.application
Companion guide

Overview

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.

NSButtonCell implements the user interface of NSButton.

Setting an NSButtonCell's integer, float, double, or object value results in a call to setState with the value converted to integer. In the case of setObjectValue, null is equivalent to 0, and a non-null object that doesn't respond to intValue sets the state to 1. Otherwise, the state is set to the object's intValue. Similarly, 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 a number containing true for on, false for off, and integer value -1 for the mixed state.

For more information on NSButtonCell’s behavior, see the NSButton and NSMatrix class specifications.

Exceptions

In its implementation of the compare method (declared in NSCell), NSButtonCell throws a BadComparisonException if the otherCell argument is not of the NSButtonCell class.

Tasks

Constructors

Setting the Titles

Setting the Images

Setting the Repeat Interval

Setting the Key Equivalent

Modifying Graphics Attributes

Displaying

Playing Sound

Handling Events and Action Messages

Drawing the Button Content

Constructors

NSButtonCell

Creates an empty NSButtonCell.

public NSButtonCell()

Creates an NSButtonCell initialized with aString.

public NSButtonCell(String aString)

Creates an NSButtonCell initialized with anImage.

public NSButtonCell(NSImage anImage)

Discussion

If anImage is null, no image is set.

Instance Methods

alternateImage

Returns the image that appears on the receiver when it’s in its alternate state, or null if there is no alternate image.

public NSImage alternateImage()

Discussion

Note that some button types don’t display an alternate image. Buttons don’t display images by default.

See Also

alternateMnemonic

Returns the character in the alternate title (the title displayed on the receiver when it’s in its alternate state) that’s marked as the “keyboard mnemonic.”

public String alternateMnemonic()

Discussion

Mnemonics are not supported in Mac OS X.

See Also

alternateMnemonicLocation

Returns an unsigned integer indicating the character in the alternate title (the title displayed on the receiver when it’s in its alternate state) that’s marked as the “keyboard mnemonic.”

public int alternateMnemonicLocation()

Discussion

If the alternate title doesn’t have a keyboard mnemonic, NSArray.NotFound is returned. Mnemonics are not supported in Mac OS X.

See Also

alternateTitle

Returns the string that appears on the receiver when it’s in its alternate state, or the empty string if the receiver doesn’t display an alternate title.

public String alternateTitle()

Discussion

Note that some button types don’t display an alternate title. By default, a button’s alternate title is “Button.”

See Also

attributedAlternateTitle

Returns the string that appears on the receiver when it’s in its alternate state as an NSAttributedString, or an empty attributed string if the receiver doesn’t display an alternate title.

public NSAttributedString attributedAlternateTitle()

Discussion

Note that some button types don’t display an alternate title. By default, a button’s alternate title is “Button.”

See Also

attributedTitle

Returns the string that appears on the receiver when it’s in its normal state as an NSAttributedString, or an empty attributed string if the receiver doesn’t display a title.

public NSAttributedString attributedTitle()

Discussion

A button’s title is always displayed if the button doesn’t use its alternate contents for highlighting or displaying the alternate state. By default, a button’s title is “Button.”

See Also

backgroundColor

Returns the background color of the button.

public NSColor backgroundColor()

Discussion

The background color is used only when drawing borderless buttons.

Availability
See Also

bezelStyle

Returns the appearance of the receiver’s border.

public int bezelStyle()

Discussion

See “Constants” for the list of the possible values.

See Also

drawBezel

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

public void drawBezel(NSRect frame, NSView controlView)

Discussion

This method is called automatically when the button is redrawn; you should not call it directly. The frame parameter contains the bounding rectangle of the button. The controlView parameter contains the control being drawn.

Availability
See Also

drawImage

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

public void drawImage(NSImage image, NSRect frame, NSView controlView)

Discussion

This method is called automatically when the button is redrawn; you should not call it directly. The frame parameter contains the bounding rectangle of the button. The controlView parameter contains the control being drawn.

You specify the primary and alternate images for the button using Interface Builder.

Availability
See Also

drawTitle

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

public NSRect drawTitle(NSAttributedString title, NSRect frame, NSView controlView)

Discussion

This method is called automatically when the button is redrawn; you should not call it directly. The controlView parameter contains the control being drawn.

Availability
See Also

gradientType

Returns the gradient of the receiver’s border.

public int gradientType()

Discussion

See “Constants” for the list of the possible values.

See Also

highlightsBy

Returns the logical OR of flags that indicate the way the receiver highlights when it receives a mouse-down event.

public int highlightsBy()

Discussion

See NSCell’s “Constants” section for the list of flags.

See Also

imageDimsWhenDisabled

Returns whether the receiver’s image and text appear “dim” when the receiver is disabled.

public boolean imageDimsWhenDisabled()

Discussion

By default, all button types except SwitchButton and RadioButton do dim when disabled. When SwitchButtons and RadioButtons are disabled, only the associated text dims.

See Also

imagePosition

Returns the position of the receiver’s image relative to its title.

public int imagePosition()

Discussion

The return value is one of the image positions described in NSCell’s “Constants” section.

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

isOpaque

Returns true if the receiver draws over every pixel in its frame, false if not.

public boolean isOpaque()

Discussion

A button cell is opaque only if it isn’t transparent and if it has a border.

See Also

isTransparent

Returns true if the receiver is transparent, false otherwise.

public boolean isTransparent()

Discussion

A transparent button never draws itself, but it receives mouse-down events and tracks the mouse properly.

See Also

keyEquivalent

Returns the key-equivalent character of the receiver, or the empty string if one hasn’t been defined.

public String keyEquivalent()

Discussion

Buttons don’t have a default key equivalent.

See Also

keyEquivalentFont

Returns the font used to draw the key equivalent, or null if the receiver doesn’t have a key equivalent.

public NSFont keyEquivalentFont()

Discussion

The default font is the same as that used to draw the title.

See Also

keyEquivalentModifierMask

Returns the mask indicating the modifier keys that are applied to the receiver’s key equivalent.

public int keyEquivalentModifierMask()

Discussion

The only mask bits relevant in button key-equivalent modifier masks are NSEvent.ControlKeyMask, NSEvent.AlternateKeyMask, and NSEvent.CommandKeyMask bits.

See Also

mouseEntered

Draws the receiver’s border.

public void mouseEntered(NSEvent event)

Discussion

The event argument is the event object generated by the mouse movement. This method is called only when the cursor moves onto the receiver and showsBorderOnlyWhileMouseInside returns true.

mouseExited

Erases the receiver’s border.

public void mouseExited(NSEvent event)

Discussion

The event argument is the event object generated by the mouse movement. This method is called only when the cursor moves off the receiver and showsBorderOnlyWhileMouseInside returns true.

performClick

Simulates the user clicking the receiver with the cursor.

public void performClick(Object sender)

Discussion

This method essentially highlights the button, sends the button’s action message to the target object, and then unhighlights the button. If an exception is thrown while the target object is processing the action message, the button is unhighlighted before the exception is propagated out of performClick.

setAlternateImage

Sets the image that appears on the receiver when it’s in its alternate state to image and, if necessary, redraws the contents of the receiver.

public void setAlternateImage(NSImage image)

Discussion

Note that some button types don’t display an alternate image.

See Also

setAlternateMnemonicLocation

Sets the character in the alternate title (the title displayed on the receiver when it’s in its alternate state) that’s to be marked as the “keyboard mnemonic.”

public void setAlternateMnemonicLocation(int location)

Discussion

If you don’t want the alternate title to have a keyboard mnemonic, specify a location of NSArray.NotFound. Mnemonics are not supported in Mac OS X.

The setAlternateMnemonicLocation method doesn’t cause the button cell to be redisplayed.

See Also

setAlternateTitle

Sets the title that’s displayed on the receiver when it’s in its alternate state to aString.

public void setAlternateTitle(String aString)

Discussion

Note that some button types don’t display an alternate title.

See Also

setAlternateTitleWithMnemonic

Sets the title that is displayed on the receiver when it’s in its alternate state to aString, taking into account the fact that an embedded “&” character is not a literal but instead marks the alternate state’s “keyboard mnemonic.”

public void setAlternateTitleWithMnemonic(String aString)

Discussion

Mnemonics are not supported in Mac OS X.

If necessary, setAlternateTitleWithMnemonic redraws the button cell. Note that some button types don’t display an alternate title.

See Also

setAttributedAlternateTitle

Sets the string that appears on the receiver when it’s in its alternate state to the attributed string aString.

public void setAttributedAlternateTitle(NSAttributedString aString)

Discussion

Note that some button types don’t display an alternate title.

See Also

setAttributedTitle

Sets the string that appears on the receiver when it’s in its normal state to the attributed string aString and redraws the button.

public void setAttributedTitle(NSAttributedString aString)

Discussion

The title is always shown on buttons that don’t use their alternate contents when highlighting or displaying their alternate state.

See Also

setBackgroundColor

Sets the background color of the button.

public void setBackgroundColor(NSColor)

Discussion

The background color is used only when drawing borderless buttons.

Availability
See Also

setBezelStyle

Sets the appearance of the border, if the receiver has one.

public void setBezelStyle(int bezelStyle)

Discussion

bezelStyle must be one of the values specified in “Constants.”

A button uses shading to look like it’s sticking out or pushed in. You can set the shading with setGradientType.

If the receiver is not bordered, the bezel style is ignored.

See Also

setButtonType

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

public void setButtonType(int aType)

Discussion

setButtonType redisplays the receiver before returning.

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.

The aType argument can be one of the constants defined in “Constants.”

See Also

setFont

Sets the font used to display the title and alternate title to the font specified by fontObj.

public void setFont(NSFont fontObj)

Discussion

Does nothing if the receiver has no title or alternate title.

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

setGradientType

Sets the type of gradient to use for the receiver.

public void setGradientType(int gradientType)

Discussion

If the receiver has no border, this method has no effect on its appearance. A concave gradient is darkest in the top-left corner; a convex gradient is darkest in the bottom-right corner. Weak versus strong is how much contrast exists between the colors used in opposite corners.

The gradientType argument can be one of the constants defined in “Constants.”

See Also

setHighlightsBy

Sets the way the receiver highlights itself while pressed.

public void setHighlightsBy(int aType)

Discussion

aType can be the logical OR of one or more of the cell masks described in NSCell’s “Constants” section.

If both NSCell.ChangeGrayCellMask and NSCell.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, NSCell.ChangeGrayCellMask is used. If the image does have alpha data, NSCell.ChangeBackgroundCellMask is used; this arrangement allows the color swap of the background to show through the image’s transparent pixels.

See Also

setImageDimsWhenDisabled

Sets whether the receiver’s image appears “dim” when the button cell is disabled, depending on the Boolean value flag.

public void setImageDimsWhenDisabled(boolean flag)

Discussion

By default, all button types except SwitchButton and RadioButton do dim when disabled. When SwitchButtons and RadioButtons are disabled, only the associated text 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.

See Also

setImagePosition

Sets the position of the receiver’s image relative to its title.

public void setImagePosition(int aPosition)

Discussion

See NSCell’s “Constants” section for a listing of possible values for aPosition.

See Also

setKeyEquivalent

Sets the key equivalent character of the receiver, specified by aKeyEquivalent, and redraws the receiver’s inside if it displays a key equivalent instead of an image.

public void setKeyEquivalent(String aKeyEquivalent)

Discussion

The key equivalent isn’t displayed if the image position is set to 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

setKeyEquivalentFont

Sets the font used to draw the key equivalent to the font specified by fontObj and redisplays the receiver if necessary.

public void setKeyEquivalentFont(NSFont fontObj)

Discussion

Does nothing if the receiver doesn’t have a key equivalent associated with it. The default font is the same as that used to draw the title.

See Also

setKeyEquivalentFontAndSize

Sets by name and size the font used to draw the key equivalent and redisplays the receiver if necessary.

public void setKeyEquivalentFontAndSize(String fontName, float fontSize)

Discussion

Does nothing if the receiver doesn’t have a key equivalent associated with it. The default font is the same as that used to draw the title.

See Also

setKeyEquivalentModifierMask

Sets the mask indicating the modifier keys to be applied to the receiver’s key equivalent using the value of mask.

public void setKeyEquivalentModifierMask(int mask)

Discussion

The only mask bits relevant in button key-equivalent modifier masks are NSEvent.ControlKeyMask, NSEvent.AlternateKeyMask, and NSEvent.CommandKeyMask bits.

See Also

setPeriodicDelayAndInterval

Sets the message delay and interval for the receiver.

public void setPeriodicDelayAndInterval(float delay, float interval)

Discussion

These two values are used if the receiver is configured (by a setContinuous message) to continuously send the action message to the target object while tracking the mouse. delay is the amount of time (in seconds) that a continuous button will pause before starting to periodically send action messages to the target object. interval is the amount of time (also in seconds) between those messages.

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

setShowsBorderOnlyWhileMouseInside

Sets whether the receiver’s border is displayed only when the cursor is over the button.

public void setShowsBorderOnlyWhileMouseInside(boolean show)

Discussion

If show is true, the border is displayed only when the cursor is within the receiver’s border and the button is active. If show is false, the receiver’s border continues to be displayed when the cursor is outside button’s bounds.

See Also

setShowsStateBy

Sets the way the receiver indicates its alternate state.

public void setShowsStateBy(int aType)

Discussion

aType should be the logical OR of one or more of the cell masks described in NSCell’s “Constants” section.

If both NSCell.ChangeGrayCellMask and NSCell.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, NSCell.ChangeGrayCellMask is used. If the image exists and has alpha data, NSCell.ChangeBackgroundCellMask is used; this arrangement allows the color swap of the background to show through the image’s transparent pixels.

See Also

setSound

Sets the sound that’s played when the user presses the receiver to aSound.

public void setSound(Object aSound)

Discussion

The sound is played during a mouse-down event, such as NSEvent.LeftMouseDown.

See Also

setTitle

Sets the title displayed by the receiver when in its normal state to aString and, if necessary, redraws the receiver’s contents.

public void setTitle(String aString)

Discussion

This title is always shown on buttons that don’t use their alternate contents when highlighting or displaying their alternate state.

See Also

setTitleWithMnemonic

Sets the title displayed on the receiver when it’s in its normal state to aString, taking into account the fact that an embedded “&” character is not a literal but instead marks the normal state’s “keyboard mnemonic.”

public void setTitleWithMnemonic(String aString)

Discussion

If necessary, setTitleWithMnemonic redraws the button cell. This title is always shown on buttons that don’t use their alternate contents when highlighting or displaying their alternate state. Mnemonics are not supported in Mac OS X.

See Also

setTransparent

public void setTransparent(boolean flag)

Discussion

Sets whether the receiver is transparent, depending on the Boolean value flag, and redraws the receiver if necessary. A transparent button tracks the mouse and sends its action, but doesn’t draw. A transparent button is useful for sensitizing an area on the screen so that an action gets sent to a target when the area receives a mouse click.

See Also

showsBorderOnlyWhileMouseInside

Returns true if the receiver’s border is displayed only when the cursor is over the button and the button is active.

public boolean showsBorderOnlyWhileMouseInside()

Discussion

By default, this method returns false.

See Also

showsStateBy

Returns the logical OR of flags that indicate the way the receiver shows its alternate state.

public int showsStateBy()

Discussion

See NSCell’s “Constants” section for the list of flags.

See Also

sound

Returns the sound that’s played when the user presses the button.

public Object sound()

See Also

title

Returns the title displayed on the receiver when it’s in its normal state (this title is always displayed if the button doesn’t use its alternate contents for highlighting or displaying the alternate state).

public String title()

Discussion

Returns the empty string if the button doesn’t display a title. By default, a button’s title is “Button.”

See Also

Constants

These are the bezel styles used by bezelStyle and setBezelStyle:

Constant

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.

DisclosureBezelStyle

A bezel style for use with a disclosure triangle. To create the disclosure triangle, set the button bezel style to DisclosureBezelStyle and the button type to OnOffButton.

Available for Mac OS X v10.3 or later.

ShadowlessSquareBezelStyle

Similar to RegularSquareBezelStyle, but has no shadow so you can abut the cells without overlapping shadows. This style would be used in a tool palette, for example.

CircularBezelStyle

A round button with room for a small icon or a single character. This style has both regular and small variants, but the large variant is available only in gray at this time.

TexturedSquareBezelStyle

A bezel style appropriate for use with textured (that is, metal) windows.

Available for Mac OS X v10.3 and later.

HelpButtonBezelStyle

A round button with a question mark providing the standard help button look.

Available for Mac OS X v10.3 and later.

SmallSquareBezelStyle

A simple square bezel style. Buttons using this style can be scaled to any size.

Available for Mac OS X v10.4 and later.

TexturedRoundedBezelStyle

A textured (metal) bezel style similar in appearance to the Finder’s action (gear) button. The height of this button is fixed. (Available for Mac OS X v10.4 and later.)

These are the button types that can be specified using setButtonType

Button Type

Description

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

After the first click, the button displays its alternate image or title. A second click returns the button to its normal state. This option is called “Toggle” in Interface Builder’s Button Inspector.

SwitchButton

This style is a variant of ToggleButton that has no border. This type of button is available as a separate palette item in Interface Builder.

RadioButton

Similar to SwitchButton. This type of button is available as a separate palette item in Interface Builder.

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.

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.


Next Page > Hide TOC

© 1997, 2007 Apple Inc. All Rights Reserved. (Last updated: 2007-02-01)

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.