NSButtonCell

Authors

Scott Christley (scottc@net-community.com)
Felipe A. Rodriguez (far@ix.netcom.com)

Date: Generated at 2025-12-03

The button cell class

Software documentation for the NSButtonCell class

NSButtonCell : NSActionCell

Declared in:

AppKit/NSButtonCell.h

Availability: OpenStep

NSButtonCell is the cell class responsible for displaying and handling the behavior of buttons in the GNUstep GUI framework. It provides functionality for various button types including push buttons, toggle buttons, radio buttons, and switch buttons. The cell manages the button's appearance, state, key equivalents, images, and user interaction behavior. As a subclass of NSActionCell, NSButtonCell inherits action and target functionality while adding button-specific features such as alternate titles and images for different button states, periodic actions for continuous button presses, and customizable visual styles through bezel styles and gradient types.

TODO Description

NSButtonCell declares 14 Instance Variables

Method summary

alternateImage

- (NSImage*) alternateImage;

Availability: OpenStep

Returns the alternate image displayed when the button is in its alternate state, such as when pressed or highlighted. The alternate image provides visual feedback to indicate the button's current interaction state. Returns nil if no alternate image is set.

Returns the NSButtonCell's alternate image.

alternateMnemonic

- (NSString*) alternateMnemonic;

Availability: MacOS-X 10.0.0

Returns the mnemonic character extracted from the alternate title, which represents the keyboard shortcut character for the button's alternate state. Returns nil if no mnemonic has been set for the alternate title.

alternateMnemonicLocation

- (NSUInteger) alternateMnemonicLocation;

Availability: MacOS-X 10.0.0

Returns the character position of the mnemonic within the alternate title string. This indicates where the mnemonic character appears for proper keyboard navigation and visual highlighting. Returns NSNotFound if no mnemonic location is set.

alternateTitle

- (NSString*) alternateTitle;

Availability: OpenStep

Returns the alternate title displayed when the button is in its alternate state. The alternate title is typically shown when the button is pressed or highlighted, providing visual feedback to the user about the button's current state.

Returns the NSButtonCell's alternate title (used when highlighted).

attributedAlternateTitle

- (NSAttributedString*) attributedAlternateTitle;

Availability: MacOS-X 10.0.0

Returns the alternate title as an attributed string, providing access to formatting information such as font, color, and style attributes applied to the alternate title text. Returns nil if no alternate attributed title has been set.

attributedTitle

- (NSAttributedString*) attributedTitle;

Availability: MacOS-X 10.0.0

Returns the primary title as an attributed string, including all formatting attributes such as font, color, and text styling. This provides richer text display capabilities than plain string titles. Returns nil if no attributed title has been set.

backgroundColor

- (NSColor*) backgroundColor;

Availability: MacOS-X 10.4.0

Returns the background color used when drawing the button cell. This color is applied behind the button's content and affects the overall appearance of the button. Returns nil if using the default system background color for the button's current style and state.

bezelStyle

- (NSBezelStyle) bezelStyle;

Availability: MacOS-X 10.0.0

Returns the current bezel style used for drawing the button's border and background. The bezel style determines the visual appearance of the button, including its shape, shadows, and dimensional effects. Different styles provide various visual treatments from flat to highly dimensional appearances.

drawBezelWithFrame: inView:

- (void) drawBezelWithFrame: (NSRect)cellFrame inView: (NSView*)controlView;

Availability: MacOS-X 10.4.0

Draws the button's bezel (border and background) within the specified frame in the given view. This method handles the visual rendering of the button's dimensional appearance, including borders, background fills, shadows, and other bezel-related visual elements.

drawImage: withFrame: inView:

- (void) drawImage: (NSImage*)imageToDisplay withFrame: (NSRect)cellFrame inView: (NSView*)controlView;

Availability: MacOS-X 10.4.0

Draws the specified image within the given frame in the control view. This method handles the rendering of the button's image content, including proper scaling, positioning, and state-dependent visual effects such as dimming for disabled buttons.

