We start our discussion of graphical user interfaces with text input. Of course, a graphical application can receive text input by calling the showInputDialog method of the JOptionPane class, but popping up a separate dialog box for each input is not a natural user interface. Most graphical programs collect text input through text fields (see Figure 1). In this section, you will learn how to add text fields to a graphical application, and how to read what the user types into them.

The JTextField class provides a text field. When you construct a text field, you need to supply the width—the approximate number of characters that you expect the user to type.

final int FIELD_WIDTH = 10;
final JTextField rateField = new JTextField(FIELD_WIDTH);

Users can type additional characters, but then a part of the contents of the field becomes invisible.

You will want to label each text field so that the user knows what to type into it. Construct a JLabel object for each label:

JLabel rateLabel = new JLabel("Interest Rate: ");

You want to give the user an opportunity to enter all information into the text fields before processing it. Therefore, you should supply a button that the user can press to indicate that the input is ready for processing.

When that button is clicked, its actionPerformed method reads the user input from the text field, using the getText method of the JTextField class. The getText method returns a String object. In our sample program, we turn the string into a number, using the Double.parseDouble method. After updating the account, we show the balance in another label.

class AddInterestListener implements ActionListener
{
   public void actionPerformed(ActionEvent event)
   {
      double rate = Double.parseDouble(rateField.getText());
      double interest = account.getBalance() * rate / 100;
      account.deposit(interest);
      resultLabel.setText("balance: " + account.getBalance());
   }
}

The following application is a useful prototype for a graphical user-interface front end for arbitrary calculations. You can easily modify it for your own needs. Place other input components into the frame. Change the contents of the actionPerformed method to carry out other calculations. Display the result in a label.

Figure 18.1. An Application with a Text Field

ch18/textfield/InvestmentViewer3.java

1  import javax.swing.JFrame;
2
3  /**
4     This program displays the growth of an investment.
5  */
6  public class InvestmentViewer3
7  {
8     public static void main(String[] args)
9     {
10       JFrame frame = new InvestmentFrame();
11       frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
12       frame.setVisible(true);
13  }
14 }

ch18/textfield/InvestmentFrame.java

1  import java.awt.event.ActionEvent;
2  import java.awt.event.ActionListener;
3  import javax.swing.JButton;
4  import javax.swing.JFrame;
5  import javax.swing.JLabel;
6  import javax.swing.JPanel;
7  import javax.swing.JTextField;
8
9  /**
10    A frame that shows the growth of an investment with variable interest.
11  */
12  public class InvestmentFrame extends JFrame
13  {
14    private static final int FRAME_WIDTH = 450;
15    private static final int FRAME_HEIGHT = 100;
16
17    private static final double DEFAULT_RATE = 5;
18    private static final double INITIAL_BALANCE = 1000;
19
20    private JLabel rateLabel;
21    private JTextField rateField;
22    private JButton button;
23    private JLabel resultLabel;
24    private JPanel panel;
25    private BankAccount account;
26

27    public InvestmentFrame()
28    {
29      account = new BankAccount(INITIAL_BALANCE);
30
31      // Use instance variables for components
32      resultLabel = new JLabel("balance: " + account.getBalance());
33
34      // Use helper methods
35      createTextField();
36      createButton();
37      createPanel();
38
39      setSize(FRAME_WIDTH, FRAME_HEIGHT);
40   }
41
42      private void createTextField()
43      {
44          rateLabel = new JLabel("Interest Rate: ");
45
46          final int FIELD_WIDTH = 10;
47          rateField = new JTextField(FIELD_WIDTH);
48          rateField.setText("" + DEFAULT_RATE);
49      }
50
51      private void createButton()
52      {
53          button = new JButton("Add Interest");
54
55          class AddInterestListener implements ActionListener
56          {
57             public void actionPerformed(ActionEvent event)
58             {
59                double rate = Double.parseDouble(rateField.getText());
60                double interest = account.getBalance() * rate / 100;
61                account.deposit(interest);
62                resultLabel.setText("balance: " + account.getBalance());
63             }
64          }
65
66           ActionListener listener = new AddInterestListener();
67           button.addActionListener(listener);
68      }
69
70      private void createPanel()
71      {
72            panel = new JPanel();
73            panel.add(rateLabel);
74            panel.add(rateField);
75            panel.add(button);
76          panel.add(resultLabel);
77          add(panel);
78      }
79   }

2. If a text field holds an integer, what expression do you use to read its contents?

In the preceding section, you saw how to construct text fields. A text field holds a single line of text. To display multiple lines of text, use the JTextArea class.

When constructing a text area, you can specify the number of rows and columns:

final int ROWS = 10;
final int COLUMNS = 30;
JTextArea textArea = new JTextArea(ROWS, COLUMNS);

Use the setText method to set the text of a text field or text area. The append method adds text to the end of a text area. Use newline characters to separate lines, like this:

textArea.append(account.getBalance() + "
");

If you want to use a text field or text area for display purposes only, call the setEditable method like this

textArea.setEditable(false);

Now the user can no longer edit the contents of the field, but your program can still call setText and append to change it.

As shown in Figure 2, the JTextField and JTextArea classes are subclasses of the class JTextComponent. The methods setText and setEditable are declared in the JText-Component class and inherited by JTextField and JTextArea. However, the append method is declared in the JTextArea class.

Figure 18.2. A Part of the Hierarchy of Swing User-Interface Components

Figure 18.3. The Investment Application with a Text Area

To add scroll bars to a text area, use a JScrollPane, like this:

JTextArea textArea = new JTextArea(ROWS, COLUMNS);
JScrollPane scrollPane = new JScrollPane(textArea);

Then add the scroll pane to the panel. Figure 3 shows the result.

The following sample program puts these concepts together. A user can enter numbers into the interest rate text field and then click on the "Add Interest" button). The interest rate is applied, and the updated balance is appended to the text area. The text area has scroll bars and is not editable.

This program is similar to the previous investment viewer program, but it keeps track of all the bank balances, not just the last one.

ch18/textarea/InvestmentFrame.java

1  import java.awt.event.ActionEvent;
2  import java.awt.event.ActionListener;
3  import javax.swing.JButton;
4  import javax.swing.JFrame;
5  import javax.swing.JLabel;
6  import javax.swing.JPanel;
7  import javax.swing.JScrollPane;
8  import javax.swing.JTextArea;
9  import javax.swing.JTextField;
10
11  /**
12     A frame that shows the growth of an investment with variable interest.
13  */
14  public class InvestmentFrame extends JFrame
15  {
16     private static final int FRAME_WIDTH = 400;
17     private static final int FRAME_HEIGHT = 250;
18
19     private static final int AREA_ROWS = 10;
20     private static final int AREA_COLUMNS = 30;
21     private static final double DEFAULT_RATE = 5;
22     private static final double INITIAL_BALANCE = 1000;
23
24     private JLabel rateLabel;
25     private JTextField rateField;
26     private JButton button;

27     private JTextArea resultArea;
28     private JPanel panel;
29     private BankAccount account;
30
31     public InvestmentFrame()
32     {
33        account = new BankAccount(INITIAL_BALANCE);
34        resultArea = new JTextArea(AREA_ROWS, AREA_COLUMNS);
35        resultArea.setEditable(false);
36
37        // Use helper methods
38        createTextField();
39        createButton();
40        createPanel();
41
42        setSize(FRAME_WIDTH, FRAME_HEIGHT);
43     }
44
45     private void createTextField()
46     {
47        rateLabel = new JLabel("Interest Rate: ");
48
49        final int FIELD_WIDTH = 10;
50        rateField = new JTextField(FIELD_WIDTH);
51        rateField.setText("" + DEFAULT_RATE);
52     }
53
54     private void createButton()
55     {
56        button = new JButton("Add Interest");
57
58     class AddInterestListener implements ActionListener
59        {
60             public void actionPerformed(ActionEvent event)
61             {
62                double rate = Double.parseDouble(rateField.getText());
63                double interest = account.getBalance() * rate / 100;
64                account.deposit(interest);
65                resultArea.append(account.getBalance() + "
");
66             }
67        }
68
69             ActionListener listener = new AddInterestListener();
70             button.addActionListener(listener);
71       }
72
73       private void createPanel()
74       {
75            panel = new JPanel();
76            panel.add(rateLabel);
77            panel.add(rateField);
78            panel.add(button);
79            JScrollPane scrollPane = new JScrollPane(resultArea);
80            panel.add(scrollPane);
81            add(panel);
82       }
83   }

3. What is the difference between a text field and a text area?

4. Why did the InvestmentFrame program call resultArea.setEditable(false)?

5. How would you modify the InvestmentFrame program if you didn't want to use scroll bars?

Up to now, you have had limited control over the layout of user-interface components. You learned how to add components to a panel. The panel arranged the components from the left to the right. However, in many applications, you need more sophisticated arrangements.

In Java, you build up user interfaces by adding components into containers such as panels. Each container has its own layout manager, which determines how the components are laid out.

By default, a JPanel uses a flow layout. A flow layout simply arranges its components from left to right and starts a new row when there is no more room in the current row.

Another commonly used layout manager is the border layout. The border layout groups components into five areas: center, north, west, south, and east (see Figure 4). Not all of the areas need to be occupied.

The border layout is the default layout manager for a frame (or, more technically, the frame's content pane). But you can also use the border layout in a panel:

panel.setLayout(new BorderLayout());

Now the panel is controlled by a border layout, not the flow layout. When adding a component, you specify the position, like this:

panel.add(component, BorderLayout.NORTH);

The grid layout is a third layout that is sometimes useful. The grid layout arranges components in a grid with a fixed number of rows and columns, resizing each of the components so that they all have the same size. Like the border layout, it also expands each component to fill the entire allotted area. (If that is not desirable, you need to place each component inside a panel.) Figure 5 shows a number pad panel that uses a grid layout. To create a grid layout, you supply the number of rows and columns in the constructor, then add the components, row by row, left to right:

Figure 18.4. Components Expand to Fill Space in the Border Layout

Figure 18.5. The Grid Layout

JPanel buttonPanel = new JPanel();
buttonPanel.setLayout(new GridLayout(4, 3));
buttonPanel.add(button7);
buttonPanel.add(button8);
buttonPanel.add(button9);
buttonPanel.add(button4);
...

Sometimes you want to have a tabular arrangement of the components where columns have different sizes or one component spans multiple columns. A more complex layout manager called the grid bag layout can handle these situations. The grid bag layout is quite complex to use, however, and we do not cover it in this book; see, for example, Cay S. Horstmann and Gary Cornell, Core Java 2 Volume 1: Fundamentals,8th edition (Prentice Hall, 2008), for more information. Java 6 introduces a group layout that is designed for use by interactive tools—see Productivity Hint 18.1 on page 757.

Fortunately, you can create acceptable-looking layouts in nearly all situations by nesting panels. You give each panel an appropriate layout manager. Panels don't have visible borders, so you can use as many panels as you need to organize your components. Figure 6 shows an example. The keypad buttons are contained in a panel with grid layout. That panel is itself contained in a larger panel with border layout. The text field is in the northern position of the larger panel. The following code produces this arrangement:

JPanel keypadPanel = new JPanel();
keypadPanel.setLayout(new BorderLayout());
buttonPanel = new JPanel();
buttonPanel.setLayout(new GridLayout(4, 3));
buttonPanel.add(button7);
buttonPanel.add(button8);
// ...
keypadPanel.add(buttonPanel, BorderLayout.CENTER);
JTextField display = new JTextField();
keypadPanel.add(display, BorderLayout.NORTH);

Figure 18.6. Nesting Panels

7. How can you stack three buttons on top of each other?

In the following sections, you will see how to present a finite set of choices to the user. Which Swing component you use depends on whether the choices are mutually exclusive or not, and on the amount of space you have for displaying the choices.

Radio Buttons

If the choices are mutually exclusive, use a set of radio buttons. In a radio button set, only one button can be selected at a time. When the user selects another button in the same set, the previously selected button is automatically turned off. (These buttons are called radio buttons because they work like the station selector buttons on a car radio: If you select a new station, the old station is automatically deselected.) For example, in Figure 7, the font sizes are mutually exclusive. You can select small, medium, or large, but not a combination of them.

Note

For a small set of mutually exclusive choices, use a group of radio buttons or a combo box.

To create a set of radio buttons, first create each button individually, and then add all buttons of the set to a ButtonGroup object:

JRadioButton smallButton = new JRadioButton("Small");
JRadioButton mediumButton = new JRadioButton("Medium");
JRadioButton largeButton = new JRadioButton("Large");

ButtonGroup group = new ButtonGroup();
group.add(smallButton);
group.add(mediumButton);
group.add(largeButton);

Note

Add radio buttons into a ButtonGroup so that only one button in the group is on at any time.

Note that the button group does not place the buttons close to each other on the container. The purpose of the button group is simply to find out which buttons to turn off when one of them is turned on. It is still your job to arrange the buttons on the screen.

The isSelected method is called to find out whether a button is currently selected or not. For example,

if (largeButton.isSelected()) { size = LARGE_SIZE; }

Because users will expect one radio button in a radio button group to be selected, call setSelected(true) on the default radio button before making the enclosing frame visible.

If you have multiple button groups, it is a good idea to group them together visually. It is a good idea to use a panel for each set of radio buttons, but the panels themselves are invisible. You can add a border to a panel to make it visible. In Figure 7, for example, the panels containing the Size radio buttons and Style check boxes have borders.

Note

You can place a border around a panel to group its contents visually.

There are a large number of border types. We will show only a couple of variations and leave it to the border enthusiasts to look up the others in the Swing documentation. The EtchedBorder class yields a border with a three-dimensional, etched effect. You can add a border to any component, but most commonly you apply it to a panel:

JPanel panel = new JPanel();
panel.setBorder(new EtchedBorder());

Figure 18.7. A Combo Box, Check Boxes, and Radio Buttons

If you want to add a title to the border (as in Figure 7), you need to construct a TitledBorder. You make a titled border by supplying a basic border and then the title you want. Here is a typical example:

panel.setBorder(new TitledBorder(new EtchedBorder(), "Size"));

JCheckBox italicCheckBox = new JCheckBox("Italic");

Combo Boxes

If you have a large number of choices, you don't want to make a set of radio buttons, because that would take up a lot of space. Instead, you can use a combo box. This component is called a combo box because it is a combination of a list and a text field. The text field displays the name of the current selection. When you click on the arrow to the right of the text field of a combo box, a list of selections drops down, and you can choose one of the items in the list (see Figure 8).

Note

For a large set of choices, use a combo box.

Figure 18.8. An Open Combo Box

If the combo box is editable, you can also type in your own selection. To make a combo box editable, call the setEditable method.

You add strings to a combo box with the addItem method.

JComboBox facenameCombo = new JComboBox();
facenameCombo.addItem("Serif");
facenameCombo.addItem("SansSerif");
...

You get the item that the user has selected by calling the getSelectedItem method. However, because combo boxes can store other objects in addition to strings, the getSelectedItem method has return type Object. Hence you must cast the returned value back to String.

String selectedString = (String) facenameCombo.getSelectedItem();

Figure 18.9. The Components of the FontViewerFrame

Figure 18.10. Classes of the Font Viewer Program

You can select an item for the user with the setSelectedItem method.

Radio buttons, check boxes, and combo boxes generate an ActionEvent whenever the user selects an item. In the following program, we don't care which component was clicked—all components notify the same listener object. Whenever the user clicks on any one of them, we simply ask each component for its current content, using the isSelected and getSelectedItem methods. We then redraw the text sample with the new font.

Figure 9 shows how the components are arranged in the frame. Figure 10 shows the relationships between the classes used in the font viewer program.

Note

Radio buttons, check boxes, and combo boxes generate action events, just as buttons do.

ch18/choice/FontViewer.java

1  import javax.swing.JFrame;
2
3  /**
4     This program allows the user to view font effects.
5  */
6  public class FontViewer
7  {
8     public static void main(String[] args)
9     {
10       JFrame frame = new FontViewerFrame();
11       frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
12       frame.setTitle("FontViewer");
13       frame.setVisible(true);
14     }
15  }

ch18/choice/FontViewerFrame.java

1   import java.awt.BorderLayout;
2   import java.awt.Font;
3   import java.awt.GridLayout;
4   import java.awt.event.ActionEvent;
5   import java.awt.event.ActionListener;
6   import javax.swing.ButtonGroup;
7   import javax.swing.JButton;
8   import javax.swing.JCheckBox;
9   import javax.swing.JComboBox;
10   import javax.swing.JFrame;
11   import javax.swing.JLabel;
12   import javax.swing.JPanel;
13   import javax.swing.JRadioButton;
14   import javax.swing.border.EtchedBorder;
15   import javax.swing.border.TitledBorder;
16
17   /**
18      This frame contains a text field and a control panel
19      to change the font of the text.
20   */
21   public class FontViewerFrame extends JFrame
22   {
23      private static final int FRAME_WIDTH = 300;
24      private static final int FRAME_HEIGHT = 400;
25
26      private JLabel sampleField;
27      private JCheckBox italicCheckBox;
28      private JCheckBox boldCheckBox;
29      private JRadioButton smallButton;
30      private JRadioButton mediumButton;
31      private JRadioButton largeButton;
32      private JComboBox facenameCombo;
33      private ActionListener listener;
34
35      /**
36         Constructs the frame.
37      */
38      public FontViewerFrame()
39      {
40         // Construct text sample
41         sampleField = new JLabel("Big Java");
42         add(sampleField, BorderLayout.CENTER);
43
44         // This listener is shared among all components
45         class ChoiceListener implements ActionListener
46         {
47            public void actionPerformed(ActionEvent event)
48            {
49               setSampleFont();
50            }
51         }
52
53         listener = new ChoiceListener();
54
55         createControlPanel();
56         setSampleFont();
57         setSize(FRAME_WIDTH, FRAME_HEIGHT);
58      }

59
60     /**
61        Creates the control panel to change the font.
62     */
63     public void createControlPanel()
64     {
65       JPanel facenamePanel = createComboBox();
66       JPanel sizeGroupPanel = createCheckBoxes();
67       JPanel styleGroupPanel = createRadioButtons();
68
69       //   Line up component panels
70
71       JPanel controlPanel = new JPanel();
72       controlPanel.setLayout(new GridLayout(3, 1));
73       controlPanel.add(facenamePanel);
74       controlPanel.add(sizeGroupPanel);
75       controlPanel.add(styleGroupPanel);
76
77       //  Add panels to content pane
78
79        add(controlPanel, BorderLayout.SOUTH);
80     }
81
82     /**
83        Creates the combo box with the font style choices.
84        @return  the panel containing the combo box
85     */
86     public JPanel createComboBox()
87      {
88        facenameCombo = new JComboBox();
89        facenameCombo.addItem("Serif");
90        facenameCombo.addItem("SansSerif");
91        facenameCombo.addItem("Monospaced");
92        facenameCombo.setEditable(true);
93        facenameCombo.addActionListener(listener);
94
95        JPanel panel = new JPanel();
96        panel.add(facenameCombo);
97        return panel;
98     }
99
100     /**
101        Creates the check boxes for selecting bold and italic styles.
102        @return  the panel containing the check boxes
103     */
104     public JPanel createCheckBoxes()
105     {
106         italicCheckBox = new JCheckBox("Italic");
107         italicCheckBox.addActionListener(listener);
108
109        boldCheckBox = new JCheckBox("Bold");
110         boldCheckBox.addActionListener(listener);
111
112        JPanel panel = new JPanel();
113        panel.add(italicCheckBox);
114        panel.add(boldCheckBox);
115        panel.setBorder(new TitledBorder(new EtchedBorder(), "Style"));
116
117        return panel;

118     }
119
120     /**
121        Creates the radio buttons to select the font size.
122        @return the panel containing the radio buttons
123     */
124     public JPanel createRadioButtons()
125     {
126        smallButton = new JRadioButton("Small");
127        smallButton.addActionListener(listener);
128
129        mediumButton = new JRadioButton("Medium");
130        mediumButton.addActionListener(listener);
131
132        largeButton = new JRadioButton("Large");
133        largeButton.addActionListener(listener);
134        largeButton.setSelected(true);
135
136        // Add radio buttons to button group
137
138        ButtonGroup group = new ButtonGroup();
139        group.add(smallButton);
140        group.add(mediumButton);
141        group.add(largeButton);
142
143        JPanel panel = new JPanel();
144        panel.add(smallButton);
145        panel.add(mediumButton);
146        panel.add(largeButton);
147        panel.setBorder(new TitledBorder(new EtchedBorder(), "Size"));
148
149        return panel;
150     }
151
152     /**
153        Gets user choice for font name, style, and size
154        and sets the font of the text sample.
155     */
156     public void setSampleFont()
157
158        // Get font name
159        String facename
160               = (String) facenameCombo.getSelectedItem();
161
162        // Get font style
163
164        int style = 0;
165        if (italicCheckBox.isSelected())
166        {
167           style = style + Font.ITALIC;
168        }
169        if (boldCheckBox.isSelected())
170        {
171           style = style + Font.BOLD;
172        }
173
174        // Get font size
175
176        int size = 0;

177
178        final int SMALL_SIZE = 24;
179        final int MEDIUM_SIZE = 36;
180        final int LARGE_SIZE = 48;
181
182        if (smallButton.isSelected()) { size = SMALL_SIZE; }
183        else if (mediumButton.isSelected()) { size = MEDIUM_SIZE; }
184        else if (largeButton.isSelected()) { size = LARGE_SIZE; }
185
186        //  Set font of text field
187
188        sampleField.setFont(new Font(facename, style, size));
189        sampleField.repaint();
190        }
191    }

9. Why do all user-interface components in the FontViewerFrame class share the same listener?

10. Why was the combo box placed inside a panel? What would have happened if it had been added directly to the control panel?

Laying Out a User Interface

A graphical user interface is made up of components such as buttons and text fields. The Swing library uses containers and layout managers to arrange these components. This How To explains how to group components into containers and how to pick the right layout managers.

• Step 1 Make a sketch of your desired component layout.

  Draw all the buttons, labels, text fields, and borders on a sheet of paper. Graph paper works best.

  Here is an example—a user interface for ordering pizza. The user interface contains

  • Three radio buttons

  • Two check boxes

  • A label: "Your Price:"

  • A text field

  • A border

  

• Step 2 Find groupings of adjacent components with the same layout.

  Usually, the component arrangement is complex enough that you need to use several panels, each with its own layout manager. Start by looking at adjacent components that are arranged top to bottom or left to right. If several components are surrounded by a border, they should be grouped together.

  Here are the groupings from the pizza user interface:

  

• Step 3 Identify layouts for each group.

  When components are arranged horizontally, choose a flow layout. When components are arranged vertically, use a grid layout with one column.

  In the pizza user interface example, you would choose

  • A (3, 1) grid layout for the radio buttons

  • A (2, 1) grid layout for the check boxes

  • A flow layout for the label and text field

• Step 4 Group the groups together.

• Look at each group as one blob, and group the blobs together into larger groups, just as you grouped the components in the preceding step. If you note one large blob surrounded by smaller blobs, you can group them together in a border layout.

  You may have to repeat the grouping again if you have a very complex user interface. You are done if you have arranged all groups in a single container.

  For example, the three component groups of the pizza user interface can be arranged as:

  • A group containing the first two component groups, placed in the center of a container with a border layout.

  • The third component group, in the southern area of that container.

  

  In this step, you may run into a couple of complications. The group "blobs" tend to vary in size more than the individual components. If you place them inside a grid layout, the grid layout forces them all to be the same size. Also, you occasionally would like a component from one group to line up with a component from another group, but there is no way for you to communicate that intent to the layout managers.

  These problems can be overcome by using more sophisticated layout managers or implementing a custom layout manager. However, those techniques are beyond the scope of this book. Sometimes, you may want to start over with Step 1, using a component layout that is easier to manage. Or you can decide to live with minor imperfections of the layout. Don't worry about achieving the perfect layout—after all, you are learning programming, not user-interface design.

• Step 5 Write the code to generate the layout.

  This step is straightforward but potentially tedious, especially if you have a large number of components.

  Start by constructing the components. Then construct a panel for each component group and set its layout manager if it is not a flow layout (the default for panels). Add a border to the panel if required. Finally, add the components to their panels. Continue in this fashion until you reach the outermost containers, which you add to the frame.

  Here is an outline of the code required for the pizza user interface.

  JPanel radioButtonPanel = new JPanel();
  radioButtonPanel.setLayout(new GridLayout(3, 1));
  radioButton.setBorder(new TitledBorder(new EtchedBorder(), "Size"));
  radioButtonPanel.add(smallButton);
  radioButtonPanel.add(mediumButton);
  radioButtonPanel.add(largeButton);
  
  JPanel checkBoxPanel = new JPanel();
  checkBoxPanel.setLayout(new GridLayout(2, 1));
  checkBoxPanel.add(pepperoniButton());
  checkBoxPanel.add(anchoviesButton());
  
  JPanel pricePanel = new JPanel(); // Uses FlowLayout by default
  pricePanel.add(new JLabel("Your Price:"));
  pricePanel.add(priceTextField);
  
  JPanel centerPanel = new JPanel(); // Uses FlowLayout
  centerPanel.add(radioButtonPanel);
  centerPanel.add(checkBoxPanel);
  
  // Frame uses BorderLayout by default
  add(centerPanel, BorderLayout.CENTER);
  add(pricePanel, BorderLayout.SOUTH);

  Of course, you also need to add event handlers to the components. See How To 10.1.

Use a GUI Builder

As you have seen, implementing even a simple graphical user interface in Java is quite tedious. You have to write a lot of code for constructing components, using layout managers, and providing event handlers. Most of the code is boring and repetitive.

A GUI builder takes away much of the tedium. Most GUI builders help you in three ways:

• You drag and drop components onto a panel. The GUI builder writes the layout management code for you.

• You customize components with a dialog box, setting properties such as fonts, colors, text, and so on. The GUI builder writes the customization code for you.

• You provide event handlers by picking the event to process and providing just the code snippet for the listener method. The GUI builder writes the boilerplate code for attaching a listener object.

Java 6 introduced GroupLayout, a powerful layout manager that was specifically designed to be used by GUI builders. The free NetBeans development environment, available from http://netbeans.org, makes use of this layout manager—see Figure 11.

If you need to build a complex user interface, you will find that learning to use a GUI builder is a very worthwhile investment. You will spend less time writing boring code, and you will have more fun designing your user interface and focusing on the functionality of your program.

Figure 18.11. A GUI Builder

Anyone who has ever used a graphical user interface is familiar with pull-down menus (see Figure 12). In Java it is easy to create these menus.

The container for the top-level menu items is called a menu bar. A menu is a collection of menu items and more menus (submenus). You add menu items and sub-menus with the add method:

JMenuItem fileExitItem = new JMenuItem("Exit");
fileMenu.add(fileExitItem);

A menu item has no further submenus. When the user selects a menu item, the menu item sends an action event. Therefore, you want to add a listener to each menu item:

fileExitItem.addActionListener(listener);

You add action listeners only to menu items, not to menus or the menu bar. When the user clicks on a menu name and a submenu opens, no action event is sent.

Figure 18.12. Pull-Down Menus Menu bar

The following program builds up a small but typical menu and traps the action events from the menu items. To keep the program readable, it is a good idea to use a separate method for each menu or set of related menus. Have a look at the create-FaceItem method, which creates a menu item to change the font face. The same listener class takes care of three cases, with the name parameters varying for each menu item. The same strategy is used for the createSizeItem and createStyleItem methods.

ch18/menu/FontViewer2.java

1  import javax.swing.JFrame;
2
3  /**
4     This program uses a menu to display font effects.
5  */
6  public class FontViewer2
7  {
8     public static void main(String[] args)
9     {
10       JFrame frame = new FontViewer2Frame();
11       frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
12       frame.setVisible(true);
13     }
14  }

ch18/menu/FontViewer2Frame.java

1  import java.awt.BorderLayout;
2  import java.awt.Font;
3  import java.awt.GridLayout;
4  import java.awt.event.ActionEvent;
5  import java.awt.event.ActionListener;
6  import javax.swing.ButtonGroup;
7  import javax.swing.JButton;
8  import javax.swing.JCheckBox;
9  import javax.swing.JComboBox;
10  import javax.swing.JFrame;

11  import javax.swing.JLabel;
12  import javax.swing.JMenu;
13  import javax.swing.JMenuBar;
14  import javax.swing.JMenuItem;
15  import javax.swing.JPanel;
16  import javax.swing.JRadioButton;
17  import javax.swing.border.EtchedBorder;
18  import javax.swing.border.TitledBorder;
19
20  /**
21     This frame has a menu with commands to change the font
22      of a text sample.
23  */
24  public class FontViewer2Frame extends JFrame
25  {
26     private static final int FRAME_WIDTH = 300;
27     private static final int FRAME_HEIGHT = 400;
28
29     private JLabel sampleField;
30     private String facename;
31     private int fontstyle;
32     private int fontsize;
33
34     /**
35        Constructs the frame.
36     */
37     public FontViewer2Frame()
38     {
39        // Construct text sample
40        sampleField = new JLabel("Big Java");
41        add(sampleField, BorderLayout.CENTER);
42
43        // Construct menu
44        JMenuBar menuBar = new JMenuBar();
45        setJMenuBar(menuBar);
46        menuBar.add(createFileMenu());
47        menuBar.add(createFontMenu());
48
49        facename = "Serif";
50        fontsize = 24;
51        fontstyle = Font.PLAIN;
52
53        setSampleFont();
54        setSize(FRAME_WIDTH, FRAME_HEIGHT);
55     }
56
57     /**
58        Creates the File menu.
59        @return the menu
60     */
61     public JMenu createFileMenu()
62
63     {
64          JMenu menu = new JMenu("File");
65          menu.add(createFileExitItem());
66          return menu;
67     }
68

69    /**
70      Creates the File->Exit menu item and sets its action listener.
71      @return  the menu item
72    */
73    public JMenuItem createFileExitItem()
74    {
75      JMenuItem item = new JMenuItem("Exit");
76      class MenuItemListener implements ActionListener
77       {
78          public void actionPerformed(ActionEvent event)
79          {
80             System.exit(0);
81          }
82      }
83      ActionListener listener = new MenuItemListener();
84      item.addActionListener(listener);
85      return item;
86    }
87
88    /**
89      Creates the Font submenu.
90      @return  the menu
91    */
92    public JMenu createFontMenu()
93    {
94      JMenu menu = new JMenu("Font");
95      menu.add(createFaceMenu());
96      menu.add(createSizeMenu());
97      menu.add(createStyleMenu());
98      return menu;
99    }
100
101    /**
102      Creates the Face submenu.
103      @return  the menu
104    */
105    public JMenu createFaceMenu()
106    {
107      JMenu menu = new JMenu("Face");
108      menu.add(createFaceItem("Serif"));
109      menu.add(createFaceItem("SansSerif"));
110      menu.add(createFaceItem("Monospaced"));
111      return menu;
112    }
113
114     /**
115      Creates the Size submenu.
116      @return  the menu
117    */
118    public JMenu createSizeMenu()
119    {
120      JMenu menu = new JMenu("Size");
121      menu.add(createSizeItem("Smaller", −1));
122      menu.add(createSizeItem("Larger", 1));
123      return menu;
124    }
125

126    /**
127       Creates the Style submenu.
128       @return the menu
129    */
130    public JMenu createStyleMenu()
131    {
132       JMenu menu = new JMenu("Style");
133               menu.add(createStyleItem("Plain", Font.PLAIN));
134       menu.add(createStyleItem("Bold", Font.BOLD));
135               menu.add(createStyleItem("Italic", Font.ITALIC));
136       menu.add(createStyleItem("Bold Italic", Font.BOLD
137                  + Font.ITALIC));
138       return menu;
139    }
140
141    /**
142       Creates a menu item to change the font face and set its action listener.
143       @param name the name of the font face
144       @return the menu item
145    */
146    public JMenuItem createFaceItem(final String name)
147    {
148       JMenuItem item = new JMenuItem(name);
149       class MenuItemListener implements ActionListener
150       {
151           public void actionPerformed(ActionEvent event)
152           {
153               facename = name;
154               setSampleFont();
155           }
156       }
157       ActionListener listener = new MenuItemListener();
158       item.addActionListener(listener);
159       return item;
160    }
161
162    /**
163       Creates a menu item to change the font size
164       and set its action listener.
165       @param name the name of the menu item
166       @param ds  the amount by which to change the size
167       @return  the menu item
168    */
169    public JMenuItem createSizeItem(String name, final int ds)
170    {
171          JMenuItem item = new JMenuItem(name);
172          class MenuItemListener implements ActionListener
173          {
174              public void actionPerformed(ActionEvent event)
175              {
176               fontsize = fontsize + ds;
177               setSampleFont();
178              }
179          }
180             ActionListener listener = new MenuItemListener();
181             item.addActionListener(listener);
182             return item;
183    }
184

185    /**
186       Creates a menu item to change the font style
187        and set its action listener.
188       @param name the name of the menu item
189       @param style the new font style
190       @return the menu item
191    */
192    public JMenuItem createStyleItem(String name, final int style)
193    {
194       JMenuItem item = new JMenuItem(name);
195       class MenuItemListener implements ActionListener
196       {
197           public void actionPerformed(ActionEvent event)
198           {
199              fontstyle = style;
200              setSampleFont();
201           }
202       }
203           ActionListener listener = new MenuItemListener();
204           item.addActionListener(listener);
205           return item;
206    }
207
208    /**
209       Sets the font of the text sample.
210    */
211    public void setSampleFont()
212    {
213           Font f = new Font(facename, fontstyle, fontsize);
214           sampleField.setFont(f);
215           sampleField.repaint();
216       }
217    }

12. Why is the name parameter in the createFaceItem method declared as final?

In the preceding sections, you saw the basic properties of the most common user-interface components. We purposefully omitted many options and variations to simplify the discussion. You can go a long way by using only the simplest properties of these components. If you want to implement a more sophisticated effect, you can look inside the Swing documentation. You will probably find the documentation quite intimidating at first glance, though. The purpose of this section is to show you how you can use the documentation to your advantage without becoming overwhelmed.

As an example, consider a program for mixing colors by specifying the red, green, and blue values. How can you specify the colors? Of course, you could supply three text fields, but sliders would be more convenient for users of your program (see Figure 13).

The Swing user-interface toolkit has a large set of user-interface components. How do you know if there is a slider? You can buy a book that illustrates all Swing components. Or you can run the sample application included in the Java Development Kit that shows off all Swing components (see Figure 14). Or you can look at the names of all of the classes that start with J and decide that JSlider may be a good candidate.

Figure 18.13. A Color Viewer

Figure 18.14. The SwingSet Demo

Next, you need to ask yourself a few questions:

When you look at the documentation of the JSlider class, you will probably not be happy. There are over 50 methods in the JSlider class and over 250 inherited methods, and some of the method descriptions look downright scary, such as the one in Figure 15. Apparently some folks out there are concerned about the valueIs-Adjusting property, whatever that may be, and the designers of this class felt it necessary to supply a method to tweak that property. Until you too feel that need, your best bet is to ignore this method. As the author of an introductory book, it pains me to tell you to ignore certain facts. But the truth of the matter is that the Java library is so large and complex that nobody understands it in its entirety, not even the designers of Java themselves. You need to develop the ability to separate fundamental concepts from ephemeral minutiae. For example, it is important that you understand the concept of event handling. Once you understand the concept, you can ask the question, "What event does the slider send when the user moves it?" But it is not important that you memorize how to set tick marks or that you know how to implement a slider with a custom look and feel.

Let us go back to our fundamental questions. In Java 6, there are six constructors for the JSlider class. You want to learn about one or two of them. You must strike a balance somewhere between the trivial and the bizarre. Consider

public JSlider()
     Creates a horizontal slider with the range 0 to 100 and an initial value of 50.

Maybe that is good enough for now, but what if you want another range or initial value? It seems too limited.

On the other side of the spectrum, there is

public JSlider(BoundedRangeModel brm)
     Creates a horizontal slider using the specified BoundedRangeModel.

Figure 18.15. A Mysterious Method Description from the API Documentation

Whoa! What is that? You can click on the BoundedRangeModel link to get a long explanation of this class. This appears to be some internal mechanism for the Swing implementors. Let's try to avoid this constructor if we can. Looking further, we find

public JSlider(int min, int max, int value)
     Creates a horizontal slider using the specified min, max, and value.

This sounds general enough to be useful and simple enough to be usable. You might want to stash away the fact that you can have vertical sliders as well.

Next, you want to know what events a slider generates. There is no addAction-Listener method. That makes sense. Adjusting a slider seems different from clicking a button, and Swing uses a different event type for these events. There is a method

public void addChangeListener(ChangeListener l)

Click on the ChangeListener link to find out more about this interface. It has a single method

void stateChanged(ChangeEvent e)

Apparently, that method is called whenever the user moves the slider. What is a ChangeEvent? Once again, click on the link, to find out that this event class has nomethods of its own, but it inherits the getSource method from its superclass Event-Object. The getSource method tells us which component generated this event, but we don't need that information—we know that the event came from the slider.

Now let's make a plan: Add a change event listener to each slider. When the slider is changed, the stateChanged method is called. Find out the new value of the slider. Recompute the color value and repaint the color panel. That way, the color panel is continually repainted as the user moves one of the sliders.

To compute the color value, you will still need to get the current value of the slider. Look at all the methods that start with get. Sure enough, you find

public int getValue()
     Returns the slider's value.

Figure 18.16. The Components of the ColorViewerFrame

Figure 18.17. Classes of the Color Viewer Program

Now you know everything you need to write the program. The program uses one new Swing component and one event listener of a new type. After having mastered the basics, you may want to explore the capabilities of the component further, for example by adding tick marks—see Exercise P18.17.

Figure 16 shows how the components are arranged in the frame. Figure 17 shows the UML diagram.

ch18/slider/ColorViewer.java

1    import javax.swing.JFrame;
2
3    public class ColorViewer
4    {
5       public static void main(String[] args)
6       {
7          ColorViewerFrame frame = new ColorViewerFrame();
8          frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
9          frame.setVisible(true);
10       }
11    }

ch18/slider/ColorViewerFrame.java

1  import java.awt.BorderLayout;
2  import java.awt.Color;
3  import java.awt.GridLayout;
4  import javax.swing.JFrame;
5  import javax.swing.JLabel;
6  import javax.swing.JPanel;
7  import javax.swing.JSlider;
8  import javax.swing.event.ChangeListener;
9  import javax.swing.event.ChangeEvent;
10
11 public class ColorViewerFrame extends JFrame
12 {
13    private static final int FRAME_WIDTH = 300;
14    private static final int FRAME_HEIGHT = 400;
15
16    private JPanel colorPanel;
17    private JSlider redSlider;
18    private JSlider greenSlider;
19    private JSlider blueSlider;

20
21    public ColorViewerFrame()
22    {
23       colorPanel = new JPanel();
24
25       add(colorPanel, BorderLayout.CENTER);
26       createControlPanel();
27       setSampleColor();
28       setSize(FRAME_WIDTH, FRAME_HEIGHT);
29    }
30
31    public void createControlPanel()
32    {
33       class ColorListener implements ChangeListener
34       {
35          public void stateChanged(ChangeEvent event)
36          {
37             setSampleColor();
38          }
39       }
40
41       ChangeListener listener = new ColorListener();
42
43       redSlider = new JSlider(0, 255, 255);
44       redSlider.addChangeListener(listener);
45
46       greenSlider = new JSlider(0, 255, 175);
47       greenSlider.addChangeListener(listener);
48
49       blueSlider = new JSlider(0, 255, 175);
50       blueSlider.addChangeListener(listener);
51
52       JPanel controlPanel = new JPanel();
53       controlPanel.setLayout(new GridLayout(3, 2));
54
55       controlPanel.add(new JLabel("Red"));
56       controlPanel.add(redSlider);
57
58       controlPanel.add(new JLabel("Green"));
59       controlPanel.add(greenSlider);
60
61       controlPanel.add(new JLabel("Blue"));
62       controlPanel.add(blueSlider);
63
64       add(controlPanel, BorderLayout.SOUTH);
65    }
66
67    /**
68       Reads the slider values and sets the panel to
69       the selected color.
70    */
71    public void setSampleColor()
72    {
73       // Read slider values
74
75       int red = redSlider.getValue();
76       int green = greenSlider.getValue();
77       int blue = blueSlider.getValue();
78

79       // Set panel background to selected color
80
81       colorPanel.setBackground(new Color(red, green, blue));
82        colorPanel.repaint();
83    }
84  }

14. Why does a slider emit change events and not action events?

java.awt.BorderLayout                     javax.swing.JMenuBar
   CENTER                                    add
   EAST                                   javax.swing.JMenuItem
   NORTH                                  javax.swing.JRadioButton
   SOUTH                                  javax.swing.JScrollPane
   WEST                                   javax.swing.JSlider
java.awt.Container                           addChangeListener
   setLayout                                 getValue
java.awt.FlowLayout                       javax.swing.JTextArea
java.awt.Font                                 append
java.awt.GridLayout                       javax.swing.JTextField
javax.swing.AbstractButton                javax.swing.border.EtchedBorder
   isSelected                             javax.swing.border.TitledBorder
   setSelected                            javax.swing.event.ChangeEvent
javax.swing.ButtonGroup                   javax.swing.event.ChangeListener
   add                                       stateChanged
javax.swing.ImageIcon                     javax.swing.text.JTextComponent
javax.swing.JCheckBox                        getText
javax.swing.JComboBox                        isEditable
   addItem                                   setEditable
   getSelectedItem                           setText
   isEditable
   setEditable
javax.swing.JComponent
   setBorder
   setFont
javax.swing.JFrame
   setJMenuBar
javax.swing.JMenu
   add