Toggle Button Styles
Toggle buttons are instances of JToggleButton
. They display a state, which changes when the button is
pressed.
Toggle buttons on macOS display the usual on and off states (corresponding to the selected or not
selected states of a JToggleButton
). Checkboxes and radio buttons on macOS
can also display a third state, called mixed.
VAqua displays the mixed state when a supported button is selected and its JButton.selectedState
client property has the value indeterminate
.
The supported buttons are JCheckBox
instances, JRadioButton
instances,
and any JToggleButton
using the checkbox or radio style.
No support is provided for transitioning into this third state.
VAqua supports several styles for toggle buttons.
Most button styles
support several size options, specified using the JComponent.sizeVariant
client property with values
regular
(the default), small
, mini
, or large
.
The default style for a toggle button depends upon its size, content, and location. The basic styles are the textured style for buttons on a tool bar and the segmented button style for buttons elsewhere. These basic styles have fixed heights and are used only when the button content is compatible with the fixed height. If the button content is too large for the basic styles, then the bevel style is used for buttons without icons and the tool bar item or gradient styles are used for buttons with icons.
The following toggle button styles may be explicitly selected using the JButton.buttonType
client property:
Gradient
A gradient button is a rectangular button.
It is intended to be used with an icon, not with a text label.
Its size is unrestricted. The size variant options do not apply.
This style is selected by setting the JButton.buttonType
client property to gradient
.
Textured
A textured button has a flat white background and rounded corners.
It may be used with an icon and/or a text label.
It is recommended for use in the window frame.
It has a fixed height based on the size variant.
This style is selected by setting the JButton.buttonType
client property to textured
.
Tool Bar Item
A tool bar item is a button that displays an icon with a label underneath.
It is intended for use on the window frame.
This style is selected by setting the JButton.buttonType
client property to toolbarItem
.
Recessed
A recessed button has a recessed appearance with rounded corners.
It is recommended for displaying groups of objects or locations that users can select to narrow
the scope of a search or other operation.
It has a fixed height based on the size variant.
This style is selected by setting the JButton.buttonType
client property to recessed
.
Disclosure
A disclosure button displays an upward or downward triangle.
It is used to reveal or hide an expanded list of options.
It has a fixed size based on the size variant.
This style is selected by setting the JButton.buttonType
client property to disclosure
.
Disclosure Triangle
A disclosure triangle button displays triangle pointing sideways or downwards.
It is used to reveal or hide additional information or subordinate items.
It has a fixed size. It does not support size variants.
This style is selected by setting the JButton.buttonType
client property to disclosureTriangle
.
Checkbox
A button may be configured to display as a checkbox by setting the JButton.buttonType
client property to
checkbox
. Unlike a JCheckBox
, the button has no associated label.
It has a fixed size based on the size variant.
Radio
A button may be configured to display as a radio button by setting the JButton.buttonType
client property to
radio
. Unlike a JRadioButton
, the button has no associated label.
It has a fixed size based on the size variant.
Color Well
A color well displays a color selection (which is the button background color). By default, clicking on a color well displays the native color panel
to allow the user to change the color selection. This default behavior is suppressed if an ActionListener
is
attached to the button. A color well can be configured to support translucent colors by setting the JButton.enableTranslucentColors
client property to (Boolean) true
.
A color well has a minimum size, but is otherwise unrestricted. The size variant options do not apply.
This style is selected by setting the JButton.buttonType
client property to colorWell
.
Inline
An inline button has a recessed appearance with rounded ends.
It has a fixed height. It does not support size variants.
It has no recommended use.
This style is selected by setting the JButton.buttonType
client property to inline
.
Rounded Rectangle
A rounded rectangle button is translucent and has a border with rounded corners.
It has no recommended use as a toggle button.
It has a fixed height based on the size variant.
This style is selected by setting the JButton.buttonType
client property to roundRect
.
Round
A round button is a circular button with a flat background, designed to display an icon.
It has a fixed size based on the size variant.
This style is selected by setting the JButton.buttonType
client property to round
.
A round button displays as a round textured button when it is used on a tool bar.
Round Textured
A round textured button is a circular button with a flat background, designed to display an icon.
It has a fixed size based on the size variant.
This style is selected by setting the JButton.buttonType
client property to roundTextured
.
Bevel
A bevel button has a flat background and rounded corners.
It may be used with an icon and/or a text label.
Its size is unrestricted. The size variant options do not apply.
Use of this style is discouraged by Apple.
This style is selected by setting the JButton.buttonType
client property to bevel
.
Square
A square button has a light gradient and square corners.
It may be used with an icon and/or a text label.
Its size is unrestricted. The size variant options do not apply.
Use of this style is discouraged by Apple.
This style is selected by setting the JButton.buttonType
client property to square
.