drawTitle: withFrame: inView:

- (NSRect) drawTitle: (NSAttributedString*)titleToDisplay withFrame: (NSRect)cellFrame inView: (NSView*)controlView;

Availability: MacOS-X 10.4.0

Draws the button's title text within the specified frame and returns the actual rectangle used for text rendering. This method handles text layout, font application, color application, and positioning of the title content within the button's available space.

getPeriodicDelay: interval:

- (void) getPeriodicDelay: (float*)delay interval: (float*)interval;

Availability: OpenStep

Retrieves the current periodic delay and interval settings for continuous button actions. The delay specifies how long to wait before beginning repeated actions, while the interval specifies the time between subsequent repeated actions. Both values are returned through the provided pointer parameters.

Gets the NSButtonCell's delay and the interval parameters used when NSButton sends continouly action messages. By default delay is 0.4 and interval is 0.075.

gradientType

- (NSGradientType) gradientType;

Availability: MacOS-X 10.0.0

Returns the current gradient type applied to the button's background. The gradient type determines the direction and intensity of shading effects, creating dimensional appearance through light and shadow gradients across the button surface.

highlightsBy

- (NSInteger) highlightsBy;

Availability: OpenStep

Returns the mask that specifies which user interactions cause the button to highlight visually. The mask combines flags that determine whether the button highlights on mouse down, mouse entered, content changes, or other interaction states to provide visual feedback.

Returns a mask describing how the button cell is highlighted :

NSNoCellMask, NSContentsCellMask,NSPushInCellMask,NSChangeGrayCellMask, NSChangeBackgroundCellMask

imageDimsWhenDisabled

- (BOOL) imageDimsWhenDisabled;

Availability: MacOS-X 10.0.0

Returns whether the button's image automatically dims when the button is disabled. When enabled, disabled buttons show their images with reduced opacity or altered appearance to indicate the non-interactive state visually.

imagePosition

- (NSCellImagePosition) imagePosition;

Availability: OpenStep

Returns the current positioning of the image relative to the title text within the button cell. The image position determines the layout arrangement of the image and text elements, such as image above text, image to the left of text, or image only.

Returns the NSButtonCell's image position. See NSCellImagePosition for more information.

imageScaling

- (NSImageScaling) imageScaling;

Availability: MacOS-X 10.5.0

Returns the current image scaling mode used when displaying the button's image. This determines how the image is resized to fit within the available space, such as proportional scaling, scaling to fit, or scaling to fill the entire area.

isTransparent

- (BOOL) isTransparent;

Availability: OpenStep

Returns whether the button cell is configured to be transparent, meaning its background does not draw and content behind it shows through. Transparent buttons are useful for overlay controls and custom drawing scenarios where background visibility is desired.

Returns whether the button cell is transparent.

keyEquivalent

- (NSString*) keyEquivalent;

Availability: OpenStep

Returns the key equivalent string that can be used to activate this button via keyboard shortcut. The key equivalent is typically a single character that, when pressed with appropriate modifier keys, triggers the button's action. Returns nil if no key equivalent is set.

Returns the NSButtonCell's key equivalent. The key equivalent and its modifier mask are used to simulate the click of the button in [NSButton -performKeyEquivalent:] . Returns an empty string if no key equivalent is defined. By default NSButtonCell hasn't key equivalent.

keyEquivalentFont

- (NSFont*) keyEquivalentFont;

Availability: OpenStep

Returns the font used to display the key equivalent symbol or character within the button. This font may differ from the main title font and is used specifically for rendering key equivalent indicators. Returns nil if using the default system font.

Returns the NSFont of the key equivalent.

keyEquivalentModifierMask

- (NSUInteger) keyEquivalentModifierMask;

Availability: OpenStep

