In Win32, the term control means the group of all the GUI things that users can press, scroll, choose between, type into, draw on, and so forth. In the Unix XWindows world, a control is called a widget.

Neither control nor widget is a Java term. Instead, we use the term Component, or, when talking specifically about Swing, the JComponent subclass of Component. Each Swing control is a subclass of javax.swing.JComponent, so each control inherits all the methods and data fields of JComponent. JComponents are serializable, meaning the object can be written out to disk, can be read in again later, and can become an object again. They follow the rules for JavaBeans, so they can be coupled together in visual builder tools.

This whole chapter is about explaining the Swing components and how you use them. You will build up your GUI programs using these components. The first thing to note is that the Swing components are no longer peer-based, but are written in Java and are thus consistent on all platforms. Under the AWT, a button ended up being a Win32 button on Windows, a Macintosh button on the Macintosh, and a Motif button on Unix. With Swing, the button is rendered on a little bit of screen area that belongs to some ancestor Java component, and Swing puts all the button semantics on top of that. Swing draws the button so it looks armed (ready to push), pushed, or disabled. Because the code is written in Java, the button has identical behavior no matter where it runs.

Frankly, JFC is a very big topic. There are more than three hundred classes in the Swing library alone. We’ll present nine or ten individual Swing JComponents here, and provide pointers on the rest. This amounts to quite a few pages, so I recommend you read one or two in depth, then just look at the figures to get an idea of what each does. Return to the appropriate section in the chapter as you need actual code examples.

Object-oriented programming fits well with window systems. The concept of making new controls by subclassing existing ones and overriding part of their behavior saves time and effort. Another similarity is the way that controls have to handle events just as objects handle messages. Method calls are equivalent to sending a message to an object, and some OOP languages even refer to a method call as “sending a message.”

There is an abstract class called JComponent, which is the parent class for most things that can appear on screen. The basic ingredients of a GUI are all subclasses of the class called JComponent. JComponent is the superclass that holds the common information about an on-screen control and provides higher-level features common to each control, such as:

Components correspond to “things that interact with the user” and Containers are “backdrops to put them on.” The superclass of javax.swing.JComponent is java.awt.Container. And the parent of Container is java.awt.Component.

The behavior and appearance of each specific control is one level down in the subclasses of JComponent. The Swing lightweight controls can be divided up as shown in Table 21-1. We will look at just one or two components from each of these categories.

Each control has methods appropriate to what it does. The JFileChooser control has methods to get and set the current directory, get the selected filename(s), apply a filename filter, and so on. We’ll examine these individual JComponents later in the chapter.

Containers are the objects that are displayed directly on the screen. Controls must be added to a Container if you want to see them. The container in this example driver program is called JFrame. JFrame will be the main window for most of your Swing applications.

Let’s create a JFrame, set its size, set it visible, tell it how to arrange JComponents that are added, and add some event-handler code to exit the program when it detects that you have clicked on the JFrame to close it. Phew! That’s quite a list of tasks, so we’ll split them off into a separate method. Make everything static. In this way, we can use it from the main() method, and we get the following:

import java.awt.*;
import java.awt.event.*;
import javax.swing.*;
public class Demo {
         static JFrame jframe = new JFrame(“Example”);

         public static void setupJFrame() {
                  jframe.setSize(400,100);
                  jframe.setVisible(true);
                  jframe.getContentPane().setLayout( new FlowLayout() );

                 WindowListener l = new WindowAdapter() {
                             public void windowClosing(WindowEvent e) {
                                      System.exit(0);}
                  };
                   jframe.addWindowListener(l);
        }

        public static void main(String[] args) {
                  setupJFrame();
                  JButton jb = new JButton("pressure");
                  jframe.getContentPane().add( jb );
                  jframe.setVisible(true);
      }
} 

The JButton Component that we are trying to demonstrate is printed in bold type. The line that follows adds the JComponent to the JFrame’s content pane. To cut down on the extraneous code in the pages ahead, I’ll show only the statements that directly deal with the JComponent. That means I’ll show only the two bold statements in the example above. You should supply all the missing code when you compile and run the examples. Next, a thread caution, then on to the first example!

What it is: JLabel is the simplest JComponent. It is just a string, image, or both that appears on screen. The contents can be left-, right-, or center-aligned according to an argument to the constructor. The default is left-aligned. JLabel is a cheap, fast way to get a picture or text on the screen

What it looks like on-screen:

The code to create it:

//  remember, we are only showing relevant statements from main()
     ImageIcon icon = new ImageIcon("star.gif");
     JLabel jl = new JLabel("You are a star", icon, JLabel.CENTER);

     frame.getContentPane().add( jl );
     frame.pack(); // size the JFrame to fit its contents 

Note the way we can bring in an image from a GIF or JPEG file by constructing an ImageIcon with a pathname to a file. Labels do not generate any events in and of themselves. It is possible, however, to get and set the text of a label. You might do that in response to an event from a different component. The constructors for JLabel are:

public javax.swing.JLabel(java.lang.String);
public javax.swing.JLabel(java.lang.String,int);
public javax.swing.JLabel(java.lang.String,javax.swing.Icon,int);
public javax.swing.JLabel(javax.swing.Icon);
public javax.swing.JLabel(javax.swing.Icon,int); 

The int parameter is a constant from the JLabel class specifying left-, right- or center-alignment in the area where the label is displayed.

JLabels are typically used to augment other controls with descriptions or instructions. People often want to know how to get a multiline label (or a multiline button). There is no direct way. Either use multiple labels, or program the functionality in for yourself by extending the class JComponent to do what you want.

What it is: This is a GUI button. You supply code for the action that is to take place when the button is pressed.

What it looks like on-screen:

The code to create it:

JButton jb = new JButton("pressure");
jframe.getContentPane().add( jb ); 

The code to handle events from it:

jb.addActionListener( new ActionListener() {
     int i = 1;
     public void actionPerformed(ActionEvent e)
          { System.out.println("pressed "+ i++); }
     } ); 

When you press this button, the event-handler will print out the number of times it has been pressed. You can easily create buttons with images as well, like this:

Icon spIcon = new ImageIcon("spam.jpg");
JButton jb = new JButton("press here for Spam", spIcon); 

You can add a keyboard accelerator to a button, and you can give it a symbolic name for the text string that it displays. This helps with internationalizing code.

Program an “Alice in Wonderland” JFrame with two buttons, one of which makes the frame grow larger, the other smaller. The Component method setSize(int, int) will resize a component. (Easy—about twenty lines of code).

What it is: This is a text string that acts as a hint or further explanation. You can set it for any JComponent. It appears automatically when the mouse lingers on that component and it disappears when you roll the mouse away.

Tooltips don’t generate any events so there is nothing to handle.

What it looks like on-screen: We’ll add a tooltip to the JLabel that we showed on the previous page.

The code to create it:

JLabel jl = ...
jl.setToolTipText(“You must practice to be a star!”); 

Notice that you don’t directly create a JToolTip object. That is done for you behind the scenes. You invoke the setToolTipText() method of JComponent.

It’s so quick and easy to create tooltips; use them generously.

What it is: This is an area of the screen where you can enter a line of text. There are a couple of subclasses: JTextArea (several lines in size) and JPasswordField (which doesn’t echo what you type in). You can display some initial text. The text is selectable (you can highlight it with the cursor) and can be set to be editable or not editable.

What it looks like on-screen:

The code to create it:

JLabel jl = new JLabel("Enter your name:");
JTextField jtf = new JTextField(25); // field is 25 chars wide 

The code to retrieve user input from it: Text fields generate key events on each keystroke and an ActionEvent when the user presses a carriage return. This makes it convenient to validate individual keystrokes as they are typed (as in ensuring that a field is wholly numeric) and to retrieve all the text when the user has finished typing. The code to get the text looks like this:

jtf.addActionListener( new ActionListener() {
     public void actionPerformed(ActionEvent e)
     {  System.out.println(
          " you entered: " + e.getActionCommand() ); }
     } );

Container c = jframe.getContentPane();
c.add( jl );
c.add( jtf ); 

In this example, running the program, typing in a name, and hitting carriage return will cause the name to be echoed on system.out. You should write some code to try implementing a listener for each keystroke.

What it is: A checkbox screen object that represents a boolean choice: pressed, not pressed, on, or off. Usually some text explains the choice. For example, a “Press for fries” JLabel would have a JCheckBox “button” allowing yes or no. You can also add an icon to the JCheckBox, just the way you can with JButton.

What it looks like on-screen:

The code to create it:

JCheckBox jck1 = new JCheckBox("Pepperoni");
JCheckBox jck2 = new JCheckBox("Mushroom");
JCheckBox jck3 = new JCheckBox("Black olives");
JCheckBox jck4 = new JCheckBox("Tomato");
Container c = jframe.getContentPane();
c.add( jck1 ); c.add( jck2 ); // etc... 

The code to retrieve user input from it: Checkbox generates both ActionEvent and ItemEvent every time you change it. This seems to be for backward compatibility with AWT. We already saw the code to handle ActionEvents with Button. The code to register an ItemListener looks like this:

jck2.addItemListener( new ItemListener()
{ // anonymous class
        public void itemStateChanged(ItemEvent e) {
                if (e.getStateChange()==e.SELECTED)
                      System.out.print("selected ");
                else System.out.print("de-selected ");
                System.out.print("Mushroom
");
        }
} ); 

In this example, running the program and clicking the “Mushroom” checkbox will cause the output of selected Mushroom in the system console.

Handlers in real programs will do more useful actions as necessary like assigning values and creating objects. The ItemEvent contains fields and methods that specify which object generated the event and whether it was selected or deselected.

What it is: There was (and is) an AWT component known as Canvas. It is a screen area that you can use for drawing graphics or receiving user input. A Canvas is usually subclassed to add the behavior you need, especially when you use it to display a GIF or JPEG image. A Canvas contains almost no methods. All its functionality is either inherited from Component (setting font, color, size) or from functionality you add when you extend the class.

Everyone expects there to be a JCanvas replacing Canvas, just as JButton replaces Button, JFrame replaces Frame, and so on. There is no JCanvas. The AWT component Canvas was just like the AWT component Panel, except Panel was also a container. The Swing version of Panel, JPanel, does double duty. It replaces both Canvas and Panel.

To draw on a JPanel, you may want to supply your own version of the method paintComponent(Graphics g). To do that, you need to extend the class and override the paintComponent() method ^[1] for this Container. That gives you a Graphics context—the argument to paintComponent() —which is used in all drawing operations. The many methods of Graphics let you render (the fancy graphics word for “draw”) lines, shapes, text, etc., on the screen.

A simpler alternative for simpler drawings is to use JLabel to create the picture and add it to JPanel as shown in the following code.

The code to create it: Figure 21-2 results from running the following code:

I like this picture because it looks the same in black and white as it does in color.

Figure 21-2. JPanel replaces Panel and Canvas.

class MyJPanel extends JPanel {
     JLabel jl = new JLabel(new ImageIcon( "bmw.jpg"));
     { add(jl); // instance initializer just for fun

          addKeyListener( new KeyAdapter() {
               public void keyPressed(KeyEvent e) {
                    char c = e.getKeyChar();
                    System.out.println("got char "+c);
               }
          } );
    }
}

...

     public static void main(String[] args) {
          setupFrame();
          MyJPanel mjp = new MyJPanel();
          jframe.getContentPane().add(mjp);
          jframe.setVisible(true);
          mjp.requestFocus();
    } 

I have also added a KeyListener for the JPanel here. That allows you to make keystrokes on top of the JPanel and have the callback take place for each one individually. All you do is echo the characters to prove you got them. With the picture backdrop and the capture of individual keystrokes, you have the basics of a computer game right there. There are a couple of real computer games on the CD.

You have to request the focus for a component before key events will be sent to it, and the component has to be visible at the time you do that.

What it is: JRadioButtons are used when you have a group of checkboxes and you want a maximum of one of them to be selected. This was done with a CheckboxGroup in the AWT, but the design has been cleaned and simplified in Swing. JRadioButton, JCheckBox, and JButton are now subclasses of AbstractButton and have common consistent behavior, can be given images, can be embedded in menus, and so on.

The term “radio buttons” arises from the old manual station selection buttons in car radios. When you pressed in one of the buttons, all the others would pop out and be deselected. ButtonGroups work the same way.

What it looks like on-screen:

On Windows, mutually exclusive checkboxes are round, while multiple selection checkboxes are square. This is one of those “look and feel” differences between window systems.

The code to create it: This example shows some more sophisticated things you can do in your event-handler. In this example, we have a JLabel with a picture of the choice. In the event-handler, we set the label to correspond to the RadioButton choice.

The ButtonGroup class automatically takes care of arming the previous radio button when you press another.

// JRadioButton code
     final JLabel piclabel
          = new JLabel(new ImageIcon( pieString + ".gif"));

     /** Listens to the radio buttons. */
     class RadioListener implements ActionListener {
          public void actionPerformed(ActionEvent e) {
          // getting the event causes update on Jlabel icon
          piclabel.setIcon(
               new ImageIcon( e.getActionCommand()+".gif"));
          }
     }

     JRadioButton pieButton = new JRadioButton(pieString);
     pieButton.setMnemonic(’b’);
     pieButton.setActionCommand(pieString);
     pieButton.setSelected(true);

     JRadioButton cakeButton = new JRadioButton(cakeString);
     JRadioButton iceButton = new JRadioButton(iceString);

     // Group the radio buttons.
     ButtonGroup group = new ButtonGroup();
     group.add(pieButton);
     group.add(cakeButton);
     group.add(iceButton);

     // Register a listener for the radio buttons.
     RadioListener myListener = new RadioListener();
     pieButton.addActionListener(myListener);
     cakeButton.addActionListener(myListener);
     iceButton.addActionListener(myListener);

     // Put the radio buttons in a column in a panel to line up
     JPanel radioPanel = new JPanel();
     radioPanel.setLayout(new GridLayout(0, 1));
     radioPanel.add(pieButton);
     radioPanel.add(cakeButton);
     radioPanel.add(iceButton);

     jframe.getContentPane().add(radioPanel);
     jframe.getContentPane().add(piclabel);
     jframe.setVisible(true); 

What it is: This is a utility pane that can pop up some common warning and error messages. It’s as easy to use as JToolTip, and it works the same way. You don’t instantiate it directly, but you call a method to make it happen.

What it looks like on-screen:

The code to create it: The method to show a JOptionPane takes four arguments:

Icon s = new ImageIcon("spam.jpg");
JLabel jl = new JLabel("Are you getting enough?", s,JLabel.CENTER);

JOptionPane.showMessageDialog( null, // parent frame
                    jl,   // Object to display
                    "Plenty of spam", // title bar message
                    JOptionPane.QUESTION_MESSAGE ); 

The code to retrieve user input from it: No input comes back from this component. When the user clicks on the button, the Pane is dismissed automatically. There are a great many choices and methods that fine-tune this JComponent to let you convey exactly the nuance of information you want.

What it is: Of all the JComponents, this one is probably my favorite. It works so hard for you with so little effort on your part.

A JScrollPane provides a scrollable view of any lightweight component. You just instantiate a JScrollPane with the thing you want to scroll as an argument to the constructor. Then set the ScrollPane’s preferred size with a method call, add it to your container, and you’re done! This is so much easier than messing around with individual and highly buggy scrollbars that we had in JDK 1.0.

By default, a scroll pane attempts to size itself so that its client displays at its preferred size. Many components have a simple preferred size that’s big enough to display the entire component. You can customize a scroll pane with many refinements on how much to scroll, which of the scroll bars to show, custom decorations around the sides, and so on. The visible area in the Pane is called the “viewport.”

What it looks like on-screen:

The code to create it: In this code, we put the JPanel subclass that we created earlier into a JScrollPane.

MyJPanel mjp = new MyJPanel();
JScrollPane jsp = new JScrollPane( mjp );
jsp.setPreferredSize( new Dimension(150, 150));
jframe.getContentPane().add(jsp); 

The code to retrieve user input from it: You won’t need to interact with your scroll pane very frequently, as it does so much of the right thing by default. However, you can implement the Scrollable interface if your enthusiasm extends to wanting to get callbacks for individual clicks on the scroll bars.

What it is: A Tabbed Pane is a component that lets you economize on-screen real estate. It simulates a folder with tabbed page dividers. You have a series of “tabs” (labels) along the top, associated with Components on a larger rectangular area beneath. By clicking on a tab label, you bring its associated component to the front. We’ll show an example using the JEditorPane and the JPanel we already saw.

What it looks like on-screen:

You can make the tabs appear on any of the four sides of the TabbedPane. You can have even more than one row of tabs, but the human factors of that are so appalling that Sun corrected it in JDK 1.4. When you have multiple rows, any tab that’s clicked moves to the bottom row of tabs. As a result, clicking on some tabs causes all of them to change places. To prevent this, you can pass an argument to the constructor saying that you want tabs to scroll, not to wrap, when you exceed a line.

The code to create it:

// set up the editor pane, as before
     JEditorPane jep =null;
     try {
          jep = new JEditorPane( "file:///tmp/know.html" );
     } catch (Exception e) {System.out.println("error: "+e); }

     jep.setEditable(false); // turns off the ability to edit
     JScrollPane jsp = new JScrollPane( jep );
     jsp.setPreferredSize( new Dimension(550, 250));

// set up the JPanel, as before
     MyJPanel mjp = new MyJPanel();
     jframe.getContentPane().add(mjp);

// create a tabbed pane and add them to it.
     JTabbedPane jtp = new JTabbedPane();
     ImageIcon ic = new ImageIcon("star.gif");
     jtp.addTab("Bike", ic, mjp,
                "1989 BWM RS100/1996 Dalmatian Annie");
     jtp.addTab("Knowledge", null, jsp, "who knew?");

     jframe.getContentPane().add(jtp);
     jframe.setVisible(true);
} 

