NSButton Class

NSButton Class Reference
2007-04-01
Apple Inc.
2007 Apple Inc.
All rights reserved.
No part of this publication may be
reproduced, stored in a retrieval system, or
transmitted, in any form or by any means,
mechanical, electronic, photocopying,
recording, or otherwise, without prior
written permission of Apple Inc., with the
following exceptions: Any person is hereby
authorized to store documentation on a
single computer for personal use only and
to print copies of documentation for
personal use provided that the
documentation contains Apples copyright
notice.
The Apple logo is a trademark of Apple Inc.
Use of the keyboard Apple logo
(Option-Shift-K) for commercial purposes
without the prior written consent of Apple
may constitute trademark infringement and
unfair competition in violation of federal
and state laws.
No licenses, express or implied, are granted
with respect to any of the technology
described in this document. Apple retains
all intellectual property rights associated
with the technology described in this
document. This document is intended to
assist application developers to develop
applications only for Apple-labeled or
Apple-licensed computers.
Every effort has been made to ensure that
the information in this document is
accurate. Apple is not responsible for
typographical errors.
Apple Inc.
1 Infinite Loop
Cupertino, CA 95014
408-996-1010
Apple, the Apple logo, Cocoa, Mac, and
Mac OS are trademarks of Apple Inc.,
registered in the United States and other
countries.
Simultaneously published in the United
States and Canada.
Even though Apple has reviewed this document,
APPLE MAKES NO WARRANTY OR
REPRESENTATION, EITHER EXPRESS OR
IMPLIED, WITH RESPECT TO THIS
DOCUMENT, ITS QUALITY, ACCURACY,
MERCHANTABILITY, OR FITNESS FOR A
PARTICULAR PURPOSE. AS A RESULT, THIS
DOCUMENT IS PROVIDED AS IS, AND
YOU, THE READER, ARE ASSUMING THE

ENTIRE RISK AS TO ITS QUALITY AND
ACCURACY.
IN NO EVENT WILL APPLE BE LIABLE FOR
DIRECT, INDIRECT, SPECIAL, INCIDENTAL,
OR CONSEQUENTIAL DAMAGES
RESULTING FROM ANY DEFECT OR
INACCURACY IN THIS DOCUMENT, even if
advised of the possibility of such damages.
THE WARRANTY AND REMEDIES SET
FORTH ABOVE ARE EXCLUSIVE AND IN
LIEU OF ALL OTHERS, ORAL OR WRITTEN,
EXPRESS OR IMPLIED. No Apple dealer, agent,
or employee is authorized to make any
modification, extension, or addition to this
warranty.
Some states do not allow the exclusion or
limitation of implied warranties or liability for
incidental or consequential damages, so the
above limitation or exclusion may not apply to
you. This warranty gives you specific legal
rights, and you may also have other rights which
vary from state to state.
Contents
NSButton Class Reference 5
Overview 5
Tasks 6
Configuring Buttons 6
Configuring Button Images 6
Managing Button State 7
Accessing Key Equivalents 8
Handling Keyboard Events 8
Instance Methods 8
allowsMixedState 8
alternateImage 8
alternateTitle 9
attributedAlternateTitle 9
attributedTitle 10
bezelStyle 10
getPeriodicDelay:interval: 11
highlight: 11
image 11
imagePosition 12
isBordered 12
isTransparent 13
keyEquivalent 13
keyEquivalentModifierMask 13
performKeyEquivalent: 14
setAllowsMixedState: 14
setAlternateImage: 15
setAlternateTitle: 15
setAttributedAlternateTitle: 16
setAttributedTitle: 16
setBezelStyle: 17
setBordered: 17
setButtonType: 18
setImage: 18
setImagePosition: 19
setKeyEquivalent: 19
setKeyEquivalentModifierMask: 20
setNextState 20
3
2007-04-01 | 2007 Apple Inc. All Rights Reserved.
C O N T E N T S
setPeriodicDelay:interval: 20
setShowsBorderOnlyWhileMouseInside: 21
setSound: 21
setState: 22
setTitle: 23
setTitleWithMnemonic: 23
setTransparent: 23
showsBorderOnlyWhileMouseInside 24
sound 24
state 25
title 25
Document Revision History 27

