NSButtonCell

Inherits From: NSActionCell : NSCell : NSObject

Conforms To: NSCoding, NSCopying (NSCell) NSObject (NSObject)

Declared In: AppKit/NSButtonCell.h

Class Description

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 (an empty string in the case of stringValue), or 0 or NULL for the off or normal state. 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 waysfor 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 containing the image that represents the Return key. Usually an NSButtonCell displays a key equivalent as its image; if you ever set an image for the NSButtonCell, the key equivalent remains, but doesn't get displayed.

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 raises NSBadComparisonException if the otherCell argument is not of the NSButtonCell class.

Setting the Titles

• - (NSString *)alternateTitle Returns the NSButtonCell's alternate title (used while the button is in the highlighted state).
• - (void)setAlternateTitle:(NSString *)aString Makes a copy of aString and uses it as the NSButtonCell's alternate title.
• - (void)setFont:(NSFont *)fontObject Sets the NSFont used to draw the title.
• - (void)setTitle:(NSString *)aString Makes a copy of aString and uses it as the NSButtonCell's title.
• - (NSString *)title Returns the NSButtonCell's title.

• - (NSImage *)alternateImage Returns the NSButtonCell's alternate image (used while the button is in the highlighted state).
• - (NSCellImagePosition)imagePosition Returns the position of the NSButtonCell's image.
• - (void)setAlternateImage:(NSImage *)anImage Makes anImage the alternate image.
• - (void)setImagePosition:(NSCellImagePosition)aPosition Sets the position of the NSButtonCell's image in relation to its title.

• - (void)getPeriodicDelay:(float *)delay Gets repeat parameters for continuous NSButtonCells. interval:(float *)interval
• - (void)setPeriodicDelay:(float)delay Sets repeat parameters for continuous NSButtonCells. interval:(float)interval Setting the Key Equivalent
• - (NSString *)keyEquivalent Returns the NSButtonCell's key equivalent.
• - (NSFont *)keyEquivalentFont Returns the NSFont used to draw the key equivalent.
• - (unsigned int)keyEquivalentModifierMask Returns the mask indicating the possible modifier keys for NSButtonCell's key equivalent.
• - (void)setKeyEquivalent:(NSString *)aKeyEquivalent Sets the NSButtonCell's key equivalent.
• - (void)setKeyEquivalentModifierMask:(unsigned int)mask Sets the mask that determines the possible modifier keys for NSButtonCell's key equivalent.
• - (void)setKeyEquivalentFont:(NSFont *)fontObj Sets the NSFont used to draw the key equivalent.
• - (void)setKeyEquivalentFont:(NSString *)fontName size:(float)fontSize Sets the NSFont and size used to draw the key equivalent.

• - (BOOL)isOpaque Returns whether receiver is opaque.
• - (BOOL)isTransparent Returns whether the NSButtonCell is transparent.
• - (void)setTransparent:(BOOL)flag Sets whether the NSButtonCell is transparent.

• - (int)highlightsBy Returns how the NSButtonCell highlights when pressed.
• - (void)setHighlightsBy:(int)aType Sets how the NSButtonCell highlights when pressed.
• - (void)setShowsStateBy:(int)aType Sets how the NSButtonCell shows its alternate (pressed) state.
• - (void)setType:(NSButtonType)aType Sets the NSButtonCell's display behavior.
• - (int)showsStateBy Returns how NSButtonCell shows its alternate (pressed) state.

• - (void)performClick:(id)sender Simulates a user's mouse click on the NSButtonCell.