The method to add a tab and the Component together takes four arguments:

public void addTab(String title,
                    Icon icon,
                    Component component,
                    String tip) 

The title is the phrase to put on the tab. The icon is a little picture with which you can decorate the phrase. For example, on the “Bike” pane I use a star, and on the “Knowledge” pane I use null to signify no picture. The third parameter is the component that you want associated with that tab. The final parameter is a String representing tooltip text that you get for free with this component.

What it is: This is a very powerful JComponent! JEditorPane allows you to display and edit documents that contain HTML, Rich Text Format, or straight Unicode characters. It formats the text and displays it.

What it looks like on-screen:

You can load the component from a URL or from a String containing a URL as shown below, or from the contents of a String itself. In the following example, the JEditor pane is placed in a ScrollPane so it displays and scrolls well.

The code to create it:

JEditorPane jep =null;
try {
     jep = new JEditorPane("file:///tmp/know.html");
} catch (Exception e) {System.out.println("error: "+e); }

jep.setEditable(false); // turns off the ability to edit
JScrollPane jsp = new JScrollPane( jep );
jsp.setPreferredSize( new Dimension(550, 250));

jframe.getContentPane().add(jsp); 

Notice how trivial it is to display an HTML file and to wrap a JScrollPane around it. JEditorPane is a subclass of the less specialized JTextComponent.

Let’s quickly review the match between components and events (Table 21-2).