Index 29
4
Inherits from:
NSControl : NSView : NSResponder : NSObject
Conforms to:
NSCoding (NSResponder)
NSObject (NSObject)
Framework
/System/Library/Frameworks/AppKit.framework
Availability:
Available in Mac OS X v10.0 and later.
Companion guide:
Button Programming Topics for Cocoa
Declared in:
NSButton.h
Overview
The NSButton class is a subclass of NSControl that intercepts mouse-down events and sends an action
message to a target object when its clicked or pressed.
The NSButton class 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 NSButtonCell objects directly, most of
the NSButton class' 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 existence of the NSButtonCell.) The only
NSButtonCell methods that dont have covers relate to the font used to display the key equivalent
and to specific methods for highlighting or showing the state of the NSButton (these last are usually
set together with the NSButton setButtonType: (page 18) method).
Overview
Tasks
Configuring Buttons
setButtonType: (page 18)
Sets how the receiver button highlights while pressed and how it shows its state.
getPeriodicDelay:interval: (page 11)
Returns by reference the delay and interval periods for a continuous button.
setPeriodicDelay:interval: (page 20)
Sets the message delay and interval periods for a continuous button.
alternateTitle (page 9)
Returns the title that the button displays when its in its alternate state.
setAlternateTitle: (page 15)
Sets the title that appears on the button when its in its alternate state.
attributedTitle (page 10)
Returns the title that the button displays in its normal state as an attributed string.
setAttributedTitle: (page 16)
Sets the string that appears on the button when its in its normal state to the given attributed
string and redraws the button.
attributedAlternateTitle (page 9)
Returns the title that the button displays when its in its alternate state as an attributed string.
setAttributedAlternateTitle: (page 16)
Sets the title that appears on the button when its in its alternate state to the given attributed
string.
title (page 25)
Returns the title displayed on the button when its in its normal state.
setTitle: (page 23)
Sets the title displayed by the receiver when in its normal state and, if necessary, redraws the
buttons contents.
setTitleWithMnemonic: (page 23)
Sets the title of a button with a character denoting an access key.

setSound: (page 21)
Sets the sound played when the user presses the button.
sound (page 24)
Returns the sound thats played when the user presses the button.
Configuring Button Images

image (page 11)
Returns the image that appears on the receiver when its in its normal state.
setImage: (page 18)
Sets the receivers image and redraws the button.
Tasks
alternateImage (page 8)
Returns the image that appears on the button when its in its alternate state.
setAlternateImage: (page 15)
Sets the image displayed by the button when its in its alternate state and, if necessary, redraws
the contents of the button.
imagePosition (page 12)
Returns the position of the receivers image relative to its title.

setImagePosition: (page 19)
Sets the position of the button's image relative to its title.

isBordered (page 12)
Returns a Boolean value indicating whether the button has a border.

setBordered: (page 17)
Sets whether the receiver has a bezeled border.

isTransparent (page 13)
Returns a Boolean value indicating whether the button is transparent.

setTransparent: (page 23)
Sets whether the receiver is transparent and redraws the receiver if necessary.
bezelStyle (page 10)
Returns the appearance of the receivers border.

setBezelStyle: (page 17)
Sets the appearance of the border, if the receiver has one.

showsBorderOnlyWhileMouseInside (page 24)
Returns a Boolean value indicating whether the button displays its border only when the cursor
is over it.
setShowsBorderOnlyWhileMouseInside: (page 21)
Sets whether the receivers border is displayed only when the cursor is over the button.
Managing Button State

allowsMixedState (page 8)
Returns a Boolean value indicating whether the button allows a mixed state.
setAllowsMixedState: (page 14)
Sets whether the button allows a mixed state.

state (page 25)
Returns the receivers state.

setState: (page 22)
Sets the cells state to the specified value.

setNextState (page 20)
Sets the receiver to its next state.

highlight: (page 11)
Highlights (or unhighlights) the receiver.
Tasks
Accessing Key Equivalents

keyEquivalent (page 13)
Returns the key-equivalent character of the receiver.

