Using the JFC/Swing Packages

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 in How to Use Buttons. For example, you can specify the image displayed in a radio button.

---

Note: In Swing 1.0.2, buttons ignore their mnemonics (key accelerators). This bug is fixed in Swing 1.0.3.

---

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 teddyButton = new JRadioButton(teddyString);
    teddyButton.setMnemonic('t');
    teddyButton.setActionCommand(teddyString);

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

    // Register a listener for the radio buttons.
    RadioListener myListener = new RadioListener();
    birdButton.addActionListener(myListener);
    catButton.addActionListener(myListener);
    dogButton.addActionListener(myListener);
    rabbitButton.addActionListener(myListener);
    teddyButton.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 Radio Button API

See The Button API for information on the AbstractButton API that JRadioButton and JRadioButtonMenuItem inherit. The AbstractButton methods that you're most likely to use are setMnemonic, addItemListener, setSelected, and isSelected. The most commonly used pieces of the radio button API fall into two groups:

• Commonly used ButtonGroup constructors/methods
• Radio button 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 Radio Buttons

The following examples use radio buttons either as buttons or as menu items.

Example	Where Described	Notes
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 the JFC/Swing Packages