Legacy Document
Important: The information in this document is obsolete and should not be used for new development.
NSButton
| Inherits from | |
| Implements | |
| Package | com.apple.cocoa.application |
| Companion guide |
Overview
NSButton is a subclass of NSControl that intercepts mouse-down events and sends an action message to a target object when it’s clicked or pressed.
NSButton uses NSButtonCell to implement its user interface.
NSButton and NSMatrix both provide a control view, which is needed to display an NSButtonCell object. However, while NSMatrix requires you to access the NSButtonCells directly, most of NSButton’s methods are “covers” for identically declared methods in NSButtonCell. (In other words, the implementation of the NSButton method invokes the corresponding NSButtonCell method for you, allowing you to be unconcerned with the NSButtonCell’s existence.) The only NSButtonCell methods that don’t have covers relate to the font used to display the key equivalent and to specific methods for highlighting or showing the NSButton’s state (these last are usually set together with NSButton’s setButtonType method).
Tasks
Constructors
Setting the Button Type
Setting the State
Setting the Repeat Interval
Setting the Titles
-
alternateTitle
-
attributedAlternateTitle
-
attributedTitle
-
setAlternateTitle
-
setAttributedAlternateTitle
-
setAttributedTitle
-
setTitle
-
setTitleWithMnemonic
-
title
Setting the Images
Modifying Graphics Attributes
-
bezelStyle
-
isBordered
-
isTransparent
-
setBordered
-
setBezelStyle
-
setShowsBorderOnlyWhileMouseInside
-
setTransparent
-
showsBorderOnlyWhileMouseInside
Displaying
Setting the Key Equivalent
Handling Events and Action Messages
Playing Sound
Constructors
NSButton
Creates an NSButton with a zero-sized frame rectangle.
public NSButton()
Creates an NSButton with frameRect as its frame rectangle.
public NSButton(NSRect frameRect)
Instance Methods
allowsMixedState
Returns true if the receiver has three states: on, off, and mixed.
public boolean allowsMixedState()
Discussion
Returns false if the receiver has two states: on and off. The default is false.
See Also
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
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
bezelStyle
Returns the appearance of the receiver’s border.
public int bezelStyle()
Discussion
See NSButtonCell’s “Constants” section for the list of possible values.
See Also
highlight
Highlights (or unhighlights) the receiver according to flag.
public void highlight(boolean flag)
Discussion
Highlighting may involve the button appearing “pushed in” to the screen, displaying its alternate title or image, or causing the button to appear to be “lit.” If the current state of the button matches flag, no action is taken.
See Also
image
Returns the image that appears on the receiver when it’s in its normal state, or null if there is no such image.
public NSImage image()
Discussion
This image is always displayed on a button that doesn’t change its contents when highlighting or showing its alternate state. Buttons don’t display images by default.
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
interval
Returns the amount of time (in seconds) between the periodic messages that a continuous button sends after its been pressed for a sufficient time.
public float interval()
Discussion
The default value is taken from a user’s defaults (60 seconds maximum). If the user hasn’t specified a value, it defaults to 0.075 seconds.
See Also
-
isContinuous(NSControl) -
periodicDelay -
setPeriodicDelayAndInterval
isBordered
Returns true if the receiver has a border, false otherwise.
public boolean isBordered()
Discussion
A button’s border isn’t the single line of most other controls’ borders—instead, it’s a raised bezel. By default, buttons are bordered.
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
-
setKeyEquivalent -
performKeyEquivalent -
keyEquivalentFont(NSButtonCell)
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
performKeyEquivalent
public boolean performKeyEquivalent(NSEvent anEvent)
Discussion
If the character in anEvent matches the receiver’s key equivalent, and the modifier flags in anEvent match the key-equivalent modifier mask, performKeyEquivalent simulates the user clicking the button and returning true. Otherwise, performKeyEquivalent does nothing and returns false. performKeyEquivalent also returns false in the event that the receiver is blocked by a modal panel or the button is disabled.
See Also
periodicDelay
Returns the amount of time (in seconds) that a continuous button will pause before starting to periodically send action messages to the target object.
public float periodicDelay()
Discussion
The default value is taken from a user’s defaults (60 seconds maximum). If the user hasn’t specified a value, it defaults to 0.4 seconds.
See Also
-
interval -
setPeriodicDelayAndInterval -
isContinuous(NSControl)
setAllowsMixedState
public void setAllowsMixedState(boolean flag)
Discussion
If flag is true, the receiver has three states: on, off, and mixed. If flag is false, the receiver has two states: on and off.
See Also
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 button.
public void setAlternateImage(NSImage image)
Discussion
Note that some button types don’t display an alternate image.
See Also
setAlternateTitle
Sets the string that appears 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
-
alternateTitle -
setTitle -
setTitleWithMnemonic -
setButtonType -
setFont(NSButtonCell)
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
-
attributedAlternateTitle -
setAttributedTitle -
setButtonType -
setFont(NSButtonCell)
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
-
attributedTitle -
setAttributedAlternateTitle -
setButtonType -
setFont(NSButtonCell)
setBezelStyle
Sets the appearance of the border, if the receiver has one.
public void setBezelStyle(int bezelStyle)
Discussion
bezelStyle must be one of the bezel styles described in NSButtonCell’s “Constants” section.
The button uses shading to look like it’s sticking out or pushed in. You can set the shading with NSButtonCell’s setGradientType method.
If the button is not bordered, the bezel style is ignored.
See Also
setBordered
Sets whether the receiver has a bezeled border.
public void setBordered(boolean flag)
Discussion
If flag is true, the receiver displays a border; if flag is false, the receiver doesn’t display a border. A button’s border is not the single line of most other controls’ borders—instead, it’s a raised bezel. This method redraws the button if setBordered causes the bordered state to change.
See Also
setButtonType
Sets how the receiver button highlights while pressed and how it shows its state.
public void setButtonType(int aType)
Discussion
setButtonType redisplays the button 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 NSButtonCell’s setHighlightsBy and setShowsStateBy methods.
The aType argument can be one of eight constants described in “Constants.”
See Also
-
setAlternateImage -
setImage -
setButtonType(NSButtonCell)
setImage
Sets the receiver’s image to anImage and redraws the button.
public void setImage(NSImage anImage)
Discussion
A button’s image is displayed when the button is in its normal state, or all the time for a button that doesn’t change its contents when highlighting or displaying its alternate state.
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 to the character represented by charCode and redraws the button’s interior if it displays a key equivalent instead of an image.
public void setKeyEquivalent(String charCode)
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
-
keyEquivalent -
performKeyEquivalent -
setAlternateImage -
setImage -
setImagePosition -
setKeyEquivalentFont(NSButtonCell)
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
setNextState
Sets the receiver to its next state.
public void setNextState()
Discussion
If the button has three states, it cycles through them in this order: on, off, mixed, on, and so forth. If the button has two states, it toggles between them.
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 button 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 is ignored, and 60.0 seconds is used.
See Also
-
setContinuous(NSControl)
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 button’s border and the button is active. If show is false, the button’s border continues to be displayed when the cursor is outside button’s bounds.
If isBordered returns false, the border is never displayed, regardless of what this method returns.
See Also
setSound
Sets the sound that’s played when the user presses the button to aSound.
public void setSound(Object aSound)
Discussion
The sound is played during a mouse-down event, such as NSEvent.LeftMouseDown.
See Also
setState
Sets the cell’s state to value, which can be NSCell.OnState, NSCell.OffState, or NSCell.MixedState.
public void setState(int value)
Discussion
If necessary, this method also redraws the receiver.
The cell can have two or three states. If it has two, value can be NSCell.OffState (the normal or unpressed state) and NSCell.OnState (the alternate or pressed state). If it has three, value can be NSCell.OnState (the feature is in effect everywhere), NSCell.OffState (the feature is in effect nowhere), or NSCell.MixedState (the feature is in effect somewhere). Note that if the cell has only two states and value is NSCell.MixedState, this method sets the cell’s state to NSCell.OnState.
Although using the enumerated constants is preferred, value can also be an integer. If the cell has two states, 0 is treated as NSCell.OffState, and a nonzero value is treated as NSCell.OnState. If the cell has three states, 0 is treated as NSCell.OffState; a negative value, as NSCell.MixedState; and a positive value, as NSCell.OnState.
To check whether the button uses the mixed state, use the method allowsMixedState.
See Also
setTitle
Sets the title displayed by the receiver when in its normal state to aString and, if necessary, redraws the button’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
-
title -
setAlternateTitle -
setButtonType -
setTitleWithMnemonic -
setFont(NSButtonCell)
setTitleWithMnemonic
Sets the title of a button with a character denoting an access key, as specified by aString.
public void setTitleWithMnemonic(String aString)
Discussion
Mnemonics are not supported in Mac OS X.
See Also
-
title -
setAlternateTitle -
setButtonType -
setTitle -
setFont(NSButtonCell)
setTransparent
Sets whether the receiver is transparent, depending on the Boolean value flag, and redraws the receiver if necessary.
public void setTransparent(boolean flag)
Discussion
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.
If isBordered returns false, the border is never displayed, regardless of what this method returns.
See Also
sound
Returns the sound that’s played when the user presses the button.
public Object sound()
See Also
state
Returns the receiver’s state.
public int state()
Discussion
The button can have two or three states. If it has two, it returns either NSCell.OffState (the normal or unpressed state) or NSCell.OnState (the alternate or pressed state). If it has three, it returns NSCell.OnState (the feature is in effect everywhere), NSCell.OffState (the feature is in effect nowhere), or NSCell.MixedState (the feature is in effect somewhere).
To check whether the button uses the mixed state, use the method allowsMixedState.
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
NSButton defines a number of constants to indicate, using setButtonType, how a button highlights while pressed and how it shows its state:
Button Type |
Description |
|---|---|
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 type is the default button type. |
|
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. |
|
|
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. |
|
The first click both highlights the button and causes it 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. |
|
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. |
|
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. |
|
This type is a variant of |
|
Similar to |
© 1997, 2007 Apple Inc. All Rights Reserved. (Last updated: 2007-02-01)