setKeyEquivalent: (page 19)
Sets the key equivalent character of the receiver to the given character.
keyEquivalentModifierMask (page 13)
Returns the mask specifying the modifier keys for the receivers key equivalent.
setKeyEquivalentModifierMask: (page 20)
Sets the mask indicating the modifier keys used by the receivers key equivalent.
Handling Keyboard Events

performKeyEquivalent: (page 14)
Checks the button's key equivalent against the specified event and, if they match, simulates
the button being clicked.
Instance Methods
allowsMixedState
Returns a Boolean value indicating whether the button allows a mixed state.
- (BOOL)allowsMixedState
Return Value
YES if the receiver has three states: on, off, and mixed. NO if the receiver has two states: on and off.
The default is NO.
Availability

See Also
Declared In
NSButton.h
alternateImage
Returns the image that appears on the button when its in its alternate state.
- (NSImage *)alternateImage
Instance Methods
Return Value
The image displayed by the button when it's in its alternate state, or nil if there is no alternate image.
Note that some button types dont display an alternate image. Buttons dont display images by default.
Availability

See Also
image (page 11)
Declared In
NSButton.h
alternateTitle
Returns the title that the button displays when its in its alternate state.
- (NSString *)alternateTitle
Return Value
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. By default, a buttons alternate title is Button.
Availability

See Also
title (page 25)
Declared In
NSButton.h
attributedAlternateTitle
Returns the title that the button displays when its in its alternate state as an attributed string.
- (NSAttributedString *)attributedAlternateTitle
Return Value
The string that appears on the receiver when it's in its alternate state, as an NSAttributedString, or
the empty string if the receiver doesn't display an alternate title. By default, a buttons alternate title
is Button.
Availability
Instance Methods
See Also
Declared In
NSButton.h
attributedTitle
Returns the title that the button displays in its normal state as an attributed string.
- (NSAttributedString *)attributedTitle
Return Value
The string that appears on the receiver when its in its normal state as an NSAttributedString, or
an empty attributed string if the receiver doesnt display a title.
A buttons title is always displayed if the button doesnt use its alternate contents for highlighting or
displaying the alternate state. By default, a buttons title is Button.
Availability

See Also
Declared In
NSButton.h
bezelStyle
Returns the appearance of the receivers border.
- (NSBezelStyle)bezelStyle
Return Value
The bezel style of the button. See the Constants section of NSButtonCell for the list of possible
values.
Availability

See Also
setBezelStyle: (page 17)
Declared In
NSButton.h
10
Instance Methods
getPeriodicDelay:interval:
Returns by reference the delay and interval periods for a continuous button.
- (void)getPeriodicDelay:(float *)delay interval:(float *)interval
Parameters
delay
On return, the amount of time (in seconds) the button will pause before starting to periodically
send action messages to the target object. The default delay is taken from a user's default (60
seconds maximum). If the user hasnt specified a default value, delay defaults to 0.4 seconds,
interval
On return, the amount of time (in seconds) between each action message that is sent. The
default interval is taken from a user's default (60 seconds maximum). If the user hasnt specified
a default value, interval defaults to 0.075 seconds.
Availability

See Also
isContinuous (NSControl)
Declared In
NSButton.h
highlight:
Highlights (or unhighlights) the receiver.
- (void)highlight:(BOOL)flag
Parameters
flag
YES to highlight the button; NO to unhighlight the button. If the current state of the button
matches flag, no action is taken.
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.
Availability

See Also
Declared In
NSButton.h
image
Returns the image that appears on the receiver when its in its normal state.
- (NSImage *)image
Instance Methods
11
Return Value
The image displayed by the button when it's in its normal state, or nil if there is no such image. This
image is always displayed on a button that doesnt change its contents when highlighting or showing
its alternate state. Buttons dont display images by default.
Availability

See Also
setImage: (page 18)
Declared In
NSButton.h
imagePosition
Returns the position of the receivers image relative to its title.
- (NSCellImagePosition)imagePosition
Return Value
The position of the button's image. This is one of the image positions described in the Constants
section of NSCell.
Discussion
If the title is above, below, or overlapping the image, or if there is no image, the text is horizontally
centered within the button.
Availability

See Also
setImage: (page 18)
setTitle: (page 23)
Declared In
NSButton.h
isBordered
Returns a Boolean value indicating whether the button has a border.
- (BOOL)isBordered
Return Value
YES if the receiver has a border, NO otherwise. A buttons border isnt the single line of most other
controls bordersinstead, its a raised bezel. By default, buttons are bordered.
12
Instance Methods
Availability

See Also
setBordered: (page 17)
Declared In
NSButton.h
isTransparent
Returns a Boolean value indicating whether the button is transparent.
- (BOOL)isTransparent
Return Value
YES if the receiver is transparent, NO otherwise. A transparent button never draws itself, but it receives
mouse-down events and tracks the mouse properly.

Availability

See Also
setTransparent: (page 23)
Declared In
NSButton.h
keyEquivalent
Returns the key-equivalent character of the receiver.
- (NSString *)keyEquivalent
Return Value
The button's key equivalent, or the empty string if one hasnt been defined. Buttons dont have a
default key equivalent.
Availability

See Also
keyEquivalentFont (NSButtonCell)
Declared In
NSButton.h
keyEquivalentModifierMask
Returns the mask specifying the modifier keys for the receivers key equivalent.
Instance Methods
13
- (NSUInteger)keyEquivalentModifierMask
Return Value
The mask specifying the modifier keys that are applied to the button's key equivalent. Mask bits are
defined in NSEvent.h. The only mask bits relevant in button key-equivalent modifier masks are
NSControlKeyMask, NSAlternateKeyMask, and NSCommandKeyMask.
Availability

See Also
setKeyEquivalentModifierMask: (page 20)
Declared In
NSButton.h
performKeyEquivalent:
Checks the button's key equivalent against the specified event and, if they match, simulates the button
being clicked.
- (BOOL)performKeyEquivalent:(NSEvent *)anEvent
Parameters
anEvent
The event containing the key equivalent.

Return Value
YES if the key equivalent in anEvent matches the button's key equivalent; NO if it does not. This method
also returns NO if he receiver is blocked by a modal panel or the button is disabled.
Discussion
If the character in anEvent matches the receivers key equivalent, and the modifier flags in anEvent
match the key-equivalent modifier mask, performKeyEquivalent: simulates the user clicking the
button and returning YES. Otherwise, performKeyEquivalent: does nothing and returns NO.
Availability

See Also
Declared In
NSButton.h
setAllowsMixedState:
Sets whether the button allows a mixed state.
- (void)setAllowsMixedState:(BOOL)flag
14
Instance Methods
Parameters
flag
YES to indicate that the receiver has three states: on, off, and mixed. If flag is NO, the receiver
has two states: on and off.

Availability

See Also
Declared In
NSButton.h
setAlternateImage:
Sets the image displayed by the button when its in its alternate state and, if necessary, redraws the
contents of the button.
- (void)setAlternateImage:(NSImage *)image
Parameters
image
The image that appears on the receiver when its in its alternate state. Note that some button
types dont display an alternate image.
Availability

See Also
setImage: (page 18)
Declared In
NSButton.h
setAlternateTitle:
Sets the title that appears on the button when its in its alternate state.
- (void)setAlternateTitle:(NSString *)aString
Parameters
aString
The string to set as the button's alternate title. Note that some button types don't display an
alternate title.
Availability
Instance Methods
15
See Also
setTitle: (page 23)
setFont: (NSButtonCell)
Declared In
NSButton.h
setAttributedAlternateTitle:
Sets the title that appears on the button when its in its alternate state to the given attributed string.
- (void)setAttributedAlternateTitle:(NSAttributedString *)aString
Parameters
aString
The attributed string to set as the button's alternate title. Note that some button types don't
display an alternate title.
Availability

See Also
Declared In
NSButton.h
setAttributedTitle:
Sets the string that appears on the button when its in its normal state to the given attributed string
and redraws the button.
- (void)setAttributedTitle:(NSAttributedString *)aString
Parameters
aString
The attributed string to set as the button's title. The title is always shown on buttons that dont
use their alternate contents when highlighting or displaying their alternate state.
Discussion
Availability

See Also
16
Instance Methods

Declared In
NSButton.h
setBezelStyle:
Sets the appearance of the border, if the receiver has one.
- (void)setBezelStyle:(NSBezelStyle)bezelStyle
Parameters
bezelStyle
The bezel style of the button. This must be one of the bezel styles described in the Constants
section of NSButtonCell.
If the button is not bordered, the bezel style is ignored.
Discussion
The button uses shading to look like its sticking out or pushed in. You can set the shading with the
NSButtonCell method setGradientType:.
Availability

See Also
bezelStyle (page 10)
Declared In
NSButton.h
setBordered:
Sets whether the receiver has a bezeled border.
- (void)setBordered:(BOOL)flag
Parameters
flag
YES if the receiver should display a border; NO if it should not. A buttons border is not the
single line of most other controls bordersinstead, its a raised bezel.

Discussion
This method redraws the button if setBordered: causes the bordered state to change.
Availability

See Also
isBordered (page 12)
Instance Methods
17
Declared In
NSButton.h
setButtonType:
Sets how the receiver button highlights while pressed and how it shows its state.
- (void)setButtonType:(NSButtonType)aType
Parameters
aType
A constant specifying the type of the buttonone of the constants described in the Constants
section of NSButtonCell.
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 the NSButtonCell methods setHighlightsBy:
and setShowsStateBy:.
Note that there is no -buttonType method. The set method sets various button properties that together
establish the behavior of the type.
Availability

See Also
setImage: (page 18)
setButtonType: (NSButtonCell)
Declared In
NSButton.h
setImage:
Sets the receivers image and redraws the button.
- (void)setImage:(NSImage *)anImage
Parameters
anImage
The button's image. A buttons image is displayed when the button is in its normal state, or
all the time for a button that doesnt change its contents when highlighting or displaying its
alternate state.
Availability

See Also
image (page 11)
18
Instance Methods

Declared In
NSButton.h
setImagePosition:
Sets the position of the button's image relative to its title.
- (void)setImagePosition:(NSCellImagePosition)aPosition
Parameters
aPosition
A constant specifying the position of the button's image. See the Constants section of NSCell
for a listing of possible values.
Availability

See Also
Declared In
NSButton.h
setKeyEquivalent:
Sets the key equivalent character of the receiver to the given character.
- (void)setKeyEquivalent:(NSString *)charCode
Parameters
charCode
The character to set as the button's key equivalent.

Discussion
This method redraws the buttons interior if it displays a key equivalent instead of an image. The key
equivalent isnt displayed if the image position is set to NSNoImage, NSImageOnly, or NSImageOverlaps;
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 nil, then set the key
equivalent, then set the image position.
Availability

See Also
setImage: (page 18)
Instance Methods
19

setKeyEquivalentFont: (NSButtonCell)
Declared In
NSButton.h
setKeyEquivalentModifierMask:
Sets the mask indicating the modifier keys used by the receivers key equivalent.
- (void)setKeyEquivalentModifierMask:(NSUInteger)mask
Parameters
mask
The mask identifying the modifier keys to be applied to the button's key equivalent.
Mask bits are defined in NSEvent.h. The only mask bits relevant in button key-equivalent
modifier masks are NSControlKeyMask, NSAlternateKeyMask, and NSCommandKeyMask.
Availability

