Swing JCheckBox API

Swinging Duke

Swing's JCheckBox class implements a checkbox object: a simple button component that appears beside a text label and contains a box in which a user can place a check mark. When the mouse is clicked inside the check area of a checkbox, an ItemEvent message is sent to all registered ItemListeners. This message contains information that specifies whether the checkbox has been selected or deselected by the user's mouse click.

The JCheckBox class -- along with JButton, JToggleButton, and JRadioButton -- is descended from the AbstractButton class. (For details, see the specification titled The Swing Button API.)

The JCheckBox class implements a button model interface named ButtonModel. The ButtonModel interface is shared by buttons, checkboxes, toggle buttons, and radio buttons. For more information on this interface, and for a look at how Swing buttons work in a real application, see the The Swing Button API.

Features of the JCheckBox Class

The JCheckBox class offers the following support for the positioning of check marks and text:

The position of the component's text label relative to the check mark.
Alignment of the check and text inside the Checkbox (that is, left-justified, centered, or right-justified).

The JCheckBox Model Interface

The JCheckBox model interface is shared by JButton, JCheckBox, and JRadioButton. JCheckBox has an isSelected state that is used by JCheckBox and JRadioButton, but not by JButton. For more details about the button model interface see the specification sheet titled "The Swing Button API".

JCheckBox Events

JCheckBox objects are a source of ItemEvents. By registering itself as an ItemListener on a checkbox, an object can ensure that it will be notified when a checkbox has been selected or deselected. For more details, see "The Swing Button API".

The Swing Checkbox API

In the 1.1 AWT, checkboxes pulled double duty, serving as both checkboxes and radio buttons. In 1.1, a checkbox could belong to a group in which only one checkbox could be selected at a time. In Swing, this "exclusive choice" capability is not supported. Instead, radio-button functionality is now supported by a new class named JRadioButton -- that is, by a real radio-button class.

For API compatibility, Swing's JCheckBox objects support all the old-style AWT Checkbox APIs. However, all methods that were designed to support exclusive selection with CheckboxGroups have now been deprecated, and will not perform old-style Checkbox exclusive-selection functionality.

Deprecated APIs

The following Checkbox APIs have been deprecated in Swing:

Checkbox(String label, 
	 boolean state, 
	 CheckboxGroup group)	  // will create a checkbox, but ignores the
				  // group argument

Checkbox(String label, 
	 CheckboxGroup group, 
	 boolean state)		  // will create a checkbox, but ignores the
				  // group argument

getLabel()  			  // replaced by getText()

setLabel(String label)  	  // replaced by setText(String text)

getState()  			  // replaced by isSelected()

setState()  			  // replaced by setSelected(boolean state)

getCheckboxGroup() 		  // Use RadioButtons instead

setCheckboxGroup(CheckboxGroup g) // Use RadioButtons instead