Copyright ã1994 by NeXT Computer, Inc.  All Rights Reserved.

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 waysÐfor 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.

Setting the Images 

- (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.

Setting the Repeat Interval 

- (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.

Modifying Graphic Attributes 

- (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.

Modifying Graphic Attributes 

- (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.

Simulating a Click 

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