Returns the modifier key mask that must be pressed along with the key equivalent to activate the button. This mask combines flags like NSCommandKeyMask, NSShiftKeyMask, NSControlKeyMask, and NSAlternateKeyMask to specify the required key combination.

Returns the modifier mask of the NSButtonCell's key equivalent. The key equivalent and its modifier mask are used to simulate the click of the button in [NSButton -performKeyEquivalent:] . The default mask is 0.

mouseEntered:

- (void) mouseEntered: (NSEvent*)event;

Availability: MacOS-X 10.0.0

Handles mouse entered events when the cursor moves into the button cell's bounds. This method is called to update the button's appearance for mouse hover effects, such as highlighting or showing borders only while the mouse is inside the button area.

mouseExited:

- (void) mouseExited: (NSEvent*)event;

Availability: MacOS-X 10.0.0

Handles mouse exited events when the cursor moves out of the button cell's bounds. This method is called to update the button's appearance when mouse interaction ends, such as removing hover highlights or hiding borders that only show during mouse interaction.

setAlternateImage:

- (void) setAlternateImage: (NSImage*)anImage;

Availability: OpenStep

Sets the alternate image to be displayed when the button is in its alternate state. This image is shown during button press, highlight, or other alternate state conditions. Pass nil to remove the alternate image. The image object is retained by the button cell.

Sets the NSButtonCell's alternate image to anImage.

setAlternateMnemonicLocation:

- (void) setAlternateMnemonicLocation: (NSUInteger)location;

Availability: MacOS-X 10.0.0

Sets the character position within the alternate title where the mnemonic character should be highlighted. This is used for keyboard navigation accessibility and visual indication of the shortcut key. Pass NSNotFound to remove the mnemonic location.
Not implemented (as of 2025-12-03).
Please help us by producing an implementation of this and donating it to the GNUstep project.

setAlternateTitle:

- (void) setAlternateTitle: (NSString*)aString;

Availability: OpenStep

Sets the alternate title to be displayed when the button is in its alternate state. This title is shown during button press or highlight states, allowing for different text to appear based on the button's current interaction state. Pass nil to remove the alternate title.

Sets the NSButtonCell's alternate title (used when highlighted) to aString and update the cell if it contains a NSControl view.

setAlternateTitleWithMnemonic:

- (void) setAlternateTitleWithMnemonic: (NSString*)aString;

Availability: MacOS-X 10.0.0

Sets the alternate title from a string containing mnemonic markers, automatically processing ampersand characters to create keyboard shortcuts and visual indicators. The processed title becomes the alternate title with appropriate mnemonic highlighting.

setAttributedAlternateTitle:

- (void) setAttributedAlternateTitle: (NSAttributedString*)aString;

Availability: MacOS-X 10.0.0

Sets the alternate title using an attributed string, allowing for rich text formatting including font variations, colors, and other text attributes. This attributed title is displayed when the button is in its alternate state. Pass nil to remove the attributed alternate title.

setAttributedTitle:

- (void) setAttributedTitle: (NSAttributedString*)aString;

Availability: MacOS-X 10.0.0

Sets the primary title using an attributed string, enabling rich text formatting with fonts, colors, and styling attributes. This becomes the main title displayed when the button is in its normal state. Pass nil to remove the attributed title.

setBackgroundColor:

- (void) setBackgroundColor: (NSColor*)color;

Availability: MacOS-X 10.4.0

Sets the background color for the button cell. This color is drawn behind the button's content and can be used to customize the button's appearance beyond the standard bezel styles. Pass nil to use the default system background color for the button's style.

setBezelStyle:

- (void) setBezelStyle: (NSBezelStyle)bezelStyle;

Availability: MacOS-X 10.0.0

Sets the bezel style that determines the visual appearance of the button's border and background. The bezel style controls the button's shape, dimensionality, and visual treatment, ranging from flat styles to highly dimensional effects with shadows and highlighting.

setButtonType:

- (void) setButtonType: (NSButtonType)buttonType;

Availability: OpenStep

