Inherits from: NSControl : NSView : NSResponder : NSObject
Conforms to: NSCoding
(from NSResponder)
NSObject (from NSObject)
Declared in: AppKit/NSButton.h
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.
The NSButton can send its action continuously and display highlighting in several different ways. What's more, an NSButton can have a key equivalent that's eligible for triggering whenever the NSButton's NSPanel or NSWindow is the key window.
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).
By virtue of its NSButtonCell, NSButton is an NSControl and displays its state depending on the configuration of the NSButtonCell. The NSButton can have two or three states. If it has two, they are on and off. If it has three, they are on, off, and mixed. A mixed state is useful for a checkbox or radio button that reflects the status of a feature. For example, suppose you have a checkbox that makes the selected text bold. If all the selected text is bold, it's on. If none of the selected text is bold, it's off. If the text has a combination of bold and plain text, it's mixed. Now suppose you click the checkbox. If you turn it on, all the text becomes bold. If you turn it off, all the text becomes plain. If you select the mixed state, the text remains as it is.
By default, a button has two states. You can allow the third state with the method setAllowsMixedState:. To set the button's state directly, use setState:. To cycle through all available states, use setNextState. Note that the state is used as the value, so NSControl methods like setIntValue: actually set the state.
Override the designated initializer (NSView's initWithFrame: method) if you create a subclass of NSButton that performs its own initialization. If you want to use a custom NSButtonCell subclass with your subclass of NSButton, you have to override the setCellClass: method, as described in "Creating New NSControls" in the NSControl class specification.
See the NSButtonCell class specification for more on NSButton's behavior.
- Setting the button type
- - setButtonType:
- Setting the state
- - allowsMixedState
- - setAllowsMixedState:
- - setNextState
- - setState:
- - state
- Setting the repeat interval
- - getPeriodicDelay:interval:
- - setPeriodicDelay:interval:
- Setting the titles
- - alternateTitle
- - attributedAlternateTitle
- - attributedTitle
- - setAlternateTitle:
- - setAttributedAlternateTitle:
- - setAttributedTitle:
- - setTitle:
- - setTitleWithMnemonic:
- - title
- Setting the images
- - alternateImage
- - image
- - imagePosition
- - setAlternateImage:
- - setImage:
- - setImagePosition:
- Modifying graphic attributes
- - bezelStyle
- - isBordered
- - isTransparent
- - setBordered:
- - setBezelStyle:
- - setShowsBorderOnlyWhileMouseInside:
- - setTransparent:
- - showsBorderOnlyWhileMouseInside
- Displaying
- - highlight:
- Setting the key equivalent
- - keyEquivalent
- - keyEquivalentModifierMask
- - setKeyEquivalent:
- - setKeyEquivalentModifierMask:
- Handling events and action messages
- - performClick:
- - performKeyEquivalent:
- Playing sound
- - setSound:
- - sound
- (BOOL)allowsMixedState
YES
if
the button has three states: on, off, and mixed. Returns NO
if
the button has two states: on and off. See Also: - setAllowsMixedState:, - setNextState
- (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: - image, - imagePosition, - keyEquivalent, - setButtonType:
- (NSString *)alternateTitle
See Also: - attributedAlternateTitle, - setButtonType:, - title
- (NSAttributedString *)attributedAlternateTitle
See Also: - attributedTitle, - setButtonType:
- (NSAttributedString *)attributedTitle
See Also: - attributedAlternateTitle, - setButtonType:
- (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(NSControl)
- (void)highlight:(BOOL)flag
See Also: - setButtonType:
nil
if
there is no such image. 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: - alternateImage, - setButtonType:
- (NSCellImagePosition)imagePosition
Return Value | Meaning |
NSNoImage |
The button doesn't display an image (this is the default) |
NSImageOnly |
The button displays an image, but not a title |
NSImageLeft |
The image is to the left of the title |
NSImageRight |
The image is to the right of the title |
NSImageBelow |
The image is below the title |
NSImageAbove |
The image is above the title |
NSImageOverlaps |
The image overlaps the title |
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:, - setImage:, - setTitle:
- (BOOL)isBordered
YES
if
the button has a border, NO
otherwise. 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.- (BOOL)isTransparent
YES
if
the button is transparent, NO
otherwise. A
transparent button never draws itself, but it receives mouse-down
events and tracks the mouse properly.- (NSString *)keyEquivalent
See Also: - performKeyEquivalent:, - keyEquivalentFont(NSButtonCell)
- (unsigned int)keyEquivalentModifierMask
See Also: - keyEquivalent
- (void)performClick:(id)sender
See Also: - performKeyEquivalent:
- (BOOL)performKeyEquivalent:(NSEvent
*)anEvent
YES
. Otherwise, performKeyEquivalent: does
nothing and returns NO
. performKeyEquivalent: also
returns NO
in the event
that the button is blocked by a modal panel or the button is disabled.See Also: - keyEquivalentModifierMask
- (void)setAllowsMixedState:(BOOL)flag
YES
,
the button has three states: on, off, and mixed. If flag is NO
,
the button has two states: on and off. See Also: - allowsMixedState, - setNextState
- (void)setAlternateImage:(NSImage
*)image
See Also: - setButtonType:, - setImage:
- (void)setAlternateTitle:(NSString
*)aString
See Also: - setTitle:, - setTitleWithMnemonic:, - setButtonType:, - setFont:(NSButtonCell)
- (void)setAttributedAlternateTitle:(NSAttributedString
*)aString
See Also: - setAttributedTitle:, - setButtonType:, - setFont:(NSButtonCell)
- (void)setAttributedTitle:(NSAttributedString
*)aString
See Also: - setAttributedAlternateTitle:, - setButtonType:, - setFont:(NSButtonCell)
- (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 NSButtonCell's setGradientType: method.
If the button is not bordered, the bezel style is ignored.
See Also: - bezelStyle
- (void)setBordered:(BOOL)flag
YES
,
the button displays a border; if flag is NO
,
the button 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.- (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 NSButtonCell's 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 or 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:, - setButtonType:(NSButtonCell)
- (void)setImage:(NSImage
*)image
See Also: - setImagePosition:, - setAlternateImage:, - setButtonType:
- (void)setImagePosition:(NSCellImagePosition)aPosition
- (void)setKeyEquivalent:(NSString
*)charCode
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: - performKeyEquivalent:, - setAlternateImage:, - setImage:, - setImagePosition:, - setKeyEquivalentFont:(NSButtonCell)
- (void)setKeyEquivalentModifierMask:(unsigned
int)mask
See Also: - setKeyEquivalent:
- (void)setNextState
See Also: - allowsMixedState, - setAllowsMixedState:
- (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 is ignored and 60.0 seconds is used.
See Also: - setContinuous:(NSControl)
- (void) setShowsBorderOnlyWhileMouseInside:(BOOL)show
YES
, the border is displayed
only when the mouse is within the button'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.If isBordered returns NO
,
the border is never displayed, regardless of what this method returns.
See Also: - showsBorderOnlyWhileMouseInside
- (void)setSound:(NSSound
*)aSound
See Also: - sound
- (void)setState:(int)value
The cell can have two or three states. If it has two, value can be NSOffState (the normal or unpressed state) and NSOnState (the alternate or pressed state). If it has three, value can be NSOnState (the feature is in effect everywhere), NSOffState (the feature is in effect nowhere), or NSMixedState (the feature is in effect somewhere). Note that if the cell has only two states and value is NSMixedState, this method sets the cell's state to NSOnState.
Although using the enumerated constants is preferred, value can also be an integer. If the cell has two states, zero is treated as NSOffState, and a non-zero value is treated as NSOnState. If the cell has three states, zero is treated as NSOffState; a negative value, as NSMixedState; and a positive value, as NSOnState.
To check whether the button uses the mixed state, use the method allowsMixedState.
- (void)setTitle:(NSString
*)aString
See Also: - setAlternateTitle:, - setButtonType:, - setTitleWithMnemonic:, - setFont:(NSButtonCell)
- (void)setTitleWithMnemonic:(NSString
*)aString
[aButton setTitleWithMnemonic:NSLocalizedString(@"Re&ceive")];
See Also: - setAlternateTitle:, - setButtonType:, - setTitle:, - setFont:(NSButtonCell)
- (void)setTransparent:(BOOL)flag
- (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
.If isBordered returns NO
,
the border is never displayed, regardless of what this method returns.
See Also: - setShowsBorderOnlyWhileMouseInside:
- (NSSound *)sound
See Also: - setSound:
- (int)state
To check whether the button uses the mixed state, use the method allowsMixedState.
- (NSString *)title
See Also: - alternateTitle, - setButtonType:, - setTitle:, - setTitleWithMnemonic: