Using Swing Components

How to Use Buttons, Check Boxes, and Radio Buttons

To create a button, you can instantiate one of the many subclasses of the AbstractButton class. First, this section explains the basic button API that AbstractButton defines -- and thus all Swing buttons have in common. Because the JButton subclass of AbstractButton defines little additional public API, this section uses it to show how buttons work. Finally, this section shows you how to use check boxes and radio buttons--specialized buttons that inherit from AbstractButton.

The following table shows the Swing-defined AbstractButton subclasses that you might want to use:

Class	Summary	Where Described
JButton	A common button.	This section.
JCheckBox	A typical check box.	How to Use Check Boxes
JRadioButton	One of a group of radio buttons.	How to Use Radio Buttons
JMenuItem	An item in a menu.	How to Use Menus
JToggleButton	Implements toggle functionality inherited by JCheckBox and JRadioButton.	Used to implement the crayon buttons in How to Use Color Choosers, the cm button in How to Use Scroll Panes, and NumberButton in the Bingo game.

---

Note: If you want to collect a group of buttons into a row or column, then you should check out tool bars.

---

Here is a picture of an application that displays three buttons:

---

Try this:

1. Compile and run the application. The source file is ButtonDemo.java.
   See Getting Started with Swing if you need help.
2. Click the left button.
   It disables the middle button (and itself, since it's no longer useful) and enables the right button.
3. Click the right button.
   It enables the middle button and the left button, and disables itself.

---

As the ButtonDemo example shows, a Swing button can display both text and an image. In ButtonDemo, each button has its text in a different place, relative to its image. The underlined letter in each button's text shows the mnemonic -- the keyboard alternative -- for each button.

When a button is disabled, the look-and-feel automatically generates the button's disabled appearance. However, you could provide an image to be substituted for the normal image. For example, you could provide gray versions of the images used in the left and right buttons.

How you implement event handling depends on the type of button you use and how you use it. Generally, you implement an action listener, which is notified every time the user clicks the button. For check boxes you usually use an item listener, which is notified when the check box is selected or deselected.

Below is the code from ButtonDemo.java that creates the buttons in the previous example and reacts to button clicks. The bold code is the code that would remain if the buttons had no images.

//In initialization code:
    ImageIcon leftButtonIcon = new ImageIcon("images/right.gif");
    ImageIcon middleButtonIcon = new ImageIcon("images/middle.gif");
    ImageIcon rightButtonIcon = new ImageIcon("images/left.gif");

    b1 = new JButton("Disable middle button", leftButtonIcon);
    b1.setVerticalTextPosition(AbstractButton.CENTER);
    b1.setHorizontalTextPosition(AbstractButton.LEFT);
    b1.setMnemonic('d');
    b1.setActionCommand("disable");

    b2 = new JButton("Middle button", middleButtonIcon);
    b2.setVerticalTextPosition(AbstractButton.BOTTOM);
    b2.setHorizontalTextPosition(AbstractButton.CENTER);
    b2.setMnemonic('m');

    b3 = new JButton("Enable middle button", rightButtonIcon);
    //Use the default text position of CENTER, RIGHT.
    b3.setMnemonic('e');
    b3.setActionCommand("enable");
    b3.setEnabled(false);

    //Listen for actions on buttons 1 and 3.
    b1.addActionListener(this);
    b3.addActionListener(this);
    . . .
}

public void actionPerformed(java.awt.event.ActionEvent e) {
    if (e.getActionCommand().equals("disable")) {
        b2.setEnabled(false);
        b1.setEnabled(false);
        b3.setEnabled(true);
    } else { 
        b2.setEnabled(true);
        b1.setEnabled(true);
        b3.setEnabled(false);
    }
}

How to Use Check Boxes

The Swing release supports check box buttons with the JCheckBox class. Swing also supports check boxes in menus, using the JCheckBoxMenuItem class. Because JCheckBox and JCheckBoxMenuItem inherit from AbstractButton, Swing check boxes have all the usual button characteristics, as discussed earlier in this section. For example, you can specify images to be used in check boxes.

Check boxes are similar to radio buttons, but their selection model is different, by convention. Any number of check boxes in a group -- none, some, or all -- can be selected. A group of radio buttons, on the other hand, can have only one button selected.

Here is a picture of an application that uses four check boxes to customize a cartoon:

---

Try this:

1. Compile and run the application. The source file is CheckBoxDemo.java. You will also need the 16 image files in the example-swing/images directory that begin with "geek". To get the image files, you can download the swing lesson.
   See Getting Started with Swing if you need help.
2. Click the Chin button or press Alt-c.
   The Chin check box becomes unselected, and the chin disappears from the picture. The other check boxes remain selected. This application has one item listener that listens to all the check boxes. Each time the item listener receives an event, the application loads a new picture that reflects the current state of the check boxes.

---

A check box generates one item event and one action event per click. Usually, you listen only for item events, since they let you determine whether the click selected or deselected the check box. Below is the code from CheckBoxDemo.java that creates the check boxes in the previous example and reacts to clicks.

//In initialization code:
    chinButton = new JCheckBox("Chin");
    chinButton.setMnemonic('c'); 
    chinButton.setSelected(true);

    glassesButton = new JCheckBox("Glasses");
    glassesButton.setMnemonic('g'); 
    glassesButton.setSelected(true);

    hairButton = new JCheckBox("Hair");
    hairButton.setMnemonic('h'); 
    hairButton.setSelected(true);

    teethButton = new JCheckBox("Teeth");
    teethButton.setMnemonic('t'); 
    teethButton.setSelected(true);

    // Register a listener for the check boxes.
    CheckBoxListener myListener = new CheckBoxListener();
    chinButton.addItemListener(myListener);
    glassesButton.addItemListener(myListener);
    hairButton.addItemListener(myListener);
    teethButton.addItemListener(myListener);
...
class CheckBoxListener implements ItemListener {
    public void itemStateChanged(ItemEvent e) {
        ...
	Object source = e.getItemSelectable();

        if (source == chinButton) {
            //...make a note of it...
        } else if (source == glassesButton) {
            //...make a note of it...
        } else if (source == hairButton) {
            //...make a note of it...
        } else if (source == teethButton) {
            //...make a note of it...
        }

        if (e.getStateChange() == ItemEvent.DESELECTED)
            //...make a note of it...
        picture.setIcon(/* new icon */);
        ...
    }
}

How to Use Radio Buttons

Radio buttons are groups of buttons in which, by convention, only one button at a time can be selected. The Swing release supports radio buttons with the JRadioButton and ButtonGroup classes. To put a radio button in a menu, use the JRadioButtonMenuItem class. Other ways of displaying one-of-many choices are combo boxes and lists. Radio buttons look similar to check boxes, but, by convention, check boxes place no limits on how many items can be selected at a time.

Because JRadioButton inherits from AbstractButton, Swing radio buttons have all the usual button characteristics, as discussed earlier in this section. For example, you can specify the image displayed in a radio button.

Here is a picture of an application that uses five radio buttons to let you choose which kind of pet is displayed:

---

Try this:

1. Compile and run the application. The source file is RadioButtonDemo.java. You will also need 5 image files: Bird.gif, Cat.gif, Dog.gif, Rabbit.gif, and Pig.gif.
   See Getting Started with Swing if you need help.
2. Click the Dog button or press Alt-d.
   The Dog button becomes selected, which makes the Bird button become unselected. The picture switches from a bird to a dog. This application has one action listener that listens to all the radio buttons. Each time the action listener receives an event, the application displays the picture for the radio button that was just clicked.

---

Each time the user clicks a radio button (even if it was already selected), the button fires an action event . One or two item events also occur -- one from the button that was just selected, and another from the button that lost the selection (if any). Usually, you handle radio button clicks using an action listener.

Below is the code from RadioButtonDemo.java that creates the radio buttons in the previous example and reacts to clicks.

//In initialization code:
    // Create the radio buttons.
    JRadioButton birdButton = new JRadioButton(birdString);
    birdButton.setMnemonic('b');
    birdButton.setActionCommand(birdString);
    birdButton.setSelected(true);

    JRadioButton catButton = new JRadioButton(catString);
    catButton.setMnemonic('c');
    catButton.setActionCommand(catString);

    JRadioButton dogButton = new JRadioButton(dogString);
    dogButton.setMnemonic('d');
    dogButton.setActionCommand(dogString);

    JRadioButton rabbitButton = new JRadioButton(rabbitString);
    rabbitButton.setMnemonic('r');
    rabbitButton.setActionCommand(rabbitString);

    JRadioButton pigButton = new JRadioButton(pigString);
    pigButton.setMnemonic('t');
    pigButton.setActionCommand(pigString);

    // Group the radio buttons.
    ButtonGroup group = new ButtonGroup();
    group.add(birdButton);
    group.add(catButton);
    group.add(dogButton);
    group.add(rabbitButton);
    group.add(pigButton);

    // Register a listener for the radio buttons.
    RadioListener myListener = new RadioListener();
    birdButton.addActionListener(myListener);
    catButton.addActionListener(myListener);
    dogButton.addActionListener(myListener);
    rabbitButton.addActionListener(myListener);
    pigButton.addActionListener(myListener);
