13: Creating Windows
& Applets

A fundamental design guideline is “make simple things easy, and difficult things possible.” [61]

The original design goal of the graphical user interface (GUI) library in Java 1.0 was to allow the programmer to build a GUI that looks good on all platforms. That goal was not achieved. Instead, the Java 1.0 Abstract Window Toolkit (AWT) produces a GUI that looks equally mediocre on all systems. In addition, it’s restrictive: you can use only four fonts and you cannot access any of the more sophisticated GUI elements that exist in your operating system. The Java 1.0 AWT programming model is also awkward and non-object-oriented. A student in one of my seminars (who had been at Sun during the creation of Java) explained why: the original AWT had been conceptualized, designed, and implemented in a month. Certainly a marvel of productivity, and also an object lesson in why design is important. [ Add Comment ]

The situation improved with the Java 1.1 AWT event model, which takes a much clearer, object-oriented approach, along with the addition of JavaBeans, a component programming model that is oriented toward the easy creation of visual programming environments. Java 2 finishes the transformation away from the old Java 1.0 AWT by essentially replacing everything with the Java Foundation Classes (JFC), the GUI portion of which is called “Swing.” These are a rich set of easy-to-use, easy-to-understand JavaBeans that can be dragged and dropped (as well as hand programmed) to create a GUI that you can (finally) be satisfied with. The “revision 3” rule of the software industry (a product isn’t good until revision 3) seems to hold true with programming languages as well. [ Add Comment ]

This chapter does not cover anything but the modern, Java 2 Swing library, and makes the reasonable assumption that Swing is the final destination GUI library for Java. If for some reason you need to use the original “old” AWT (because you’re supporting old code or you have browser limitations), you can find that introduction in the first edition of this book, downloadable at www.BruceEckel.com (also included on the CD ROM bound with this book). [ Add Comment ]

Early in this chapter, you’ll see how things are different when you want to create an applet vs. a regular application using Swing, and how to create programs that are both applets and applications so they can be run either inside a browser or from the command line. Almost all the GUI examples in this book will be executable as either applets or applications. [ Add Comment ]

Please be aware that this is not a comprehensive glossary of either all the Swing components, or all the methods for the described classes. What you see here is intended to be simple. The Swing library is vast, and the goal of this chapter is only to get you started with the essentials and comfortable with the concepts. If you need to do more, then Swing can probably give you what you want if you’re willing to do the research. [ Add Comment ]

I assume here that you have downloaded and installed the (free) Java library documents in HTML format from java.sun.com and will browse the javax.swing classes in that documentation to see the full details and methods of the Swing library. Because of the simplicity of the Swing design, this will often be enough information to solve your problem. There are numerous (rather thick) books dedicated solely to Swing and you’ll want to go to those if you need more depth, or if you want to modify the default Swing behavior. [ Add Comment ]

As you learn about Swing you’ll discover: [ Add Comment ]

Swing contains all the components that you expect to see in a modern UI, everything from buttons that contain pictures to trees and tables. It’s a big library, but it’s designed to have appropriate complexity for the task at hand—if something is simple, you don’t have to write much code but as you try to do more complex things, your code becomes proportionally more complex. This means an easy entry point, but you’ve got the power if you need it. [ Add Comment ]

Much of what you’ll like about Swing could be called “orthogonality of use.” That is, once you pick up the general ideas about the library you can apply them everywhere. Primarily because of the standard naming conventions, much of the time that I was writing these examples I could guess at the method names and get it right the first time, without looking anything up. This is certainly the hallmark of a good library design. In addition, you can generally plug components into other components and things will work correctly. [ Add Comment ]

For speed, all the components are “lightweight,” and Swing is written entirely in Java for portability. [ Add Comment ]

Keyboard navigation is automatic—you can run a Swing application without using the mouse, and this doesn’t require any extra programming. Scrolling support is effortless—you simply wrap your component in a JScrollPane as you add it to your form. Features such as tool tips typically require a single line of code to use. [ Add Comment ]

Swing also supports a rather radical feature called “pluggable look and feel,” which means that the appearance of the UI can be dynamically changed to suit the expectations of users working under different platforms and operating systems. It’s even possible (albeit difficult) to invent your own look and feel. [ Add Comment ]

One of Java’s design goals is to create applets, which are little programs that run inside a Web browser. Because they must be safe, applets are limited in what they can accomplish. However, applets are a powerful tool that support client-side programming, a major issue for the Web. [ Add Comment ]

Programming within an applet is so restrictive that it’s often referred to as being “inside the sandbox,” since you always have someone—that is, the Java run-time security system—watching over you. [ Add Comment ]

However, you can also step outside the sandbox and write regular applications rather than applets, in which case you can access the other features of your OS. We’ve been writing regular applications all along in this book, but they’ve been console applications without any graphical components. Swing can also be used to build GUI interfaces for regular applications. [ Add Comment ]

You can generally answer the question of what an applet is able to do by looking at what it is supposed to do: extend the functionality of a Web page in a browser. Since, as a Net surfer, you never really know if a Web page is from a friendly place or not, you want any code that it runs to be safe. So the biggest restrictions you’ll notice are probably: [ Add Comment ]

If you can live within the restrictions, applets have definite advantages, especially when building client/server or other networked applications: [ Add Comment ]

Because applets are automatically integrated with HTML, you have a built-in platform-independent documentation system to support the applet. It’s an interesting twist, since we’re used to having the documentation part of the program rather than vice versa. [ Add Comment ]

Libraries are often grouped according to their functionality. Some libraries, for example, are used as is, off the shelf. The standard Java library String and ArrayList classes are examples of these. Other libraries are designed specifically as building blocks to create other classes. A certain category of library is the application framework, whose goal is to help you build applications by providing a class or set of classes that produces the basic behavior that you need in every application of a particular type. Then, to customize the behavior to your own needs, you inherit from the application class and override the methods of interest. The application framework’s default control mechanism will call your overridden methods at the appropriate time. An application framework is a good example of “separating the things that change from the things that stay the same,” since it attempts to localize all the unique parts of a program in the overridden methods[62]. [ Add Comment ]

Applets are built using an application framework. You inherit from class JApplet and override the appropriate methods. There are a few methods that control the creation and execution of an applet on a Web page:

With this information you are ready to create a simple applet:

Note that applets are not required to have a main( ). That’s all wired into the application framework; you put any startup code in init( ). [ Add Comment ]

In this program, the only activity is putting a text label on the applet, via the JLabel class (the old AWT appropriated the name Label as well as other names of components, so you will often see a leading “J” used with Swing components). The constructor for this class takes a String and uses it to create the label. In the above program this label is placed on the form. [ Add Comment ]

The init( ) method is responsible for putting all the components on the form using the add( ) method. You might think that you ought to be able to simply call add( ) by itself, and in fact that’s the way it used to be in the old AWT. However, Swing requires you to add all components to the “content pane” of a form, and so you must call getContentPane( ) as part of the add( ) process. [ Add Comment ]

To run this program you must place it inside a Web page and view that page inside your Java-enabled Web browser. To place an applet inside a Web page you put a special tag inside the HTML source for that Web page[63] to tell the page how to load and run the applet. [ Add Comment ]

This process used to be very simple, when Java itself was simple and everyone was on the same bandwagon and incorporated the same Java support inside their Web browsers. Then you might have been able to get away with a very simple bit of HTML inside your Web page, like this:

Then along came the browser and language wars, and we (programmers and end users alike) lost. After awhile, JavaSoft realized that we could no longer expect browsers to support the correct flavor of Java, and the only solution was to provide some kind of add-on that would conform to a browser’s extension mechanism. By using the extension mechanism (which a browser vendor cannot disable—in an attempt to gain competitive advantage—without breaking all the third-party extensions), JavaSoft guarantees that Java cannot be shut out of the Web browser by an antagonistic vendor. [ Add Comment ]

With Internet Explorer, the extension mechanism is the ActiveX control, and with Netscape it is the plug-in. In your HTML code, you must provide tags to support both. Here’s what the simplest resulting HTML page looks like for Applet1:[64]

Some of these lines were too long and had to be wrapped to fit on the page. The code in this book’s source code (on the book’s CD ROM, and downloadable from www.BruceEckel.com) will work without having to worry about correcting line wraps. [ Add Comment ]

The code value gives the name of the .class file where the applet resides. The width and height specify the initial size of the applet (in pixels, as before). There are other items you can place within the applet tag: a place to find other .class files on the Internet (codebase), alignment information (align), a special identifier that makes it possible for applets to communicate with each other (name), and applet parameters to provide information that the applet can retrieve. Parameters are in the form:

and there can be as many as you want. [ Add Comment ]

The source code package for this book provides an HTML page for each of the applets in this book, and thus many examples of the applet tag. You can find a full and current description of the details of placing applets in Web pages at java.sun.com. [ Add Comment ]

Sun’s JDK (freely downloadable from java.sun.com) contains a tool called the Appletviewer that picks the <applet> tags out of the HTML file and runs the applets without displaying the surrounding HTML text. Because the Appletviewer ignores everything but APPLET tags, you can put those tags in the Java source file as comments:

This way, you can run “appletviewer MyApplet.java” and you don’t need to create tiny HTML files to run tests. For example, you can add the commented HTML tags to Applet1.java:

Now you can invoke the applet with the command

In this book, this form will be used for easy testing of applets. Shortly, you’ll see another coding approach which will allow you to execute applets from the command line without the Appletviewer. [ Add Comment ]

You can perform a simple test without any network connection by starting up your Web browser and opening the HTML file containing the applet tag. As the HTML file is loaded, the browser will discover the applet tag and go hunt for the .class file specified by the code value. Of course, it looks at the CLASSPATH to find out where to hunt, and if your .class file isn’t in the CLASSPATH then it will give an error message on the status line of the browser to the effect that it couldn’t find that .class file. [ Add Comment ]

When you want to try this out on your Web site things are a little more complicated. First of all, you must have a Web site, which for most people means a third-party Internet Service Provider (ISP) at a remote location. Since the applet is just a file or set of files, the ISP does not have to provide any special support for Java. You must also have a way to move the HTML files and the .class files from your site to the correct directory on the ISP machine. This is typically done with a File Transfer Protocol (FTP) program, of which there are many different types available for free or as shareware. So it would seem that all you need to do is move the files to the ISP machine with FTP, then connect to the site and HTML file using your browser; if the applet comes up and works, then everything checks out, right? [ Add Comment ]

Here’s where you can get fooled. If the browser on the client machine cannot locate the .class file on the server, it will hunt through the CLASSPATH on your local machine. Thus, the applet might not be loading properly from the server, but to you it looks fine during your testing process because the browser finds it on your machine. When someone else connects, however, his or her browser can’t find it. So when you’re testing, make sure you erase the relevant .class files (or .jar file) on your local machine to verify that they exist in the proper location on the server. [ Add Comment ]

One of the most insidious places where this happened to me is when I innocently placed an applet inside a package. After uploading the HTML file and applet, it turned out that the server path to the applet was confused because of the package name. However, my browser found it in the local CLASSPATH. So I was the only one who could properly load the applet. It took some time to discover that the package statement was the culprit. In general, you’ll want to leave the package statement out of an applet. [ Add Comment ]

There are times when you’d like to make a windowed program do something else other than sit on a Web page. Perhaps you’d also like it to do some of the things a “regular” application can do but still have the vaunted instant portability provided by Java. In previous chapters in this book we’ve made command-line applications, but in some operating environments (the Macintosh, for example) there isn’t a command line. So for any number of reasons you’d like to build a windowed, non-applet program using Java. This is certainly a reasonable desire. [ Add Comment ]

The Swing library allows you to make an application that preserves the look and feel of the underlying operating environment. If you want to build windowed applications, it makes sense to do so[65] only if you can use the latest version of Java and associated tools so you can deliver applications that won’t confound your users. If for some reason you’re forced to use an older version of Java, think hard before committing to building a significant windowed application. [ Add Comment ]

Often you’ll want to be able to create a class that can be invoked as either a window or an applet. This is especially convenient when you’re testing the applets, since it’s typically much faster and easier to run the resulting applet-application from the command line than it is to start up a Web browser or the Appletviewer. [ Add Comment ]

To create an applet that can be run from the console command line, you simply add a main( ) to your applet that builds an instance of the applet inside a JFrame.[66] As a simple example, let’s look at Applet1b.java modified to work as both an application and an applet:

main( ) is the only element added to the applet, and the rest of the applet is untouched. The applet is created and added to a JFrame so that it can be displayed. [ Add Comment ]

The line:

Causes the window to be properly closed. Console comes from com.bruceeckel.swing and will be explained a little later. [ Add Comment ]

You can see that in main( ), the applet is explicitly initialized and started since in this case the browser isn’t available to do it for you. Of course, this doesn’t provide the full behavior of the browser, which also calls stop( ) and destroy( ), but for most situations it’s acceptable. If it’s a problem, you can force the calls yourself.[67] [ Add Comment ]

Notice the last line:

Without this, you won’t see anything on the screen. [ Add Comment ]

Although the code that turns programs into both applets and applications produces valuable results, if used everywhere it becomes distracting and wastes paper. Instead, the following display framework will be used for the Swing examples in the rest of this book:

This is a tool you may want to use yourself, so it’s placed in the library com.bruceeckel.swing. The Console class consists entirely of static methods. The first is used to extract the class name (using RTTI) from any object and to remove the word “class,” which is typically prepended by getClass( ). This uses the String methods indexOf( ) to determine whether the word “class” is there, and substring( ) to produce the new string without “class” or the trailing space. This name is used to label the window that is displayed by the run( ) methods. [ Add Comment ]

setupClosing( ) is used to hide the code that causes a JFrame to exit a program when that JFrame is closed. The default behavior is to do nothing, so if you don’t call setupClosing( ) or write the equivalent code for your JFrame, the application won’t close. The reason this code is hidden rather than placing it directly in the subsequent run( ) methods is partly because it allows you to use the method by itself when what you want to do is more complicated than what run( ) provides. However, it also isolates a change factor: Java 2 has two ways of causing certain types of windows to close. In JDK 1.2, the solution is to create a new WindowAdapter class and implement windowClosing( ), as seen above (the meaning of this will be fully explained later in this chapter). However, during the creation of JDK 1.3 the library designers observed that you typically need to close windows whenever you’re creating a non-applet, and so they added the setDefaultCloseOperation( ) to JFrame and JDialog. From the standpoint of writing code, the new method is much nicer to use but this book was written while there was still no JDK 1.3 implemented on Linux and other platforms, so in the interest of cross-version portability the change was isolated inside setupClosing( ). [ Add Comment ]

The run( ) method is overloaded to work with JApplets, JPanels, and JFrames. Note that only if it’s a JApplet are init( ) and start( ) called. [ Add Comment ]

Now any applet can be run from the console by creating a main( ) containing a line like this:

in which the last two arguments are the display width and height. Here’s Applet1c.java modified to use Console:

This allows the elimination of repeated code while providing the greatest flexibility in running the examples. [ Add Comment ]

If you’re using Windows, you can simplify the process of running a command-line Java program by configuring the Windows Explorer—the file browser in Windows, not the Internet Explorer—so that you can simply double-click on a .class file to execute it. There are several steps in this process. [ Add Comment ]

First, download and install the Perl programming language from www.Perl.org. You’ll find the instructions and language documentation on that site. [ Add Comment ]

Next, create the following script without the first and last lines (this script is part of this book’s source-code package):

Now, open the Windows Explorer, select “View,” “Folder Options,” then click on the “File Types” tab. Press the “New Type” button. For “Description of Type” enter “Java class file.” For “Associated Extension,” enter “class.” Under “Actions” press the “New” button. For “Action” enter “Open,” and for “Application used to perform action” enter a line like this:

You must customize the path before “RunJava.bat” to conform to the location where you placed the batch file. [ Add Comment ]

Once you perform this installation, you may run any Java program by simply double-clicking on the .class file containing a main( ). [ Add Comment ]

Making a button is quite simple: you just call the JButton constructor with the label you want on the button. You’ll see later that you can do fancier things, like putting graphic images on buttons. [ Add Comment ]

Usually you’ll want to create a field for the button inside your class so that you can refer to it later. [ Add Comment ]

The JButton is a component—its own little window—that will automatically get repainted as part of an update. This means that you don’t explicitly paint a button or any other kind of control; you simply place them on the form and let them automatically take care of painting themselves. So to place a button on a form, you do it inside init( ):

Something new has been added here: before any elements are placed on the content pane, it is given a new “layout manager,” of type FlowLayout. The layout manager is the way that the pane implicitly decides where to place the control on the form. The normal behavior of an applet is to use the BorderLayout, but that won’t work here because (as you will learn later in this chapter when controlling the layout of a form is examined in more detail) it defaults to covering each control entirely with every new one that is added. However, FlowLayout causes the controls to flow evenly onto the form, left to right and top to bottom. [ Add Comment ]

You’ll notice that if you compile and run the applet above, nothing happens when you press the buttons. This is where you must step in and write some code to determine what will happen. The basis of event-driven programming, which comprises a lot of what a GUI is about, is tying events to code that responds to those events. [ Add Comment ]

The way that this is accomplished in Swing is by cleanly separating the interface (the graphical components) and the implementation (the code that you want to run when an event happens to a component). Each Swing component can report all the events that might happen to it, and it can report each kind of event individually. So if you’re not interested in, for example, whether the mouse is being moved over your button, you don’t register your interest in that event. It’s a very straightforward and elegant way to handle event-driven programming, and once you understand the basic concepts you can easily use Swing components that you haven’t seen before—in fact, this model extends to anything that can be classified as a JavaBean (which you’ll learn about later in the chapter). [ Add Comment ]

At first, we will just focus on the main event of interest for the components being used. In the case of a JButton, this “event of interest” is that the button is pressed. To register your interest in when a button is pressed, you call the JButton’s addActionListener( ) method. This method expects an argument that is an object that implements the ActionListener interface, which contains a single method called actionPerformed( ). So all you have to do to attach code to a JButton is to implement the ActionListener interface in a class, and register an object of that class with the JButton via addActionListener( ). The method will be called when the button is pressed (this is normally referred to as a callback). [ Add Comment ]

But what should the result of pressing that button be? We’d like to see something change on the screen, so a new Swing component will be introduced: the JTextField. This is a place where text can be typed, or in this case modified by the program. Although there are a number of ways to create a JTextField, the simplest is just to tell the constructor how wide you want that field to be. Once the JTextField is placed on the form, you can modify its contents by using the setText( ) method (there are many other methods in JTextField, but you must look these up in the HTML documentation for the JDK from java.sun.com). Here is what it looks like:

Creating a JTextField and placing it on the canvas takes the same steps as for JButtons, or for any Swing component. The difference in the above program is in the creation of the aforementioned ActionListener class BL. The argument to actionPerformed( ) is of type ActionEvent, which contains all the information about the event and where it came from. In this case, I wanted to describe the button that was pressed: getSource( ) produces the object where the event originated, and I assumed that is a JButton. getText( ) returns the text that’s on the button, and this is placed in the JTextField to prove that the code was actually called when the button was pressed. [ Add Comment ]

In init( ), addActionListener( ) is used to register the BL object with both the buttons. [ Add Comment ]

It is often more convenient to code the ActionListener as an anonymous inner class, especially since you tend to only use a single instance of each listener class. Button2.java can be modified to use an anonymous inner class as follows: [ Add Comment ]

The approach of using an anonymous inner class will be preferred (when possible) for the examples in this book. [ Add Comment ]

A JTextArea is like a JTextField except that it can have multiple lines and has more functionality. A particularly useful method is append( ); with this you can easily pour output into the JTextArea, thus making a Swing program an improvement (since you can scroll backward) over what has been accomplished thus far using command-line programs that print to standard output. As an example, the following program fills a JTextArea with the output from the geography generator in Chapter 9:

In init( ), the Map is filled with all the countries and their capitals. Note that for both buttons the ActionListener is created and added without defining an intermediate variable, since you never need to refer to that listener again during the program. The “Add Data” button formats and appends all the data, while the “Clear Data” button uses setText( ) to remove all the text from the JTextArea. [ Add Comment ]

As the JTextArea is added to the applet, it is wrapped in a JScrollPane, to control scrolling when too much text is placed on the screen. That’s all you must do in order to produce full scrolling capabilities. Having tried to figure out how to do the equivalent in some other GUI programming environments, I am very impressed with the simplicity and good design of components like JScrollPane. [ Add Comment ]

The way that you place components on a form in Java is probably different from any other GUI system you’ve used. First, it’s all code; there are no “resources” that control placement of components. Second, the way components are placed on a form is controlled not by absolute positioning but by a “layout manager” that decides how the components lie based on the order that you add( ) them. The size, shape, and placement of components will be remarkably different from one layout manager to another. In addition, the layout managers adapt to the dimensions of your applet or application window, so if the window dimension is changed, the size, shape, and placement of the components can change in response. [ Add Comment ]

JApplet, JFrame JWindow, and JDialog can all produce a Container with getContentPane( ) that can contain and display Components. In Container, there’s a method called setLayout( ) that allows you to choose a different layout manager. Other classes, such as JPanel, contain and display components directly and so you also set the layout manager directly, without using the content pane. [ Add Comment ]

