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.