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.
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 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.
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.
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).
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 :
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.
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.
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.
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 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.
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 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.
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.
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.
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.
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 2026-02-09).
Please help us by producing an implementation of
this and donating it to the GNUstep project.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 :
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.
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
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.