In this section we’ll explore the various layout managers by placing buttons in them (since that’s the simplest thing to do). There won’t be any capturing of button events since these examples are just intended to show how the buttons are laid out. [ Add Comment ]

The applet uses a default layout scheme: the BorderLayout (a number of the previous example have changed the layout manager to FlowLayout). Without any other instruction, this takes whatever you add( ) to it and places it in the center, stretching the object all the way out to the edges. [ Add Comment ]

However, there’s more to the BorderLayout. This layout manager has the concept of four border regions and a center area. When you add something to a panel that’s using a BorderLayout you can use the overloaded add( ) method that takes a constant value as its first argument. This value can be any of the following:

BorderLayout. NORTH (top)
BorderLayout. SOUTH (bottom)
BorderLayout. EAST (right)
BorderLayout. WEST (left)
BorderLayout.CENTER (fill the middle, up to the other components or to the edges) [ Add Comment ]

If you don’t specify an area to place the object, it defaults to CENTER. [ Add Comment ]

Here’s a simple example. The default layout is used, since JApplet defaults to BorderLayout:

For every placement but CENTER, the element that you add is compressed to fit in the smallest amount of space along one dimension while it is stretched to the maximum along the other dimension. CENTER, however, spreads out in both dimensions to occupy the middle. [ Add Comment ]

This simply “flows” the components onto the form, from left to right until the top space is full, then moves down a row and continues flowing. [ Add Comment ]

Here’s an example that sets the layout manager to FlowLayout and then places buttons on the form. You’ll notice that with FlowLayout the components take on their “natural” size. A JButton, for example, will be the size of its string. [ Add Comment ]

All components will be compacted to their smallest size in a FlowLayout, so you might get a little bit of surprising behavior. For example, because a JLabel will be the size of its string, attempting to right-justify its text yields an unchanged display when using FlowLayout. [ Add Comment ]

A GridLayout allows you to build a table of components, and as you add them they are placed left-to-right and top-to-bottom in the grid. In the constructor you specify the number of rows and columns that you need and these are laid out in equal proportions. [ Add Comment ]

In this case there are 21 slots but only 20 buttons. The last slot is left empty because no “balancing” goes on with a GridLayout. [ Add Comment ]

The GridBagLayout provides you with tremendous control in deciding exactly how the regions of your window will lay themselves out and reformat themselves when the window is resized. However, it’s also the most complicated layout manager, and quite difficult to understand. It is intended primarily for automatic code generation by a GUI builder (good GUI builders will use GridBagLayout instead of absolute placement). If your design is so complicated that you feel you need to use GridBagLayout, then you should be using a GUI builder tool to generate that design. If you feel you must know the intricate details, I’ll refer you to Core Java 2 by Horstmann & Cornell (Prentice-Hall, 1999), or a dedicated Swing book, as a starting point. [ Add Comment ]

It is also possible to set the absolute position of the graphical components in this way:

Some GUI builders use this approach extensively, but this is usually not the best way to generate code. More useful GUI builders will use GridBagLayout instead. [ Add Comment ]

Because people had so much trouble understanding and working with GridBagLayout, Swing also includes the BoxLayout, which gives you many of the benefits of GridBagLayout without the complexity, so you can often use it when you need to do hand-coded layouts (again, if your design becomes too complex, use a GUI builder that generates GridBagLayouts for you). BoxLayout allows you to control the placement of components either vertically or horizontally, and to control the space between the components using something called “struts and glue.” First, let’s see how to use the BoxLayout directly, in the same way that the other layout managers have been demonstrated:

The constructor for BoxLayout is a bit different than the other layout managers—you provide the Container that is to be controlled by the BoxLayout as the first argument, and the direction of the layout as the second argument. [ Add Comment ]

To simplify matters, there’s a special container called Box that uses BoxLayout as its native manager. The following example lays out components horizontally and vertically using Box, which has two static methods to create boxes with vertical and horizontal alignment:

Once you have a Box, you pass it as a second argument when adding components to the content pane. [ Add Comment ]

Struts add space between components, measured in pixels. To use a strut, you simply add it in between the addition of the components that you want spaced apart:

Struts separate components by a fixed amount, but glue is the opposite: it separates components by as much as possible. Thus it’s more of a “spring” than “glue” (and the design on which this was based was called “springs and struts” so the choice of the term is a bit mysterious). [ Add Comment ]

A strut works in one direction, but a rigid area fixes the spacing between components in both directions:

You should be aware that rigid areas are a bit controversial. Since they use absolute values, some people feel that they cause more trouble than they are worth. [ Add Comment ]

Swing is powerful; it can get a lot done with a few lines of code. The examples shown in this book are reasonably simple, and for learning purposes it makes sense to write them by hand. You can actually accomplish quite a bit by combining simple layouts. At some point, however, it stops making sense to hand-code GUI forms—it becomes too complicated and is not a good use of your programming time. The Java and Swing designers oriented the language and libraries to support GUI building tools, which have been created for the express purpose of making your programming experience easier. As long as you understand what’s going on with layouts and how to deal with the events (described next), it’s not particularly important that you actually know the details of how to lay out components by hand—let the appropriate tool do that for you (Java is, after all, designed to increase programmer productivity). [ Add Comment ]

In the Swing event model a component can initiate (“fire”) an event. Each type of event is represented by a distinct class. When an event is fired, it is received by one or more “listeners,” which act on that event. Thus, the source of an event and the place where the event is handled can be separate. Since you typically use Swing components as they are, but need to write code that is called when the components receive an event, this is an excellent example of the separation of interface and implementation. [ Add Comment ]

Each event listener is an object of a class that implements a particular type of listener interface. So as a programmer, all you do is create a listener object and register it with the component that’s firing the event. This registration is performed by calling an addXXXListener( ) method in the event-firing component, in which “XXX” represents the type of event listened for. You can easily know what types of events can be handled by noticing the names of the “addListener” methods, and if you try to listen for the wrong events you’ll discover your mistake at compile-time. You’ll see later in the chapter that JavaBeans also use the names of the “addListener” methods to determine what events a Bean can handle. [ Add Comment ]

All of your event logic, then, will go inside a listener class. When you create a listener class, the sole restriction is that it must implement the appropriate interface. You can create a global listener class, but this is a situation in which inner classes tend to be quite useful, not only because they provide a logical grouping of your listener classes inside the UI or business logic classes they are serving, but because (as you shall see later) the fact that an inner class object keeps a reference to its parent object provides a nice way to call across class and subsystem boundaries. [ Add Comment ]

All the examples so far in this chapter have been using the Swing event model, but the remainder of this section will fill out the details of that model. [ Add Comment ]

All Swing components include addXXXListener( ) and removeXXXListener( ) methods so that the appropriate types of listeners can be added and removed from each component. You’ll notice that the “XXX” in each case also represents the argument for the method, for example: addMyListener(MyListener m). The following table includes the basic associated events, listeners, and methods, along with the basic components that support those particular events by providing the addXXXListener( ) and removeXXXListener( ) methods. You should keep in mind that the event model is designed to be extensible, so you may encounter other events and listener types that are not covered in this table.

You can see that each type of component supports only certain types of events. It turns out to be rather difficult to look up all the events supported by each component. A simpler approach is to modify the ShowMethodsClean.java program from Chapter 12 so that it displays all the event listeners supported by any Swing component that you enter.

Chapter 12 introduced reflection and used that feature to look up methods for a particular class—either the entire list of methods or a subset of those whose names match a keyword that you provide. The magic of this is that it can automatically show you all the methods for a class without forcing you to walk up the inheritance hierarchy examining the base classes at each level. Thus, it provides a valuable timesaving tool for programming: because the names of most Java methods are made nicely verbose and descriptive, you can search for the method names that contain a particular word of interest. When you find what you think you’re looking for, check the online documentation. [ Add Comment ]

However, by Chapter 12 you hadn’t seen Swing, so the tool in that chapter was developed as a command-line application. Here is the more useful GUI version, specialized to look for the “addListener” methods in Swing components:

The StripQualifiers class defined in Chapter 12 is reused here by importing the com.bruceeckel.util library. [ Add Comment ]

The GUI contains a JTextField name in which you can enter the Swing class name you want to look up. The results are displayed in a JTextArea. [ Add Comment ]

You’ll notice that there are no buttons or other components by which to indicate that you want the search to begin. That’s because the JTextField is monitored by an ActionListener. Whenever you make a change and press ENTER, the list is immediately updated. If the text isn’t empty, it is used inside Class.forName( ) to try to look up the class. If the name is incorrect, Class.forName( ) will fail, which means that it throws an exception. This is trapped and the JTextArea is set to “No match.” But if you type in a correct name (capitalization counts), Class.forName( ) is successful and getMethods( ) will return an array of Method objects. Each of the objects in the array is turned into a String via toString( ) (this produces the complete method signature) and added to n, a String array. The array n is a member of class ShowAddListeners and is used in updating the display whenever reDisplay( ) is called. [ Add Comment ]

reDisplay( ) creates an array of String called rs (for “result set”). The result set is conditionally copied from the Strings in n that contain “add” and “Listener.” indexOf( ) and substring( ) are then used to remove the qualifiers like public, static, etc. Finally, StripQualifiers.strip( ) removes the extra name qualifiers. [ Add Comment ]

This program is a convenient way to investigate the capabilities of a Swing component. Once you know which events a particular component supports, you don’t need to look anything up to react to that event. You simply:

Here are some of the listener interfaces:

This is not an exhaustive listing, partly because the event model allows you to create your own event types and associated listeners. Thus, you’ll regularly come across libraries that have invented their own events, and the knowledge gained in this chapter will allow you to figure out how to use these events.

In the table above, you can see that some listener interfaces have only one method. These are trivial to implement since you’ll implement them only when you want to write that particular method. However, the listener interfaces that have multiple methods can be less pleasant to use. For example, something you must always do when creating an application is provide a WindowListener to the JFrame so that when you get the windowClosing( ) event you can call System.exit( ) to exit the application. But since WindowListener is an interface, you must implement all of the other methods even if they don’t do anything. This can be annoying. [ Add Comment ]

To solve the problem, some (but not all) of the listener interfaces that have more than one method are provided with adapters, the names of which you can see in the table above. Each adapter provides default empty methods for each of the interface methods. Then all you need to do is inherit from the adapter and override only the methods you need to change. For example, the typical WindowListener you’ll use looks like this (remember that this has been wrapped inside the Console class in com.bruceeckel.swing):

The whole point of the adapters is to make the creation of listener classes easy. [ Add Comment ]

There is a downside to adapters, however, in the form of a pitfall. Suppose you write a WindowAdapter like the one above:

This doesn’t work, but it will drive you crazy trying to figure out why, since everything will compile and run fine—except that closing the window won’t exit the program. Can you see the problem? It’s in the name of the method: WindowClosing( ) instead of windowClosing( ). A simple slip in capitalization results in the addition of a completely new method. However, this is not the method that’s called when the window is closing, so you don’t get the desired results. Despite the inconvenience, an interface will guarantee that the methods are properly implemented. [ Add Comment ]

To prove to yourself that these events are in fact being fired, and as an interesting experiment, it’s worth creating an applet that tracks extra behavior in a JButton (other than just whether it’s pressed or not). This example also shows you how to inherit your own button object because that’s what is used as the target of all the events of interest. To do so, you can just inherit from JButton.[69] [ Add Comment ]

The MyButton class is an inner class of TrackEvent, so MyButton can reach into the parent window and manipulate its text fields, which is what’s necessary to be able to write the status information into the fields of the parent. Of course this is a limited solution, since myButton can be used only in conjunction with TrackEvent. This kind of code is sometimes called “highly coupled”:

In the MyButton constructor, the button’s color is set with a call to SetBackground( ). The listeners are all installed with simple method calls. [ Add Comment ]

The TrackEvent class contains a HashMap to hold the strings representing the type of event and JTextFields where information about that event is held. Of course, these could have been created statically rather than putting them in a HashMap, but I think you’ll agree that it’s a lot easier to use and change. In particular, if you need to add or remove a new type of event in TrackEvent, you simply add or remove a string in the event array—everything else happens automatically. [ Add Comment ]

When report( ) is called it is given the name of the event and the parameter string from the event. It uses the HashMap h in the outer class to look up the actual JTextField associated with that event name, and then places the parameter string into that field. [ Add Comment ]

This example is fun to play with since you can really see what’s going on with the events in your program. [ Add Comment ]

Now that you understand layout managers and the event model, you’re ready to see how Swing components can be used. This section is a nonexhaustive tour of the Swing components and features that you’ll probably use most of the time. Each example is intended to be reasonably small so that you can easily lift the code and use it in your own programs. [ Add Comment ]

You can easily see what each of these examples looks like while running by viewing the HTML pages in the downloadable source code for this chapter. [ Add Comment ]

Swing includes a number of different types of buttons. All buttons, check boxes, radio buttons, and even menu items are inherited from AbstractButton (which, since menu items are included, would probably have been better named “AbstractChooser” or something equally general). You’ll see the use of menu items shortly, but the following example shows the various types of buttons available: [ Add Comment ]

This begins with the BasicArrowButton from javax.swing.plaf.basic, then continues with the various specific types of buttons. When you run the example, you’ll see that the toggle button holds its last position, in or out. But the check boxes and radio buttons behave identically to each other, just clicking on or off (they are inherited from JToggleButton). [ Add Comment ]

If you want radio buttons to behave in an “exclusive or” fashion, you must add them to a “button group.” But, as the example below demonstrates, any AbstractButton can be added to a ButtonGroup. [ Add Comment ]

To avoid repeating a lot of code, this example uses reflection to generate the groups of different types of buttons. This is seen in makeBPanel( ), which creates a button group and a JPanel. The second argument to makeBPanel( ) is an array of String. For each String, a button of the class represented by the first argument is added to the JPanel:

The title for the border is taken from the name of the class, stripping off all the path information. The AbstractButton is initialized to a JButton that has the label “Failed” so if you ignore the exception message, you’ll still see the problem on screen. The getConstructor( ) method produces a Constructor object that takes the array of arguments of the types in the Class array passed to getConstructor( ). Then all you do is call newInstance( ), passing it an array of Object containing your actual arguments—in this case, just the String from the ids array. [ Add Comment ]

This adds a little complexity to what is a simple process. To get “exclusive or” behavior with buttons, you create a button group and add each button for which you want that behavior to the group. When you run the program, you’ll see that all the buttons except JButton exhibit this “exclusive or” behavior. [ Add Comment ]

You can use an Icon inside a JLabel or anything that inherits from AbstractButton (including JButton, JCheckBox, JRadioButton, and the different kinds of JMenuItem). Using Icons with JLabels is quite straightforward (you’ll see an example later). The following example explores all the additional ways you can use Icons with buttons and their descendants. [ Add Comment ]

You can use any gif files you want, but the ones used in this example are part of this book’s code distribution, available at www.BruceEckel.com. To open a file and bring in the image, simply create an ImageIcon and hand it the file name. From then on, you can use the resulting Icon in your program. [ Add Comment ]

Note that path information is hard-coded into this example; you will need to change the path to correspond to the location of the image files.

An Icon can be used in many constructors, but you can also use setIcon( ) to add or change an Icon. This example also shows how a JButton (or any AbstractButton) can set the various different sorts of icons that appear when things happen to that button: when it’s pressed, disabled, or “rolled over” (the mouse moves over it without clicking). You’ll see that this gives the button a nice animated feel. [ Add Comment ]

The previous example added a “tool tip” to the button. Almost all of the classes that you’ll be using to create your user interfaces are derived from JComponent, which contains a method called setToolTipText(String). So, for virtually anything you place on your form, all you need to do is say (for an object jc of any JComponent-derived class):

and when the mouse stays over that JComponent for a predetermined period of time, a tiny box containing your text will pop up next to the mouse. [ Add Comment ]

This example shows the extra behavior that JTextFields are capable of:

The JTextField t3 is included as a place to report when the action listener for the JTextField t1 is fired. You’ll see that the action listener for a JTextField is fired only when you press the “enter” key. [ Add Comment ]

The JTextField t1 has several listeners attached to it. The T1 listener is a DocumentListener that responds to any change in the “document” (the contents of the JTextField, in this case). It automatically copies all text from t1 into t2. In addition, t1’s document is set to a derived class of PlainDocument, called UpperCaseDocument, which forces all characters to uppercase. It automatically detects backspaces and performs the deletion, adjusting the caret and handling everything as you would expect. [ Add Comment ]

JComponent contains a method called setBorder( ), which allows you to place various interesting borders on any visible component. The following example demonstrates a number of the different borders that are available, using a method called showBorder( ) that creates a JPanel and puts on the border in each case. Also, it uses RTTI to find the name of the border that you’re using (stripping off all the path information), then puts that name in a JLabel in the middle of the panel:

You can also create your own borders and put them inside buttons, labels, etc.—anything derived from JComponent. [ Add Comment ]

Most of the time you’ll just want to let a JScrollPane do it’s job, but you can also control which scroll bars are allowed—vertical, horizontal, both, or neither:

Using different arguments in the JScrollPane constructor controls the scrollbars that are available. This example also dresses things up a bit using borders. [ Add Comment ]

The JTextPane control provides a great deal of support for editing, without much effort. The following example makes very simple use of this, ignoring the bulk of the functionality of the class:

The button just adds randomly generated text. The intent of the JTextPane is to allow text to be edited in place, so you will see that there is no append( ) method. In this case (admittedly, a poor use of the capabilities of JTextPane), the text must be captured, modified, and placed back into the pane using setText( ). [ Add Comment ]

As mentioned before, the default layout behavior of an applet is to use the BorderLayout. If you add something to the pane without specifying any details, it just fills the center of the pane out to the edges. However, if you specify one of the surrounding regions (NORTH, SOUTH, EAST, or WEST) as is done here, the component will fit itself into that region—in this case, the button will nest down at the bottom of the screen. [ Add Comment ]

Notice the built-in features of JTextPane, such as automatic line wrapping. There are lots of other features that you can look up using the JDK documentation. [ Add Comment ]

A check box provides a way to make a single on/off choice; it consists of a tiny box and a label. The box typically holds a little “x” (or some other indication that it is set) or is empty, depending on whether that item was selected. [ Add Comment ]

You’ll normally create a JCheckBox using a constructor that takes the label as an argument. You can get and set the state, and also get and set the label if you want to read or change it after the JCheckBox has been created. [ Add Comment ]

Whenever a JCheckBox is set or cleared, an event occurs, which you can capture the same way you do a button, by using an ActionListener. The following example uses a JTextArea to enumerate all the check boxes that have been checked:

The trace( ) method sends the name of the selected JCheckBox and its current state to the JTextArea using append( ), so you’ll see a cumulative list of the checkboxes that were selected and what their state is. [ Add Comment ]

The concept of a radio button in GUI programming comes from pre-electronic car radios with mechanical buttons: when you push one in, any other button that was pressed pops out. Thus, it allows you to force a single choice among many. [ Add Comment ]

All you need to do to set up an associated group of JRadioButtons is to add them to a ButtonGroup (you can have any number of ButtonGroups on a form). One of the buttons can optionally have its starting state set to true (using the second argument in the constructor). If you try to set more than one radio button to true then only the final one set will be true. [ Add Comment ]

Here’s a simple example of the use of radio buttons. Note that you capture radio button events like all others:

To display the state, a text field is used. This field is set to noneditable because it’s used only to display data, not to collect it. Thus it is an alternative to using a JLabel. [ Add Comment ]

Like a group of radio buttons, a drop-down list is a way to force the user to select only one element from a group of possibilities. However, it’s a more compact way to accomplish this, and it’s easier to change the elements of the list without surprising the user. (You can change radio buttons dynamically, but that tends to be visibly jarring). [ Add Comment ]

Java’s JComboBox box is not like the combo box in Windows, which lets you select from a list or type in your own selection. With a JComboBox box you choose one and only one element from the list. In the following example, the JComboBox box starts with a certain number of entries and then new entries are added to the box when a button is pressed. [ Add Comment ]

The JTextField displays the “selected index,” which is the sequence number of the currently selected element, as well as the label on the radio button. [ Add Comment ]

List boxes are significantly different from JComboBox boxes, and not just in appearance. While a JComboBox box drops down when you activate it, a JList occupies some fixed number of lines on a screen all the time and doesn’t change. If you want to see the items in a list, you simply call getSelectedValues( ), which produces an array of String of the items that have been selected. [ Add Comment ]

A JList allows multiple selection: if you control-click on more than one item (holding down the “control” key while performing additional mouse clicks) the original item stays highlighted and you can select as many as you want. If you select an item, then shift-click on another item, all the items in the span between the two are selected. To remove an item from a group you can control-click it. [ Add Comment ]

When you press the button it adds items to the top of the list (because addItem( )’s second argument is 0). [ Add Comment ]

You can see that borders have also been added to the lists. [ Add Comment ]

If you just want to put an array of Strings into a JList, there’s a much simpler solution: you pass the array to the JList constructor, and it builds the list automatically. The only reason for using the “list model” in the above example is so that the list could be manipulated during the execution of the program. [ Add Comment ]

JLists do not automatically provide direct support for scrolling. Of course, all you need to do is wrap the JList in a JScrollPane and all the details are automatically managed for you. [ Add Comment ]

