Getting Started

The best way to learn how to use any programming technology is usually through hands-on experience, so to learn how to use Swing let's start by creating the "Hello, world!" application in Listing 1:

import javax.swing.JFrame; public class HelloWorld { public static void main(String[] args) { JFrame frame = new JFrame(); frame.setTitle("Hello, world!"); frame.setSize(400, 225); frame.setVisible(true); } }
Listing 1: A simple "Hello, world!" Swing application.

If you compile and run this program, a window like the one shown in Figure 1 will appear in the upper left corner of your screen. In this case the Java application was run on Windows 7 with Aero enabled, but depending upon your operating system and its settings, the window that appears when you run the program may be somewhat different.
'Hello, world!' application window
Figure 1: Window displayed when running the "Hello, world!" application running on Windows 7 with Aero.
This type of window is called a frame and is created by instantiating an instance of the JFrame class. The frame should look familiar because most desktop applications -- including your browser -- provide a frame that serves as the main window for the application.

The term desktop application in this context refers to an application that runs directly on your computer and provides a user interface without using a web browser. In contrast, a web application is accessed through a browser, and as implied here, the browser itself is really just another desktop application.
Likewise, when you create a Swing application, you should design it to create and display a frame when the application is started. Some applications initially show a splash screen, but otherwise a frame is typically the first window displayed and it should be the center of information and activity for the application until it's closed. In fact, closing an application's frame is usually interpreted as a request to terminate the application itself, because the frame represents the application's user interface (UI) and if you no longer have access to the application's UI then by definition you can no longer interact with the application.

The relationship just described between a frame and its application isn't dictated by Swing; it's simply a convention used by programmers, and closing a frame doesn't automatically cause Java to terminate the application that created it. Instead, the application is usually implemented in such a way that it receives a notification that its user has indicated that the frame should be closed, and when that notification occurs the application terminates itself. This approach allows an application to be shut down gracefully so that, for example, if unsaved work exists the program can prompt the user to save that work before the program terminates itself. We'll examine the notification mechanism in detail later on, but for now the key point to be aware of is that closing a frame doesn't automatically shut down the application that created it.

Another point worth noting with respect to frames and their corresponding applications is that it's usually a good practice for an application to create only a single frame. There's no technical limitation that prevents you from creating more than one, but you should think of the frame as the focal point of your user interface, and a UI that displays multiple frames is likely to be confusing to its users.

Frames can usually be distinguished from the other types of window by the presence of a title bar with buttons like the ones shown in Figure 2:
Contents of a title bar
Figure 2: The composition of a title bar.
The buttons shown here are:

  • Minimize- Replaces the frame with an icon representation of it that's displayed in a location such as the Windows task bar as shown in Figure 3. A minimized frame can be made visible again ("restored") by clicking on the icon.
  • Maximize- Expands the frame to fill the screen. While a frame is maximized its Maximize button is replaced by a Restore button that causes the frame to return to its previous (pre-maximization) size.
  • Close- Makes the frame disappear and usually also causes the application that created it to terminate, though as mentioned earlier the specific behavior is determined by the application.
A minimized JFrame
Figure 3: A minimized JFrame in the Windows task bar.
Other characteristics of a frame include its ability to be resized by dragging its sides and corners, and to be moved to a different location on the screen by dragging its title bar. The Windows operating system also supports a popup menu like the one shown in Figure 4 that's triggered by clicking on the icon at the left side of the title bar. That popup menu supports the same frame actions (minimize, maximize / restore, close, move, resize) described here, but not every operating system provides a popup menu for its frames.
Popup menu supported on Windows
Figure 4: A popup menu on Windows.
Having defined the capabilities of a frame, let's go back and review the HelloWorld application to understand what each line in it is doing.

Understanding the Code

Our HelloWorld program starts out the same way as any Java application: with the definition of a static main() method that allows the class to act as the entry point of a thread created by a Java Virtual Machine (JVM). Inside that main() method, the first statement is a standard variable declaration and assignment that defines a local variable named frame and assigns to it a reference to a newly created JFrame object. That class is defined in the javax.swing package, which is where most of the Swing classes you'll use are defined.
JFrame frame = new JFrame();
After the frame is instantiated three mutator (or "setter") methods are called, and these types of method invocations are common in Swing applications, because it's common to need to set various properties to achieve the results you want. In this case, we're setting the newly created frame's title, size, and visibility properties:
frame.setTitle("Hello, world!"); frame.setSize(400, 225); frame.setVisible(true);
Setting the frame's title is easy to understand because the string passed to setTitle() is the same text that appears in the title bar when we run the application. A frame has no title by default so if you were to remove the call to setTitle() and run the application again you'd see a frame like the one shown in Listing 5:
A frame with no title (the default)
Figure 5: The result of not setting a title.
The next line in the program sets the frame's size
In practice, you normally shouldn't explicitly assign an arbitrary size to a Swing object as we've done here. Instead, you should let it choose its own size, and we'll see in a later section how this can be done.
and includes a pair of int parameter values:
frame.setSize(400, 225);
These parameters define how large the frame should be in pixels: the first value indicates that the frame should be 400 pixels wide and the second that it should have a height of 225 pixels. The last of the setter statements in the program updates the frame's visibility property:
frame.setVisible(true);
When a frame -- or, for that matter, any other type of window -- is created in Java it's invisible by default, which means that it doesn't appear on the screen and never will appear until its visibility property is changed as was done here.

Components

Finally, it's helpful to introduce you to an important bit of terminology that you'll often encounter when discussing Swing code. Specifically, a component is a class (or an instance of a class) that has a visual representation. For example, we've seen that a JFrame instance has a visual representation, so JFrame is an example of a component. The name "component" comes from the fact that in Swing all "widget" types directly or indirectly extend the Component class, and Oracle's definition of a component is shown below:

A component is an object having a graphical representation that can be displayed on the screen and that can interact with the user. Examples of components are the buttons, checkboxes, and scrollbars of a typical graphical user interface.
This distinction is important because as we'll see, Swing also includes many classes that don't have visual representations, but instead provide useful functionality that supports the construction of user interface code.