See Also
Declared In
NSButton.h
setNextState
Sets the receiver to its next state.
- (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.
Availability

See Also
Declared In
NSButton.h
setPeriodicDelay:interval:
Sets the message delay and interval periods for a continuous button.
20
Instance Methods
- (void)setPeriodicDelay:(float)delay interval:(float)interval
Parameters
delay
The amount of time (in seconds) that a continuous button will pause before starting to
periodically send action messages to the target object. The maximum allowed value is 60.0
seconds; if a larger value is supplied, it is ignored, and 60.0 seconds is used.
interval
The amount of time (in seconds) between each action message. The maximum value is 60.0
seconds; if a larger value is supplied, it is ignored, and 60.0 seconds is used.
Discussion
The delay and interval 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.
Availability

See Also
setContinuous: (NSControl)
Declared In
NSButton.h
setShowsBorderOnlyWhileMouseInside:
Sets whether the receivers border is displayed only when the cursor is over the button.
- (void)setShowsBorderOnlyWhileMouseInside:(BOOL)show
Parameters
show
YES to display the border only when the cursor is within the buttons border and the button
is active. NO, to continue to display the buttons border when the cursor is outside the buttons
bounds.
Discussion
If isBordered (page 12) returns NO, the border is never displayed, regardless of what this method
returns.
Availability

See Also
showsBorderOnlyWhileMouseInside (page 24)
Declared In
NSButton.h
setSound:
Sets the sound played when the user presses the button.
Instance Methods
21
- (void)setSound:(NSSound *)aSound
Parameters
aSound
The sound that should be played when the user presses the button. The sound is played during
a mouse-down event, such as NSLeftMouseDown.
Availability

See Also
sound (page 24)
Declared In
NSButton.h
setState:
Sets the cells state to the specified value.
- (void)setState:(NSInteger)value
Parameters
value
The state of the button. This can be NSOnState, NSOffState,NSMixedState. See the discussion
for a more detailed explanation.
Discussion
If necessary, this method also redraws the receiver.

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 cells state to NSOnState.
Although using the enumerated constants is preferred, value can also be an integer. If the cell has
two states, 0 is treated as NSOffState, and a nonzero value is treated as NSOnState. If the cell has
three states, 0 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 (page 8).
Availability

See Also
state (page 25)
Declared In
NSButton.h
22
Instance Methods
setTitle:
Sets the title displayed by the receiver when in its normal state and, if necessary, redraws the buttons
contents.
- (void)setTitle:(NSString *)aString
Parameters
aString
The string to set as the button's title. This title is always shown on buttons that dont use their
alternate contents when highlighting or displaying their alternate state.
Availability

See Also
title (page 25)
Declared In
NSButton.h
setTitleWithMnemonic:
Sets the title of a button with a character denoting an access key.
- (void)setTitleWithMnemonic:(NSString *)aString
Discussion
Mnemonics are not supported in Mac OS X.

Availability

See Also
title (page 25)
setTitle: (page 23)
Declared In
NSButton.h
setTransparent:
Sets whether the receiver is transparent and redraws the receiver if necessary.
- (void)setTransparent:(BOOL)flag
Instance Methods
23
Parameters
flag
YES if the button is transparent; otherwise NO.
Discussion
A transparent button tracks the mouse and sends its action, but doesnt 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.
Availability

See Also
isTransparent (page 13)
Declared In
NSButton.h
showsBorderOnlyWhileMouseInside
Returns a Boolean value indicating whether the button displays its border only when the cursor is
over it.
- (BOOL)showsBorderOnlyWhileMouseInside
Return Value
YES if the receivers border is displayed only when the cursor is over the button and the button is
active; NO if the border is displayed all the time.
By default, this method returns NO.

Discussion
If isBordered (page 12) returns NO, the border is never displayed, regardless of what this method
returns.
Availability

See Also
setShowsBorderOnlyWhileMouseInside: (page 21)
Declared In
NSButton.h
sound
Returns the sound thats played when the user presses the button.
- (NSSound *)sound
Return Value
The sound played when the user presses the button.
24
Instance Methods
Availability

See Also
setSound: (page 21)
Declared In
NSButton.h
state
Returns the receivers state.
- (NSInteger)state
Return Value
The button's state. A button can have two or three states. If it has two, this value is either NSOffState
(the normal or unpressed state) or NSOnState (the alternate or pressed state). If it has three, this 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).
Discussion
To check whether the button uses the mixed state, use the method allowsMixedState (page 8).
Availability

See Also
setState: (page 22)
Declared In
NSButton.h
title
Returns the title displayed on the button when its in its normal state.
- (NSString *)title
Return Value
The title displayed on the receiver when its in its normal state or the empty string if the button doesnt
display a title. This title is always displayed if the button doesnt use its alternate contents for
highlighting or displaying the alternate state. By default, a buttons title is Button.
Availability

See Also
setTitle: (page 23)
Instance Methods
25
Declared In
NSButton.h
26
Instance Methods
R E V I S I O N
H I S T O R Y
Document Revision History
This table describes the changes to NSButton Class Reference.

Date
Notes
2007-04-01
Made editorial improvements.
2006-05-23
First publication of this content as a separate document.
27
R E V I S I O N
H I S T O R Y
Document Revision History
28
Index
performKeyEquivalent: instance method 14
allowsMixedState instance method 8