The JTabbedPane allows you to create a “tabbed dialog,” which has file-folder tabs running across one edge, and all you have to do is press a tab to bring forward a different dialog.

In Java, the use of some sort of “tabbed panel” mechanism is quite important because in applet programming the use of pop-up dialogs is discouraged by automatically adding a little warning to any dialog that pops up out of an applet. [ Add Comment ]

When you run the program you’ll see that the JTabbedPane automatically stacks the tabs if there are too many of them to fit on one row. You can see this by resizing the window when you run the program from the console command line. [ Add Comment ]

Windowing environments commonly contain a standard set of message boxes that allow you to quickly post information to the user or to capture information from the user. In Swing, these message boxes are contained in JOptionPane. You have many different possibilities (some quite sophisticated), but the ones you’ll most commonly use are probably the message dialog and confirmation dialog, invoked using the static JOptionPane.showMessageDialog( ) and JOptionPane. showConfirmDialog( ). The following example shows a subset of the message boxes available with JOptionPane:

To be able to write a single ActionListener, I’ve used the somewhat risky approach of checking the String labels on the buttons. The problem with this is that it’s easy to get the label a little bit wrong, typically in capitalization, and this bug can be hard to spot. [ Add Comment ]

Note that showOptionDialog( ) and showInputDialog( ) provide return objects that contain the value entered by the user. [ Add Comment ]

Each component capable of holding a menu, including JApplet, JFrame, JDialog, and their descendants, has a setJMenuBar( ) method that accepts a JMenuBar (you can have only one JMenuBar on a particular component). You add JMenus to the JMenuBar, and JMenuItems to the JMenus. Each JMenuItem can have an ActionListener attached to it, to be fired when that menu item is selected. [ Add Comment ]

The use of the modulus operator in “i%3” distributes the menu items among the three JMenus. Each JMenuItem must have an ActionListener attached to it; here, the same ActionListener is used everywhere but you’ll usually need an individual one for each JMenuItem. [ Add Comment ]

JMenuItem inherits AbstractButton, so it has some buttonlike behaviors. By itself, it provides an item that can be placed on a drop-down menu. There are also three types inherited from JMenuItem: JMenu to hold other JMenuItems (so you can have cascading menus), JCheckBoxMenuItem, which produces a checkmark to indicate whether that menu item is selected, and JRadioButtonMenuItem, which contains a radio button. [ Add Comment ]

As a more sophisticated example, here are the ice cream flavors again, used to create menus. This example also shows cascading menus, keyboard mnemonics,  JCheckBoxMenuItems, and the way you can dynamically change menus:

In this program I placed the menu items into arrays and then stepped through each array calling add( ) for each JMenuItem. This makes adding or subtracting a menu item somewhat less tedious. [ Add Comment ]

This program creates not one but two JMenuBars to demonstrate that menu bars can be actively swapped while the program is running. You can see how a JMenuBar is made up of JMenus, and each JMenu is made up of JMenuItems, JCheckBoxMenuItems, or even other JMenus (which produce submenus). When a JMenuBar is assembled it can be installed into the current program with the setJMenuBar( ) method. Note that when the button is pressed, it checks to see which menu is currently installed by calling getJMenuBar( ), then it puts the other menu bar in its place. [ Add Comment ]

When testing for “Open,” notice that spelling and capitalization are critical, but Java signals no error if there is no match with “Open.” This kind of string comparison is a source of programming errors. [ Add Comment ]

The checking and unchecking of the menu items is taken care of automatically. The code handling the JCheckBoxMenuItems shows two different ways to determine what was checked: string matching (which, as mentioned above, isn’t a very safe approach although you’ll see it used) and matching on the event target object. As shown, the getState( ) method can be used to reveal the state. You can also change the state of a JCheckBoxMenuItem with setState( ). [ Add Comment ]

The events for menus are a bit inconsistent and can lead to confusion: JMenuItems use ActionListeners, but JCheckboxMenuItems use ItemListeners. The JMenu objects can also support ActionListeners, but that’s not usually helpful. In general, you’ll attach listeners to each JMenuItem, JCheckBoxMenuItem, or JRadioButtonMenuItem, but the example shows ItemListeners and ActionListeners attached to the various menu components. [ Add Comment ]

Swing supports mnemonics, or “keyboard shortcuts,” so you can select anything derived from AbstractButton (button, menu item, etc.) using the keyboard instead of the mouse. These are quite simple: for JMenuItem you can use the overloaded constructor that takes as a second argument the identifier for the key. However, most AbstractButtons do not have constructors like this so the more general way to solve the problem is to use the setMnemonic( ) method. The example above adds mnemonics to the button and some of the menu items; shortcut indicators automatically appear on the components. [ Add Comment ]

You can also see the use of setActionCommand( ). This seems a bit strange because in each case the “action command” is exactly the same as the label on the menu component. Why not just use the label instead of this alternative string? The problem is internationalization. If you retarget this program to another language, you want to change only the label in the menu, and not change the code (which would no doubt introduce new errors). So to make this easy for code that checks the text string associated with a menu component, the “action command” can be immutable while the menu label can change. All the code works with the “action command,” so it’s unaffected by changes to the menu labels. Note that in this program, not all the menu components are examined for their action commands, so those that aren’t don’t have their action command set. [ Add Comment ]

The bulk of the work happens in the listeners. BL performs the JMenuBar swapping. In ML, the “figure out who rang” approach is taken by getting the source of the ActionEvent and casting it to a JMenuItem, then getting the action command string to pass it through a cascaded if statement. [ Add Comment ]

The FL listener is simple even though it’s handling all the different flavors in the flavor menu. This approach is useful if you have enough simplicity in your logic, but in general, you’ll want to take the approach used with FooL, BarL, and BazL, in which they are each attached to only a single menu component so no extra detection logic is necessary and you know exactly who called the listener. Even with the profusion of classes generated this way, the code inside tends to be smaller and the process is more foolproof. [ Add Comment ]

You can see that menu code quickly gets long-winded and messy. This is another case where the use of a GUI builder is the appropriate solution. A good tool will also handle the maintenance of the menus. [ Add Comment ]

The most straightforward way to implement a JPopupMenu is to create an inner class that extends MouseAdapter, then add an object of that inner class to each component that you want to produce pop-up behavior:

The same ActionListener is added to each JMenuItem, so that it fetches the text from the menu label and inserts it into the JTextField. [ Add Comment ]

In a good GUI framework, drawing should be reasonably easy—and it is, in the Swing library. The problem with any drawing example is that the calculations that determine where things go are typically a lot more complicated that the calls to the drawing routines, and these calculations are often mixed together with the drawing calls so it can seem that the interface is more complicated than it actually is. [ Add Comment ]

For simplicity, consider the problem of representing data on the screen—here, the data will be provided by the built-in Math.sin( ) method which is a mathematical sine function. To make things a little more interesting, and to further demonstrate how easy it is to use Swing components, a slider will be placed at the bottom of the form to dynamically control the number of sine wave cycles that are displayed. In addition, if you resize the window, you’ll see that the sine wave refits itself to the new window size. [ Add Comment ]

Although any JComponent may be painted and thus used as a canvas, if you just want a straightforward drawing surface you will typically inherit from a JPanel. The only method you need to override is paintComponent( ), which is called whenever that component must be repainted (you normally don’t need to worry about this, as the decision is managed by Swing). When it is called, Swing passes a Graphics object to the method, and you can then use this object to draw or paint on the surface. [ Add Comment ]

In the following example, all the intelligence concerning painting is in the SineDraw class; the SineWave class simply configures the program and the slider control. Inside SineDraw, the setCycles( ) method provides a hook to allow another object—the slider control, in this case—to control the number of cycles.

All of the data members and arrays are used in the calculation of the sine wave points: cycles indicates the number of complete sine waves desired, points contains the total number of points that will be graphed, sines contains the sine function values, and pts contains the y-coordinates of the points that will be drawn on the JPanel. The setCycles( ) method creates the arrays according to the number of points needed and fills the sines array with numbers. By calling repaint( ) , setCycles( ) forces paintComponent( ) to be called so the rest of the calculation and redraw will take place. [ Add Comment ]

The first thing you must do when you override paintComponent( ) is to call the base-class version of the method. Then you are free to do whatever you like; normally, this means using the Graphics methods that you can find in the documentation for java.awt.Graphics (in the HTML documentation from java.sun.com) to draw and paint pixels onto the JPanel. Here, you can see that almost all the code is involved in performing the calculations; the only two method calls that actually manipulate the screen are setColor( ) and drawLine( ). You will probably have a similar experience when creating your own program that displays graphical data—you’ll spend most of your time figuring out what it is you want to draw, but the actual drawing process will be quite simple. [ Add Comment ]

When I created this program, the bulk of my time was spent in getting the sine wave to display. Once I did that, I thought it would be nice to be able to dynamically change the number of cycles. My programming experiences when trying to do such things in other languages made me a bit reluctant to try this, but it turned out to be the easiest part of the project. I created a JSlider (the arguments are the left-most value of the JSlider, the right-most value, and the starting value, respectively, but there are other constructors as well) and dropped it into the JApplet. Then I looked at the HTML documentation and noticed that the only listener was the addChangeListener, which was triggered whenever the slider was changed enough for it to produce a different value. The only method for this was the obviously named stateChanged( ), which provided a ChangeEvent object so that I could look backward to the source of the change and find the new value. By calling the sines object’s setCycles( ), the new value was incorporated and the JPanel redrawn. [ Add Comment ]

In general, you will find that most of your Swing problems can be solved by following a similar process, and you’ll find that it’s generally quite simple, even if you haven’t used a particular component before. [ Add Comment ]

If your problem is more complex, there are other more sophisticated alternatives for drawing, including third-party JavaBeans components and the Java 2D API. These solutions are beyond the scope of this book, but you should look them up if your drawing code becomes too onerous. [ Add Comment ]

A dialog box is a window that pops up out of another window. Its purpose is to deal with some specific issue without cluttering the original window with those details. Dialog boxes are heavily used in windowed programming environments, but less frequently used in applets. [ Add Comment ]

To create a dialog box, you inherit from JDialog, which is just another kind of Window, like a JFrame. A JDialog has a layout manager (which defaults to BorderLayout) and you add event listeners to deal with events. One significant difference when windowClosing( ) is called is that you don’t want to shut down the application. Instead, you release the resources used by the dialog’s window by calling dispose( ). Here’s a very simple example:

Once the JDialog is created, the show( ) method must be called to display and activate it. For the dialog to close, it must call dispose( ). [ Add Comment ]

You’ll see that anything that pops up out of an applet, including dialog boxes, is “untrusted.” That is, you get a warning in the window that’s been popped up. This is because, in theory, it would be possible to fool the user into thinking that they’re dealing with a regular native application and to get them to type in their credit card number, which then goes across the Web. An applet is always attached to a Web page and visible within your Web browser, while a dialog box is detached—so in theory, it could be possible. As a result it is not so common to see an applet that uses a dialog box. [ Add Comment ]

The following example is more complex; the dialog box is made up of a grid (using GridLayout) of a special kind of button that is defined here as class ToeButton. This button draws a frame around itself and, depending on its state, a blank, an “x,” or an “o” in the middle. It starts out blank, and then depending on whose turn it is, changes to an “x” or an “o.” However, it will also flip back and forth between “x” and “o” when you click on the button. (This makes the tic-tac-toe concept only slightly more annoying than it already is.) In addition, the dialog box can be set up for any number of rows and columns by changing numbers in the main application window.

Because statics can only be at the outer level of the class, inner classes cannot have static data or static inner classes. [ Add Comment ]

The paintComponent( ) method draws the square around the panel, and the “x” or the “o.” This is full of tedious calculations, but it’s straightforward. [ Add Comment ]

A mouse click is captured by the MouseListener, which first checks to see if the panel has anything written on it. If not, the parent window is queried to find out whose turn it is and that is used to establish the state of the ToeButton. Via the inner class mechanism, the ToeButton then reaches back into the parent and changes the turn. If the button is already displaying an “x” or an “o” then that is flopped. You can see in these calculations the convenient use of the ternary if-else described in Chapter 3. After a state change, the ToeButton is repainted. [ Add Comment ]

The constructor for ToeDialog is quite simple: it adds into a GridLayout as many buttons as you request, then resizes it for 50 pixels on a side for each button. [ Add Comment ]

TicTacToe sets up the whole application by creating the JTextFields (for inputting the rows and columns of the button grid) and the “go” button with its ActionListener. When the button is pressed, the data in the JTextFields must be fetched, and, since they are in String form, turned into ints using the static Integer.parseInt( ) method. [ Add Comment ]

Some operating systems have a number of special built-in dialog boxes to handle the selection of things such as fonts, colors, printers, and the like. Virtually all graphical operating systems support the opening and saving of files, however, and so Java’s JFileChooser encapsulates these for easy use. [ Add Comment ]

The following application exercises two forms of JFileChooser dialogs, one for opening and one for saving. Most of the code should by now be familiar, and all the interesting activities happen in the action listeners for the two different button clicks:

Note that there are many variations you can apply to JFileChooser, including filters to narrow the file names that you will allow. [ Add Comment ]

For an “open file” dialog, you call showOpenDialog( ), and for a “save file” dialog you call showSaveDialog( ). These commands don’t return until the dialog is closed. The JFileChooser object still exists, so you can read data from it. The methods getSelectedFile( ) and getCurrentDirectory( ) are two ways you can interrogate the results of the operation. If these return null it means the user canceled out of the dialog. [ Add Comment ]

Any component that can take text can also take HTML text, which it will reformat according to HTML rules. This means you can very easily add fancy text to a Swing component. For example,

You must start the text with “<html>,” and then you can use normal HTML tags. Note that you are not forced to include the normal closing tags. [ Add Comment ]

The ActionListener adds a new JLabel to the form, which also contains HTML text. However, this label is not added during init( ) so you must call the container’s validate( ) method in order to force a re-layout of the components (and thus the display of the new label). [ Add Comment ]

You can also use HTML text for JTabbedPane, JMenuItem, JToolTip, JRadioButton and JCheckBox. [ Add Comment ]

A slider (which has already been used in the sine wave example) allows the user to input data by moving a point back and forth, which is intuitive in some situations (volume controls, for example). A progress bar displays data in a relative fashion from “full” to “empty” so the user gets a perspective. My favorite example for these is to simply hook the slider to the progress bar so when you move the slider the progress bar changes accordingly:

The key to hooking the two components together is in sharing their model, in the line: [ Add Comment ]

The JProgressBar is fairly straightforward, but the JSlider has a lot of options, such as the orientation and major and minor tick marks. Notice how straightforward it is to add a titled border. [ Add Comment ]

Using a JTree can be as simple as saying:

This displays a primitive tree. The API for trees is vast, however—certainly one of the largest in Swing. It appears that you can do just about anything with trees, but more sophisticated tasks might require quite a bit of research and experimentation. [ Add Comment ]

Fortunately, there is a middle ground provided in the library: the “default” tree components, which generally do what you need. So most of the time you can use these components, and only in special cases will you need to delve in and understand trees more deeply. [ Add Comment ]

The following example uses the “default” tree components to display a tree in an applet. When you press the button, a new subtree is added under the currently selected node (if no node is selected, the root node is used): [ Add Comment ]

The first class, Branch, is a tool to take an array of String and build a DefaultMutableTreeNode with the first String as the root and the rest of the Strings in the array as leaves. Then node( ) can be called to produce the root of this “branch.” [ Add Comment ]

The Trees class contains a two-dimensional array of Strings from which Branches can be made and a static int i to count through this array. The DefaultMutableTreeNode objects hold the nodes, but the physical representation on screen is controlled by the JTree and its associated model, the DefaultTreeModel. Note that when the JTree is added to the applet, it is wrapped in a JScrollPane—this is all it takes to provide automatic scrolling. [ Add Comment ]

The JTree is controlled through its model. When you make a change to the model, the model generates an event that causes the JTree to perform any necessary updates to the visible representation of the tree. In init( ), the model is captured by calling getModel( ). When the button is pressed, a new “branch” is created. Then the currently selected component is found (or the root is used if nothing is selected) and the model’s insertNodeInto( ) method does all the work of changing the tree and causing it to be updated. [ Add Comment ]

An example like the one above may give you what you need in a tree. However, trees have the power to do just about anything you can imagine—everywhere you see the word “default” in the example above, you can substitute your own class to get different behavior. But beware: almost all of these classes have a large interface, so you could spend a lot of time struggling to understand the intricacies of trees. Despite this, it’s a good design and the alternatives are usually much worse. [ Add Comment ]

Like trees, tables in Swing are vast and powerful. They are primarily intended to be the popular “grid” interface to databases via Java Database Connectivity (JDBC, discussed in Chapter 15) and thus they have a tremendous amount of flexibility, which you pay for in complexity. There’s easily enough here to be the basis of a full-blown spreadsheet and could probably justify an entire book. However, it is also possible to create a relatively simple JTable if you understand the basics. [ Add Comment ]

The JTable controls how the data is displayed, but the TableModel controls the data itself. So to create a JTable you’ll typically create a TableModel first. You can fully implement the TableModel interface, but it’s usually simpler to inherit from the helper class AbstractTableModel:

DataModel contains an array of data, but you could also get the data from some other source such as a database. The constructor adds a TableModelListener that prints the array every time the table is changed. The rest of the methods follow the Beans naming convention, and are used by JTable when it wants to present the information in DataModel. AbstractTableModel provides default methods for setValueAt( ) and isCellEditable( ) that prevent changes to the data, so if you want to be able to edit the data, you must override these methods. [ Add Comment ]

Once you have a TableModel, you only need to hand it to the JTable constructor. All the details of displaying, editing, and updating will be taken care of for you. This example also puts the JTable in a JScrollPane. [ Add Comment ]

One of the very interesting aspects of Swing is the “Pluggable Look & Feel.” This allows your program to emulate the look and feel of various operating environments. You can even do all sorts of fancy things like dynamically changing the look and feel while the program is executing. However, you generally just want to do one of two things, either select the “cross platform” look and feel (which is Swing’s “metal”), or select the look and feel for the system you are currently on, so your Java program looks like it was created specifically for that system. The code to select either of these behaviors is quite simple—but you must execute it before you create any visual components, because the components will be made based on the current look and feel and will not be changed just because you happen to change the look and feel midway during the program (that process is more complicated and uncommon, and is relegated to Swing-specific books). [ Add Comment ]

Actually, if you want to use the cross-platform (“metal”) look and feel that is characteristic of Swing programs, you don’t have to do anything—it’s the default. But if you want instead to use the current operating environment’s look and feel, you just insert the following code, typically at the beginning of your main( ) but somehow before any components are added:

You don’t need anything in the catch clause because the UIManager will default to the cross-platform look and feel if your attempts to set up any of the alternatives fail. However, during debugging the exception can be quite useful so you may at least want to put a print statement in the catch clause. [ Add Comment ]

Here is a program that takes a command-line argument to select a look and feel, and shows how several different components look under the chosen look and feel:

You can see that one option is to explicitly specify a string for a look and feel, as seen with MotifLookAndFeel. However, that one and the default “metal” look and feel are the only ones that can legally be used on any platform; even though there are strings for Windows and Macintosh look and feels, those can only be used on their respective platforms (these are produced when you call getSystemLookAndFeelClassName( ) and you’re on that particular platform). [ Add Comment ]

It is also possible to create a custom look and feel package, for example, if you are building a framework for a company that wants a distinctive appearance. This is a big job and is far beyond the scope of this book (in fact, you’ll discover it is beyond the scope of many dedicated Swing books!). [ Add Comment ]

The JFC supports limited operations with the system clipboard (in the java.awt.datatransfer package). You can copy String objects to the clipboard as text, and you can paste text from the clipboard into String objects. Of course, the clipboard is designed to hold any type of data, but how this data is represented on the clipboard is up to the program doing the cutting and pasting. The Java clipboard API provides for extensibility through the concept of a “flavor.” When data comes off the clipboard, it has an associated set of flavors that it can be converted to (for example, a graph might be represented as a string of numbers or as an image) and you can see if that particular clipboard data supports the flavor you’re interested in. [ Add Comment ]

The following program is a simple demonstration of cut, copy, and paste with String data in a JTextArea. One thing you’ll notice is that the keyboard sequences you normally use for cutting, copying, and pasting also work. But if you look at any JTextField or JTextArea in any other program you’ll find that they also automatically support the clipboard key sequences. This example simply adds programmatic control of the clipboard, and you could use these techniques if you want to capture clipboard text into something other than a JTextComponent.

The creation and addition of the menu and JTextArea should by now seem a pedestrian activity. What’s different is the creation of the Clipboard field clipbd, which is done through the Toolkit. [ Add Comment ]

All the action takes place in the listeners. The CopyL and CutL listeners are the same except for the last line of CutL, which erases the line that’s been copied. The special two lines are the creation of a StringSelection object from the String and the call to setContents( ) with this StringSelection. That’s all there is to putting a String on the clipboard. [ Add Comment ]

In PasteL, data is pulled off the clipboard using getContents( ). What comes back is a fairly anonymous Transferable object, and you don’t really know what it contains. One way to find out is to call getTransferDataFlavors( ), which returns an array of DataFlavor objects indicating which flavors are supported by this particular object. You can also ask it directly with isDataFlavorSupported( ), passing in the flavor you’re interested in. Here, however, the bold approach is taken: getTransferData( ) is called assuming that the contents supports the String flavor, and if it doesn’t the problem is sorted out in the exception handler. [ Add Comment ]

In the future you can expect more data flavors to be supported.

An important use of the JAR utility is to optimize applet loading. In Java 1.0, people tended to try to cram all their code into a single applet class so the client would need only a single server hit to download the applet code. Not only did this result in messy, hard to read (and maintain) programs, but the .class file was still uncompressed so downloading wasn’t as fast as it could have been. [ Add Comment ]

JAR files solve the problem by compressing all of your .class files into a single file that is downloaded by the browser. Now you can create the right design without worrying about how many .class files it will generate, and the user will get a much faster download time. [ Add Comment ]

Consider TicTacToe.java. It looks like a single class, but in fact it contains five inner classes, so that’s six in all. Once you’ve compiled the program, you package it into a JAR file with the line:

This assumes that the only .class files in the current directory are the ones from TicTacToe.java (otherwise you’ll get extra baggage). [ Add Comment ]

Now you can create an HTML page with the new archive tag to indicate the name of the JAR file. Here is the tag using the old form of the HTML tag, as an illustration:

Because GUI programming in Java has been an evolving technology with some very significant changes between Java 1.0/1.1 and the Swing library in Java 2, there have been some old programming idioms that have seeped through to examples that you might see given for Swing. In addition, Swing allows you to program in more and better ways than were allowed by the old models. In this section, some of these issues will be demonstrated by introducing and examining some programming idioms. [ Add Comment ]

One of the benefits of the Swing event model is flexibility. You can add and remove event behavior with single method calls. The following example demonstrates this:

The new twists in this example are: [ Add Comment ]

This kind of flexibility provides much greater power in your programming. [ Add Comment ]

You should notice that event listeners are not guaranteed to be called in the order they are added (although most implementations do in fact work that way). [ Add Comment ]

Another issue is multitiered systems, where the “business objects” reside on a completely separate machine. This central location of the business rules allows changes to be instantly effective for all new transactions, and is thus a compelling way to set up a system. However, these business objects can be used in many different applications and so should not be tied to any particular mode of display. They should just perform the business operations and nothing more. [ Add Comment ]

The following example shows how easy it is to separate the business logic from the GUI code:

You can see that BusinessLogic is a straightforward class that performs its operations without even a hint that it might be used in a GUI environment. It just does its job. [ Add Comment ]

Separation keeps track of all the UI details, and it talks to BusinessLogic only through its public interface. All the operations are centered around getting information back and forth through the UI and the BusinessLogic object. So Separation, in turn, just does its job. Since Separation knows only that it’s talking to a BusinessLogic object (that is, it isn’t highly coupled), it could be massaged into talking to other types of objects without much trouble. [ Add Comment ]

Thinking in terms of separating UI from business logic also makes life easier when you’re adapting legacy code to work with Java. [ Add Comment ]

Inner classes, the Swing event model, and the fact that the old event model is still supported along with new library features that rely on old-style programming has added a new element of confusion to the code design process. Now there are even more different ways for people to write unpleasant code. [ Add Comment ]

Except in extenuating circumstances you can always use the simplest and clearest approach: listener classes (typically written as inner classes) to solve your event-handling needs. This is the form used in most of the examples in this chapter. [ Add Comment ]

By following this model you should be able to reduce the statements in your programs that say: “I wonder what caused this event.” Each piece of code is concerned with doing, not type-checking. This is the best way to write your code; not only is it easier to conceptualize, but much easier to read and maintain. [ Add Comment ]

So far in this book you’ve seen how valuable Java is for creating reusable pieces of code. The “most reusable” unit of code has been the class, since it comprises a cohesive unit of characteristics (fields) and behaviors (methods) that can be reused either directly via composition or through inheritance. [ Add Comment ]

Inheritance and polymorphism are essential parts of object-oriented programming, but in the majority of cases when you’re putting together an application, what you really want is components that do exactly what you need. You’d like to drop these parts into your design like the electronic engineer puts together chips on a circuit board. It seems, too, that there should be some way to accelerate this “modular assembly” style of programming. [ Add Comment ]

“Visual programming” first became successful—very successful—with Microsoft’s Visual Basic (VB), followed by a second-generation design in Borland’s Delphi (the primary inspiration for the JavaBeans design). With these programming tools the components are represented visually, which makes sense since they usually display some kind of visual component such as a button or a text field. The visual representation, in fact, is often exactly the way the component will look in the running program. So part of the process of visual programming involves dragging a component from a palette and dropping it onto your form. The application builder tool writes code as you do this, and that code will cause the component to be created in the running program. [ Add Comment ]

Simply dropping the component onto a form is usually not enough to complete the program. Often, you must change the characteristics of a component, such as what color it is, what text is on it, what database it’s connected to, etc. Characteristics that can be modified at design time are referred to as properties. You can manipulate the properties of your component inside the application builder tool, and when you create the program this configuration data is saved so that it can be rejuvenated when the program is started. [ Add Comment ]

By now you’re probably used to the idea that an object is more than characteristics; it’s also a set of behaviors. At design-time, the behaviors of a visual component are partially represented by events, meaning “Here’s something that can happen to the component.” Ordinarily, you decide what you want to happen when an event occurs by tying code to that event. [ Add Comment ]

Here’s the critical part: the application builder tool uses reflection to dynamically interrogate the component and find out which properties and events the component supports. Once it knows what they are, it can display the properties and allow you to change those (saving the state when you build the program), and also display the events. In general, you do something like double-clicking on an event and the application builder tool creates a code body and ties it to that particular event. All you have to do at that point is write the code that executes when the event occurs. [ Add Comment ]

All this adds up to a lot of work that’s done for you by the application builder tool. As a result you can focus on what the program looks like and what it is supposed to do, and rely on the application builder tool to manage the connection details for you. The reason that visual programming tools have been so successful is that they dramatically speed up the process of building an application—certainly the user interface, but often other portions of the application as well. [ Add Comment ]

After the dust settles, then, a component is really just a block of code, typically embodied in a class. The key issue is the ability for the application builder tool to discover the properties and events for that component. To create a VB component, the programmer had to write a fairly complicated piece of code following certain conventions to expose the properties and events. Delphi was a second-generation visual programming tool and the language was actively designed around visual programming so it is much easier to create a visual component. However, Java has brought the creation of visual components to its most advanced state with JavaBeans, because a Bean is just a class. You don’t have to write any extra code or use special language extensions in order to make something a Bean. The only thing you need to do, in fact, is slightly modify the way that you name your methods. It is the method name that tells the application builder tool whether this is a property, an event, or just an ordinary method. [ Add Comment ]

In the Java documentation, this naming convention is mistakenly termed a “design pattern.” This is unfortunate, since design patterns (see Thinking in Patterns with Java, downloadable at www.BruceEckel.com) are challenging enough without this sort of confusion. It’s not a design pattern, it’s just a naming convention and it’s fairly simple:

Point 1 above answers a question about something you might have noticed when looking at older code vs. newer code: a number of method names have had small, apparently meaningless name changes. Now you can see that most of those changes had to do with adapting to the “get” and “set” naming conventions in order to make that particular component into a Bean. [ Add Comment ]

First, you can see that it’s just a class. Usually, all your fields will be private, and accessible only through methods. Following the naming convention, the properties are jumps, color, spots, and jumper (notice the case change of the first letter in the property name). Although the name of the internal identifier is the same as the name of the property in the first three cases, in jumper you can see that the property name does not force you to use any particular identifier for internal variables (or, indeed, to even have any internal variables for that property). [ Add Comment ]

The events this Bean handles are ActionEvent and KeyEvent, based on the naming of the “add” and “remove” methods for the associated listener. Finally, you can see that the ordinary method croak( ) is still part of the Bean simply because it’s a public method, not because it conforms to any naming scheme. [ Add Comment ]

One of the most critical parts of the Bean scheme occurs when you drag a Bean off a palette and plop it onto a form. The application builder tool must be able to create the Bean (which it can do if there’s a default constructor) and then, without access to the Bean’s source code, extract all the necessary information to create the property sheet and event handlers. [ Add Comment ]

Part of the solution is already evident from the end of Chapter 12: Java reflection allows all the methods of an anonymous class to be discovered. This is perfect for solving the Bean problem without requiring you to use any extra language keywords like those required in other visual programming languages. In fact, one of the prime reasons that reflection was added to Java was to support Beans (although reflection also supports object serialization and remote method invocation). So you might expect that the creator of the application builder tool would have to reflect each Bean and hunt through its methods to find the properties and events for that Bean. [ Add Comment ]

This is certainly possible, but the Java designers wanted to provide a standard tool, not only to make Beans simpler to use but also to provide a standard gateway to the creation of more complex Beans. This tool is the Introspector class, and the most important method in this class is the static getBeanInfo( ). You pass a Class reference to this method and it fully interrogates that class and returns a BeanInfo object that you can then dissect to find properties, methods, and events. [ Add Comment ]

Usually you won’t care about any of this—you’ll probably get most of your Beans off the shelf from vendors, and you don’t need to know all the magic that’s going on underneath. You’ll simply drag your Beans onto your form, then configure their properties and write handlers for the events you’re interested in. However, it’s an interesting and educational exercise to use the Introspector to display information about a Bean, so here’s a tool that does it:

BeanDumper.dump( ) is the method that does all the work. First it tries to create a BeanInfo object, and if successful calls the methods of BeanInfo that produce information about properties, methods, and events. In Introspector.getBeanInfo( ), you’ll see there is a second argument. This tells the Introspector where to stop in the inheritance hierarchy. Here, it stops before it parses all the methods from Object, since we’re not interested in seeing those. [ Add Comment ]

For properties, getPropertyDescriptors( ) returns an array of PropertyDescriptors. For each PropertyDescriptor you can call getPropertyType( ) to find the class of object that is passed in and out via the property methods. Then, for each property you can get its pseudonym (extracted from the method names) with getName( ), the method for reading with getReadMethod( ), and the method for writing with getWriteMethod( ). These last two methods return a Method object that can actually be used to invoke the corresponding method on the object (this is part of reflection). [ Add Comment ]

For the public methods (including the property methods), getMethodDescriptors( ) returns an array of MethodDescriptors. For each one you can get the associated Method object and print its name. [ Add Comment ]

For the events, getEventSetDescriptors( ) returns an array of (what else?) EventSetDescriptors. Each of these can be queried to find out the class of the listener, the methods of that listener class, and the add- and remove-listener methods. The BeanDumper program prints out all of this information. [ Add Comment ]

Upon startup, the program forces the evaluation of frogbean.Frog. The output, after removing extra details that are unnecessary here, is:

This reveals most of what the Introspector sees as it produces a BeanInfo object from your Bean. You can see that the type of the property and its name are independent. Notice the lowercasing of the property name. (The only time this doesn’t occur is when the property name begins with more than one capital letter in a row.) And remember that the method names you’re seeing here (such as the read and write methods) are actually produced from a Method object that can be used to invoke the associated method on the object. [ Add Comment ]

The public method list includes the methods that are not associated with a property or event, such as croak( ), as well as those that are. These are all the methods that you can call programmatically for a Bean, and the application builder tool can choose to list all of these while you’re making method calls, to ease your task. [ Add Comment ]

Finally, you can see that the events are fully parsed out into the listener, its methods, and the add- and remove-listener methods. Basically, once you have the BeanInfo, you can find out everything of importance for the Bean. You can also call the methods for that Bean, even though you don’t have any other information except the object (again, a feature of reflection). [ Add Comment ]

This next example is slightly more sophisticated, albeit frivolous. It’s a JPanel that draws a little circle around the mouse whenever the mouse is moved. When you press the mouse, the word “Bang!” appears in the middle of the screen, and an action listener is fired. [ Add Comment ]

The properties you can change are the size of the circle as well as the color, size, and text of the word that is displayed when you press the mouse. A BangBean also has its own addActionListener( ) and removeActionListener( ) so you can attach your own listener that will be fired when the user clicks on the BangBean. You should be able to recognize the property and event support:

The first thing you’ll notice is that BangBean implements the Serializable interface. This means that the application builder tool can “pickle” all the information for the BangBean using serialization after the program designer has adjusted the values of the properties. When the Bean is created as part of the running application, these “pickled” properties are restored so that you get exactly what you designed. [ Add Comment ]

You can see that all the fields are private, which is what you’ll usually do with a Bean—allow access only through methods, usually using the “property” scheme. [ Add Comment ]

When you look at the signature for addActionListener( ), you’ll see that it can throw a TooManyListenersException. This indicates that it is unicast, which means it notifies only one listener when the event occurs. Ordinarily, you’ll use multicast events so that many listeners can be notified of an event. However, that runs into issues that you won’t be ready for until the next chapter, so it will be revisited there (under the heading “JavaBeans revisited”). A unicast event sidesteps the problem. [ Add Comment ]

When you click the mouse, the text is put in the middle of the BangBean, and if the actionListener field is not null, its actionPerformed( ) is called, creating a new ActionEvent object in the process. Whenever the mouse is moved, its new coordinates are captured and the canvas is repainted (erasing any text that’s on the canvas, as you’ll see). [ Add Comment ]

Here is the BangBeanTest class to allow you to test the bean as either an applet or an application:

When a Bean is in a development environment, this class will not be used, but it’s helpful to provide a rapid testing method for each of your Beans. BangBeanTest places a BangBean within the applet, attaching a simple ActionListener to the BangBean to print an event count to the JTextField whenever an ActionEvent occurs. Usually, of course, the application builder tool would create most of the code that uses the Bean. [ Add Comment ]

When you run the BangBean through BeanDumper or put the BangBean inside a Bean-enabled development environment, you’ll notice that there are many more properties and actions than are evident from the above code. That’s because BangBean is inherited from JPanel, and JPanel is also Bean, so you’re seeing its properties and events as well. [ Add Comment ]

Before you can bring a Bean into a Bean-enabled visual builder tool, it must be put into the standard Bean container, which is a JAR file that includes all the Bean classes as well as a “manifest” file that says “This is a Bean.” A manifest file is simply a text file that follows a particular form. For the BangBean, the manifest file looks like this (without the first and last lines):

The first line indicates the version of the manifest scheme, which until further notice from Sun is 1.0. The second line (empty lines are ignored) names the BangBean.class file, and the third says, “It’s a Bean.” Without the third line, the program builder tool will not recognize the class as a Bean. [ Add Comment ]

The only tricky part is that you must make sure that you get the proper path in the “Name:” field. If you look back at BangBean.java, you’ll see it’s in package bangbean (and thus in a subdirectory called “bangbean” that’s off of the classpath), and the name in the manifest file must include this package information. In addition, you must place the manifest file in the directory above the root of your package path, which in this case means placing the file in the directory above the “bangbean” subdirectory. Then you must invoke jar from the same directory as the manifest file, as follows:

This assumes that you want the resulting JAR file to be named BangBean.jar and that you’ve put the manifest in a file called BangBean.mf. [ Add Comment ]

You might wonder “What about all the other classes that were generated when I compiled BangBean.java?” Well, they all ended up inside the bangbean subdirectory, and you’ll see that the last argument for the above jar command line is the bangbean subdirectory. When you give jar the name of a subdirectory, it packages that entire subdirectory into the jar file (including, in this case, the original BangBean.java source-code file—you might not choose to include the source with your own Beans). In addition, if you turn around and unpack the JAR file you’ve just created, you’ll discover that your manifest file isn’t inside, but that jar has created its own manifest file (based partly on yours) called MANIFEST.MF and placed it inside the subdirectory META-INF (for “meta-information”). If you open this manifest file you’ll also notice that digital signature information has been added by jar for each file, of the form:

In general, you don’t need to worry about any of this, and if you make changes you can just modify your original manifest file and reinvoke jar to create a new JAR file for your Bean. You can also add other Beans to the JAR file simply by adding their information to your manifest. [ Add Comment ]

One thing to notice is that you’ll probably want to put each Bean in its own subdirectory, since when you create a JAR file you hand the jar utility the name of a subdirectory and it puts everything in that subdirectory into the JAR file. You can see that both Frog and BangBean are in their own subdirectories. [ Add Comment ]

Once you have your Bean properly inside a JAR file you can bring it into a Beans-enabled program-builder environment. The way you do this varies from one tool to the next, but Sun provides a freely available test bed for JavaBeans in their “Beans Development Kit” (BDK) called the “beanbox.” (Download the BDK from java.sun.com/beans.) To place your Bean in the beanbox, copy the JAR file into the BDK’s “jars” subdirectory before you start up the beanbox. [ Add Comment ]

You can see how remarkably simple it is to make a Bean. But you aren’t limited to what you’ve seen here. The JavaBeans architecture provides a simple point of entry but can also scale to more complex situations. These situations are beyond the scope of this book, but they will be briefly introduced here. You can find more details at java.sun.com/beans. [ Add Comment ]

One place where you can add sophistication is with properties. The examples above have shown only single properties, but it’s also possible to represent multiple properties in an array. This is called an indexed property. You simply provide the appropriate methods (again following a naming convention for the method names) and the Introspector recognizes an indexed property so your application builder tool can respond appropriately. [ Add Comment ]

Properties can be bound, which means that they will notify other objects via a PropertyChangeEvent. The other objects can then choose to change themselves based on the change to the Bean. [ Add Comment ]

Properties can be constrained, which means that other objects can veto a change to that property if it is unacceptable. The other objects are notified using a PropertyChangeEvent, and they can throw a PropertyVetoException to prevent the change from happening and to restore the old values. [ Add Comment ]

You can also change the way your Bean is represented at design time: [ Add Comment ]

There’s another issue that couldn’t be addressed here. Whenever you create a Bean, you should expect that it will be run in a multithreaded environment. This means that you must understand the issues of threading, which will be introduced in Chapter 14. You’ll find a section there called “JavaBeans revisited” that will look at the problem and its solution. [ Add Comment ]

There are a number of books about JavaBeans; for example, JavaBeans by Elliotte Rusty Harold (IDG, 1998). [ Add Comment ]

Of all the libraries in Java, the GUI library has seen the most dramatic changes from Java 1.0 to Java 2. The Java 1.0 AWT was roundly criticized as being one of the worst designs seen, and while it would allow you to create portable programs, the resulting GUI was “equally mediocre on all platforms.” It was also limiting, awkward, and unpleasant to use compared with the native application development tools available on a particular platform. [ Add Comment ]

When Java 1.1 introduced the new event model and JavaBeans, the stage was set—now it was possible to create GUI components that could be easily dragged and dropped inside visual application builder tools. In addition, the design of the event model and Beans clearly shows strong consideration for ease of programming and maintainable code (something that was not evident in the 1.0 AWT). But it wasn’t until the JFC/Swing classes appeared that the job was finished. With the Swing components, cross-platform GUI programming can be a civilized experience. [ Add Comment ]

Actually, the only thing that’s missing is the application builder tool, and this is where the real revolution lies. Microsoft’s Visual Basic and Visual C++ require Microsoft’s application builder tools, as does Borland’s Delphi and C++ Builder. If you want the application builder tool to get better, you have to cross your fingers and hope the vendor will give you what you want. But Java is an open environment, and so not only does it allow for competing application builder environments, it encourages them. And for these tools to be taken seriously, they must support JavaBeans. This means a leveled playing field: if a better application builder tool comes along, you’re not tied to the one you’ve been using—you can pick up and move to the new one and increase your productivity. This kind of competitive environment for GUI application builder tools has not been seen before, and the resulting marketplace can generate only positive results for the productivity of the programmer. [ Add Comment ]

If you don’t see what you need here, delve into the online documentation from Sun and search the Web, and if that’s not enough then find a dedicated Swing book—a good place to start is The JFC Swing Tutorial, by Walrath & Campione (Addison Wesley, 1999). [ Add Comment ]

Solutions to selected exercises can be found in the electronic document The Thinking in Java Annotated Solution Guide, available for a small fee from www.BruceEckel.com.

[61] A variation on this is called “the principle of least astonishment,” which essentially says: “don’t surprise the user.”

[62] This is an example of the design pattern called the template method.

[63] It is assumed that the reader is familiar with the basics of HTML. It’s not too hard to figure out, and there are lots of books and resources.

[64] This page—in particular, the ‘clsid’ portion—seemed to work fine with both JDK1.2.2 and JDK1.3 rc-1. However, you may find that you have to change the tag sometime in the future. Details can be found at java.sun.com.

[65] In my opinion. And after you learn about Swing, you won’t want to waste your time on the earlier stuff.

[66] As described earlier, “Frame” was already taken by the AWT, so Swing uses JFrame.

[67] This will make sense after you’ve read further in this chapter. First, make the reference JApplet a static member of the class (instead of a local variable of main( )), and then call applet.stop( ) and applet.destroy( ) inside WindowAdapter.windowClosing( ) before you call System.exit( ).

[68] There is no MouseMotionEvent even though it seems like there ought to be. Clicking and motion is combined into MouseEvent, so this second appearance of MouseEvent in the table is not an error.

[69] In Java 1.0/1.1 you could not usefully inherit from the button object. This was only one of numerous fundamental design flaws.