The JFC Swing Tutorial: A Guide to Constructing GUIs (2nd Edition)

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 ^[111] and ButtonGroup ^[112] classes. To put a radio button in a menu, use the JRadioButtonMenuItem ^[113] 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.

^[111] JRadioButton API documentation: http://java.sun.com/j2se/1.4.2/docs/api/javax/swing/JRadioButton.html.

^[112] ButtonGroup API documentation: http://java.sun.com/j2se/1.4.2/docs/api/javax/swing/ButtonGroup.html.

^[113] JRadioButtonMenuItem API documentation: http://java.sun.com/j2se/1.4.2/docs/api/javax/swing/JRadioButtonMenuItem.html.

Because JRadioButton inherits from AbstractButton , Swing radio buttons have all the usual button characteristics, as discussed earlier in How to Use Buttons (page 156). For example, you can specify the image displayed in a radio button.

Figure 45 is a picture of an application that uses five radio buttons to let you choose which kind of pet is displayed.

Try This:

1. Run RadioButtonDemo using Java Web Start or compile and run the example yourself. [114] [114] To run RadioButtonDemo using Java Web Start, click the RadioButtonDemo link on the RunExamples/ components .html page on the CD. You can find the source files here: JavaTutorial/uiswing/components/example-1dot4/index.html#RadioButtonDemo .

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 occurone 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(KeyEvent.VK_B); birdButton.setActionCommand(birdString); birdButton.setSelected(true); JRadioButton catButton = new JRadioButton(catString); catButton.setMnemonic(KeyEvent.VK_C); catButton.setActionCommand(catString); JRadioButton dogButton = new JRadioButton(dogString); dogButton.setMnemonic(KeyEvent.VK_D); dogButton.setActionCommand(dogString); JRadioButton rabbitButton = new JRadioButton(rabbitString); rabbitButton.setMnemonic(KeyEvent.VK_R); rabbitButton.setActionCommand(rabbitString); JRadioButton pigButton = new JRadioButton(pigString); pigButton.setMnemonic(KeyEvent.VK_P); 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. birdButton.addActionListener(this); catButton.addActionListener(this); dogButton.addActionListener(this); rabbitButton.addActionListener(this); pigButton.addActionListener(this); .. 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 previously selected button 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 rulea group of radio buttons can have no initial selection. Once the user has made a selection, exactly one button is selected from then on. There's no supported API for unselecting all the buttons.

Version Note: In versions prior to 1.4, invoking setSelected(null, true) on the ButtonGroup happened to deselect all the buttons. It no longer does so.

The Radio Button API

Tables 62 and 63 list the commonly used radio button- related API. Also consult the tables in The Button API (page 160) for methods inherited from AbstractButton . Other methods you might call, such as setFont and setForeground , are listed in the API tables in The JComponent Class (page 53). Also refer to the API documentation for JRadioButton and JRadioButtonMenuItem at:

http://java.sun.com/j2se/1.4.2/docs/api/javax/swing/JRadioButton.html

http://java.sun.com/j2se/1.4.2/docs/api/javax/swing/JRadioButtonMenuItem.html

Table 62. Radio Button Constructors

Table 63. Commonly Used Button Group Constructors and Methods

Examples That Use Radio Buttons

The following examples use radio buttons.