Configures the button's type, which determines its fundamental interaction behavior and visual appearance. Different button types provide distinct behaviors for state changes, highlighting, and response to user interaction such as momentary, toggle, or radio button behaviors.

setFont:

- (void) setFont: (NSFont*)fontObject;

Availability: OpenStep

Sets the font used to display both the regular and alternate titles of the button cell. This font affects all text rendering within the button, ensuring consistent typography across different button states. The font object is retained by the button cell.

Sets the NSButtonCell's font to fontObject. The key equivalent font size is changed to match the fontObject if needed.

setGradientType:

- (void) setGradientType: (NSGradientType)gradientType;

Availability: MacOS-X 10.0.0

Sets the gradient type for the button's background shading. Different gradient types provide various dimensional effects through directional shading, from subtle concave effects to strong convex appearance with pronounced highlighting and shadowing.

setHighlightsBy:

- (void) setHighlightsBy: (NSInteger)mask;

Availability: OpenStep

Sets the mask that determines which user interactions trigger visual highlighting of the button. The mask combines various flags to specify highlighting behavior for mouse down, mouse entry, content changes, and other interactive states that should provide visual feedback.

Sets a mask describing how the button cell is highlighted :

NSNoCellMask, NSContentsCellMask,NSPushInCellMask,NSChangeGrayCellMask, NSChangeBackgroundCellMask

setImageDimsWhenDisabled:

- (void) setImageDimsWhenDisabled: (BOOL)flag;

Availability: MacOS-X 10.0.0

Sets whether the button's image should automatically dim when the button becomes disabled. When enabled, this provides visual feedback about the button's non-interactive state by reducing image opacity or applying visual effects to indicate disability.

setImagePosition:

- (void) setImagePosition: (NSCellImagePosition)aPosition;

Availability: OpenStep

Sets the positioning of the image relative to the title text within the button cell. This determines the visual layout of image and text elements, controlling whether the image appears above, below, to the left, to the right, or overlapping with the text.

Sets the image position. The GNUstep implementation depends only on the image position. If the image position is set to NSNoImage then the type is set to NSTextCellType , to NSImageCellType otherwise

setImageScaling:

- (void) setImageScaling: (NSImageScaling)scaling;

Availability: MacOS-X 10.5.0

Sets the image scaling mode that determines how the button's image is resized to fit within the button's bounds. Different scaling modes provide various behaviors for maintaining aspect ratio and fitting images into the available display area.

setKeyEquivalent:

- (void) setKeyEquivalent: (NSString*)key;

Availability: OpenStep

Sets the key equivalent string that allows keyboard activation of the button. When this key is pressed with the appropriate modifier keys, the button's action is triggered. Pass an empty string or nil to remove the key equivalent. Common values include single characters, escape sequences, or special key constants.

Sets the NSButtonCell's key equivalent to key. The key equivalent and its modifier mask are used to simulate the click of the button in [NSButton -performKeyEquivalent:] . By default NSButton hasn't key equivalent.

setKeyEquivalentFont:

- (void) setKeyEquivalentFont: (NSFont*)fontObj;

Availability: OpenStep

Sets the font used for displaying key equivalent indicators within the button. This font is used specifically for key equivalent symbols and may be different from the main button title font. Pass nil to use the default system font for key equivalents.

Sets the NSFont of the key equivalent to fontObject.

setKeyEquivalentFont: size:

- (void) setKeyEquivalentFont: (NSString*)fontName size: (float)fontSize;

Availability: OpenStep

Sets the key equivalent font using a font name and size. This convenience method creates a font object from the specified name and size, then sets it as the key equivalent font. The font is used for rendering key equivalent indicators within the button.

Sets the NSFont with size fontSize of the key equivalent to fontName.

setKeyEquivalentModifierMask:

- (void) setKeyEquivalentModifierMask: (NSUInteger)mask;

Availability: OpenStep