...
class RadioListener implements ActionListener ... {
    public void actionPerformed(ActionEvent e) {
        picture.setIcon(new ImageIcon("images/" 
                                      + e.getActionCommand() 
				      + ".gif"));
    }
}

For each group of radio buttons, you need to create a ButtonGroup instance and add each radio button to it. The ButtonGroup takes care of unselecting the previous selection when the user selects another button in the group.

You should generally initialize a group of radio buttons so that one is selected. However, the API doesn't enforce this rule -- a group of radio buttons can have no initial selection. Once the user makes a selection, there's currently no way to make all the radio buttons be unselected again. [PENDING: Some people have requested API that lets them unselect all radio buttons programmatically. We'll update this section if that API appears.]

The Button API

The following tables list the commonly used AbstractButton methods, JButton, JCheckBox, and JRadioButton constructors, and ButtonGroup constructors and methods. You can see most of this API in action by playing with the Buttons, Radio Buttons, and Check Boxes panes in the SwingSet example that's part of the Swing release. See the release's top-level README.txt for help finding and using SwingSet.

The API for using buttons falls into these categories:

• Setting or Getting the Button's Contents
• Fine Tuning the Button's Appearance
• Implementing the Button's Functionality
• Check Box Constructors
• Commonly Used ButtonGroup Constructors/Methods
• Radio Button Constructors

Setting or Getting the Button's Contents

Method or Constructor	Purpose
JButton(String, Icon) JButton(String) JButton(Icon) JButton()	Create a JButton instance, initializing it to have the specified text/image.
void setText(String) String getText()	Set or get the text displayed by the button.
void setIcon(Icon) Icon getIcon()	Set or get the image displayed by the button when the button isn't selected or pressed.
void setDisabledIcon(Icon) Icon getDisabledIcon()	Set or get the image displayed by the button when it's disabled. If you don't specify a disabled image, then the look-and-feel creates one by manipulating the default image.
void setPressedIcon(Icon) Icon getPressedIcon()	Set or get the image displayed by the button when it's being pressed.
void setSelectedIcon(Icon) Icon getSelectedIcon() void setDisabledSelectedIcon(Icon) Icon getDisabledSelectedIcon()	Set or get the image displayed by the button when it's selected. If you don't specify a disabled selected image, then the look-and-feel creates one by manipulating the selected image.
setRolloverEnabled(boolean) boolean getRolloverEnabled() void setRolloverIcon(Icon) Icon getRolloverIcon() void setRolloverSelectedIcon(Icon) Icon getRolloverSelectedIcon()	Use setRolloverEnabled(true) and setRolloverIcon(someIcon) to make the button display the specified icon when the cursor passes over it.

Fine Tuning the Button's Appearance

Method or Constructor	Purpose
void setHorizontalAlignment(int) void setVerticalAlignment(int) int getHorizontalAlignment() int getVerticalAlignment()	Set or get where in the button its contents should be placed. The AbstractButton class allows any one of the following values for horizontal alignment: LEFT, CENTER (the default), and RIGHT. For vertical alignment: TOP, CENTER (the default), and BOTTOM.
void setHorizontalTextPosition(int) void setVerticalTextPosition(int) int getHorizontalTextPosition() int getVerticalTextPosition()	Set or get where the button's text should be placed, relative to the button's image. The AbstractButton class allows any one of the following values for horizontal position: LEFT, CENTER, and RIGHT (the default). For vertical position: TOP, CENTER (the default), and BOTTOM.
void setMargin(Insets) Insets getMargin()	Set or get the number of pixels between the button's border and its contents.
void setFocusPainted(boolean) boolean isFocusPainted()	Set or get whether the button should look different when it has the focus.
void setBorderPainted(boolean) boolean isBorderPainted()	Set or get whether the border of the button should be painted.

Implementing the Button's Functionality

Method or Constructor	Purpose
void setMnemonic(char) char getMnemonic()	Set or get the keyboard alternative to clicking the button. Note: In Swing 1.0.2, buttons ignore their mnemonics (key accelerators). This bug is fixed in Swing 1.0.3.
void setActionCommand(String) String getActionCommand(void)	Set or get the name of the action performed by the button.
void addActionListener(ActionListener) ActionListener removeActionListener()	Add or remove an object that listens for action events fired by the button.
void addItemListener(ItemListener) ItemListener removeItemListener()	Add or remove an object that listens for item events fired by the button.
void setSelected(boolean) boolean isSelected()	Set or get whether the button is selected. Makes sense only for buttons that have on/off state, such as check boxes.
void doClick() void doClick(int)	Programmatically perform a "click". The optional argument specifies the amount of time (in milliseconds) that the button should look pressed.

Check Box Constructors

Constructor	Purpose
JCheckBox(String) JCheckBox(String, boolean) JCheckBox(Icon) JCheckBox(Icon, boolean) JCheckBox(String, Icon) JCheckBox(String, Icon, boolean) JCheckBox()	Create a JCheckBox instance. The string argument specifies the text, if any, that the check box should display. Similarly, the Icon argument specifies the image that should be used instead of the look-and-feel's default check box image. Specifying the boolean argument as true initializes the check box to be selected. If the boolean argument is absent or false, then the check box is initially unselected.
JCheckBoxMenuItem(String) JCheckBoxMenuItem(String, boolean) JCheckBoxMenuItem(Icon) JCheckBoxMenuItem(String, Icon) JCheckBoxMenuItem(String, Icon, boolean) JCheckBoxMenuItem()	Create a JCheckBoxMenuItem instance. The arguments are interpreted in the same way as the arguments to the JCheckBox constructors.

Commonly Used ButtonGroup Constructors/Methods

Constructor or Method	Purpose
ButtonGroup()	Creates a ButtonGroup instance.
void add(AbstractButton) void remove(AbstractButton)	Adds a button to the group, or removes a button from the group.

Radio Button Constructors

Constructor	Purpose
JRadioButton(String) JRadioButton(String, boolean) JRadioButton(Icon) JRadioButton(Icon, boolean) JRadioButton(String, Icon) JRadioButton(String, Icon, boolean) JRadioButton()	Creates a JRadioButton instance. The string argument specifies the text, if any, that the radio button should display. Similarly, the Icon argument specifies the image that should be used instead of the look-and-feel's default radio button image. Specifying the boolean argument as true initializes the radio button to be selected, subject to the approval of the ButtonGroup object. If the boolean argument is absent or false, then the radio button is initially unselected.
JRadioButtonMenuItem(String) JRadioButtonMenuItem(Icon) JRadioButtonMenuItem(String, Icon) JRadioButtonMenuItem()	Creates a JRadioButtonMenuItem instance. The arguments are interpreted in the same way as the arguments to the JRadioButton constructors.

Examples that Use Buttons, Check Boxes, and Radio Buttons

The following examples use JButton, JCheckBox, or JRadioButton objects either as buttons or as menu items. For examples of using MenuItem objects see the section for menus. Also see the tool bar section, which describes adding JButton objects to a JToolBar.

Example	Where Described	Notes
ButtonDemo.java	This page.	Uses mnemonics and icons. Specifies the button text position, relative to the button icon. Uses action commands.
AppletDemo.java	Running a Swing Applet	The same example as on this page, but implemented as an applet.
ListDialog.java	How to Use BoxLayout	Implements a dialog with two buttons, one of which is the default button. [PENDING: should mention getRootPane().setDefaultButton(aButton) somewhere on this page.]
DialogDemo.java	How to Make Dialogs	Has "Show it" buttons whose behavior is tied to the state of radio buttons. Uses sizable, though anonymous, inner classes to implement the action listeners.
ProgressBarDemo.java	How to Monitor Progress	Implements the action listener with a named inner class.
CheckBoxDemo.java	This page.	Uses check box buttons to determine which of 16 images it should display.
ActionDemo.java	How to Use Actions	Uses check box menu items to set the state of the program.
RadioButtonDemo.java	This page.	Uses radio buttons to determine which of five images it should display.
DialogDemo.java	How to Make Dialogs	Contains several sets of radio buttons, which it uses to determine which dialog to bring up.
MenuDemo.java	How to Use Menus	Contains radio button menu items.

Using Swing Components