alternateImage instance method 8
alternateTitle instance method 9
attributedAlternateTitle instance method 9
attributedTitle instance method 10
S
setAllowsMixedState: instance method 14
setAlternateImage: instance method 15
setAlternateTitle: instance method 15
setAttributedAlternateTitle: instance method
16
bezelStyle instance method 10
G
getPeriodicDelay:interval: instance method 11
setAttributedTitle: instance method 16

setBezelStyle: instance method 17
setBordered: instance method 17
setButtonType: instance method 18
setImage: instance method 18
setImagePosition: instance method 19
setKeyEquivalent: instance method 19
setKeyEquivalentModifierMask: instance method
20
H
highlight: instance method 11
setNextState instance method 20

setPeriodicDelay:interval: instance method 20
setShowsBorderOnlyWhileMouseInside: instance
method 21
I
image instance method 11
imagePosition instance method 12
isBordered instance method 12
isTransparent instance method 13
setSound: instance method 21

setState: instance method 22
setTitle: instance method 23
setTitleWithMnemonic: instance method 23
setTransparent: instance method 23
showsBorderOnlyWhileMouseInside instance
method 24
sound instance method 24
state instance method 25
K
keyEquivalent instance method 13
keyEquivalentModifierMask instance method 13
T
title instance method 25
29

NSButton Class

Uploaded by

NSButton Class

Uploaded by

NSButton Class Reference

YOU, THE READER, ARE ASSUMING THE

Document Revision History 27

NSButton Class Reference

NSControl : NSView : NSResponder : NSObject

Available in Mac OS X v10.0 and later.

Button Programming Topics for Cocoa

NSButton Class Reference

Sets the title of a button with a character denoting an access key.

Configuring Button Images

Sets the receivers image and redraws the button.

NSButton Class Reference

Returns the position of the receivers image relative to its title.

Sets the position of the button's image relative to its title.

Returns a Boolean value indicating whether the button has a border.

Sets whether the receiver has a bezeled border.

Returns a Boolean value indicating whether the button is transparent.

Returns the appearance of the receivers border.

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

Managing Button State

Sets whether the button allows a mixed state.

Returns the receivers state.

Sets the cells state to the specified value.

Sets the receiver to its next state.

Highlights (or unhighlights) the receiver.

NSButton Class Reference

Accessing Key Equivalents

Returns the key-equivalent character of the receiver.

Handling Keyboard Events

Available in Mac OS X v10.0 and later.

NSButton Class Reference

Available in Mac OS X v10.0 and later.

Available in Mac OS X v10.0 and later.

Available in Mac OS X v10.0 and later.

NSButton Class Reference

Available in Mac OS X v10.0 and later.

Available in Mac OS X v10.0 and later.

NSButton Class Reference

Available in Mac OS X v10.0 and later.

Available in Mac OS X v10.0 and later.

NSButton Class Reference

Available in Mac OS X v10.0 and later.

Available in Mac OS X v10.0 and later.

controls bordersinstead, its a raised bezel. By default, buttons are bordered.

NSButton Class Reference

Available in Mac OS X v10.0 and later.

mouse-down events and tracks the mouse properly.

Available in Mac OS X v10.0 and later.

Available in Mac OS X v10.0 and later.

NSButton Class Reference

Available in Mac OS X v10.0 and later.

The event containing the key equivalent.

Available in Mac OS X v10.0 and later.

NSButton Class Reference

has two states: on and off.

Available in Mac OS X v10.0 and later.

Available in Mac OS X v10.0 and later.

Available in Mac OS X v10.0 and later.

NSButton Class Reference

Available in Mac OS X v10.0 and later.

Available in Mac OS X v10.0 and later.

NSButton Class Reference

setAttributedAlternateTitle: (page 16)

Available in Mac OS X v10.0 and later.

single line of most other controls bordersinstead, its a raised bezel.

Available in Mac OS X v10.0 and later.

NSButton Class Reference

Available in Mac OS X v10.0 and later.

Available in Mac OS X v10.0 and later.

NSButton Class Reference

setAlternateImage: (page 15)

Available in Mac OS X v10.0 and later.

The character to set as the button's key equivalent.

Available in Mac OS X v10.0 and later.

NSButton Class Reference

setImagePosition: (page 19)