Sets the modifier key mask that must be pressed along with the key equivalent to activate the button. The mask should combine appropriate flags like NSCommandKeyMask to specify which modifier keys are required for the keyboard shortcut.

Sets the modifier mask of the NSButtonCell's key equivalent to mask. The key equivalent and its modifier mask are used to simulate the click of the button in [NSButton -performKeyEquivalent:] . By default the mask is 0.

setPeriodicDelay: interval:

- (void) setPeriodicDelay: (float)delay interval: (float)interval;

Availability: OpenStep

Sets the periodic delay and interval for continuous button actions when the button is held down. The delay parameter specifies the initial wait time before repeated actions begin, and the interval parameter specifies the time between subsequent repeated actions. This enables automatic repetition for buttons like scrollers.

Sets the NSButtonCell's delay and interval parameters used when NSButton sends continouly action messages. By default delay is 0.4 and interval is 0.075.

setShowsBorderOnlyWhileMouseInside:

- (void) setShowsBorderOnlyWhileMouseInside: (BOOL)show;

Availability: MacOS-X 10.0.0

Sets whether the button should display its border only during mouse hover. When enabled, the button appears borderless until the mouse enters its bounds, at which point the border appears to provide visual feedback for potential interaction.

setShowsStateBy:

- (void) setShowsStateBy: (NSInteger)mask;

Availability: OpenStep

Sets the mask that determines which conditions cause the button to display its alternate state visually. This controls when the button shows alternate titles, images, or other state-dependent visual elements to reflect different operational conditions.

setSound:

- (void) setSound: (NSSound*)aSound;

Availability: MacOS-X 10.0.0

Sets the sound that plays when the button is activated. The sound provides auditory feedback for button interactions, enhancing the user experience with audio cues. Pass nil to remove the button's sound and disable audio feedback for button activation.

setTitle:

- (void) setTitle: (NSString*)aString;

Availability: OpenStep

Sets the primary title text displayed on the button. This is the default text shown when the button is in its normal state. The title string is copied and stored by the button cell. Pass nil to remove the title text entirely.

Sets the NSButtonCell's title to aString.

setTitleWithMnemonic:

- (void) setTitleWithMnemonic: (NSString*)aString;

Availability: MacOS-X 10.0.0

Sets the primary title from a string that includes mnemonic markers, typically ampersand characters that indicate keyboard shortcuts. The mnemonic character is automatically processed to create the appropriate key equivalent and visual underlining for accessibility.

setTransparent:

- (void) setTransparent: (BOOL)flag;

Availability: OpenStep

Sets whether the button cell should be transparent. When set to YES, the button's background is not drawn, allowing content behind it to show through. This is useful for creating overlay buttons or custom visual effects where background transparency is needed.

Sets whether the button cell is transparent.

showsBorderOnlyWhileMouseInside

- (BOOL) showsBorderOnlyWhileMouseInside;

Availability: MacOS-X 10.0.0

Returns whether the button shows its border only when the mouse cursor is positioned over it. This creates a hover effect where the button appears borderless until mouse interaction, providing a cleaner interface with interactive feedback.

showsStateBy

- (NSInteger) showsStateBy;

Availability: OpenStep

Returns the mask that specifies which conditions cause the button to show its alternate state visually. This mask determines when alternate titles, images, or other state-dependent visual elements are displayed to reflect the button's current operational state.

sound

- (NSSound*) sound;

Availability: MacOS-X 10.0.0

Returns the sound object that plays when the button is activated. This sound provides auditory feedback for button interactions. Returns nil if no sound has been assigned to the button or if audio feedback is disabled for button activation.

title

- (NSString*) title;

Availability: OpenStep

Returns the primary title text currently displayed on the button. This is the main text shown when the button is in its normal, non-highlighted state. Returns nil if no title has been set.

Returns the NSButtonCell's title.

Instance Variables for NSButtonCell Class

_altContents

@protected NSString* _altContents;

Availability: OpenStep

Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.