How to Make Frames (Main Windows)

Most Swing applications present their primary GUIs within a JFrame -- a top-level Swing container that provides windows for applets and applications. A frame has decorations such as a border, a title, and buttons for closing and iconifying the window. A typical program simply creates a frame, adds components to its content pane, and perhaps adds a menu bar. However, through its root pane, JFrame provides support for further customization.
To make a window that's dependent on another window -- disappearing when the other window is iconified, for example -- use a dialog instead of a frame. To make a window that appears within another window, use an internal frame.
Here are two pictures of the same program, FrameDemo.java, running on different platforms. The program brings up a frame that contains something interesting to look at.

Solaris Windows

[PENDING: run this on
Windows and get a snapshot]

Note: The specific decorations on a frame are system-dependent. You cannot change the decorations on a frame.

Below is the code from FrameDemo.java that creates the frame in the previous example.
public static void main(String s[]) {
    JFrame frame = new JFrame("A Basic Frame");

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

    JLabel aLabel = new JLabel("Something to look at",
                                       new ImageIcon("images/beach.gif"),
                                       JLabel.CENTER);
    aLabel.setVerticalTextPosition(JLabel.TOP);
    aLabel.setHorizontalTextPosition(JLabel.CENTER);
    frame.getContentPane().add(aLabel, BorderLayout.CENTER);

    frame.pack();
    frame.setVisible(true);
}
The code creates a frame with the title A Basic Frame and adds a window listener to it that will exit the program when the user closes the frame.
The italic lines of code create the label that displays the text and image in the frame. This is essentially this program's GUI. If you use this program as a framework for your own program, replace the italicized code to create the components that make up your program's GUI.
The bold line adds the label to the frame's content pane. Refer to Adding Components to a Frame for further details and examples.
For a frame to appear on the screen, a program must either call setSize or pack, and then call setVisible(true) or its equivalent, show. This program packs the frame and uses setVisible. Note that if any of the GUI is already visible, you should invoke setVisible from the event dispatching thread. Refer to the Threads and Swing page.
This code is typical of many programs and is the framework we used to create many of the examples for this lesson (including GlassPaneDemo.java and BorderDemo.java). Some examples in this lesson, such as TextFieldDemo.java and TableDemo.java, subclass JFrame and instantiate the frame subclass instead of JFrame. In these programs, the GUI is created in the constructor for the subclass. You might do this in your programs if you need to subclass JFrame for some reason.
JFrame itself is a subclass of java.awt.Frame to which it adds support for interposing input and painting behavior in front of the frame's children, placing children on different "layers", and for Swing menu bars. Generally speaking, you should use a JFrame instead of a Frame, for these reasons:

To take advantage of new features provided by its root pane such as the glass pane and the layered pane.
JFrame lets you customize window closing behavior by calling the setDefaultCloseOperation method instead of writing a window listener.
JFrame supports the revalidate method. [PENDING: link to where revalidate is discussed]
Swing menus work best in a JFrame due to its setJMenuBar method.
You must use a JFrame in an applet if the applet uses Swing components. Also, we recommend that you use a JFrame in an application that uses Swing components, although it's not required.

Adding Components to a Frame
As you saw in FrameDemo.java, to add components to a JFrame, you add them to the frame's content pane. Two common techniques are used to provide the components for a frame's content pane:
Create a container such as a JPanel, a JScrollPane, or a JTabbedPane, add components to it, then use JFrame.setContentPane to make it the frame's content pane.
TableDemo.java uses this technique. The code creates a scroll pane to use as the frame's content pane. A table is in the scroll pane:
public class TableDemo extends JFrame {

    public TableDemo() {
        super("TableDemo");

        MyTableModel myModel = new MyTableModel();
        JTable table = new JTable(myModel);
        table.setPreferredScrollableViewportSize(new Dimension(500, 70));

        //Create the scroll pane and add the table to it.
        JScrollPane scrollPane = new JScrollPane(table);

        //Add the scroll pane to this window.
        setContentPane(scrollPane);

	. . .
Use JFrame.getContentPane to get the frame's content pane. Add components to the object returned. LayeredPaneDemo.java uses this technique as shown here:
...//create the components...
//get the content pane, add components to it: 
Container contentPane = getContentPane();
// use a layout manager that respects preferred sizes
contentPane.setLayout(new BoxLayout(contentPane, BoxLayout.Y_AXIS));
contentPane.add(Box.createRigidArea(new Dimension(0, 10)));
contentPane.add(controls);
contentPane.add(Box.createRigidArea(new Dimension(0, 10)));
contentPane.add(emptyArea);
The default layout manager for a frame's content pane is BorderLayout. As the preceding example shows, you can invoke the setLayout method on the content pane to change its layout manager.
The JFrame API

The following tables list the commonly used JFrame constructors and methods. Other methods you're likely to call are defined by the Frame and Window classes and include pack, setSize, show, hide, setVisible, setTitle, and getTitle.
Much of the operation of a frame is managed by other objects. For example, the interior of a frame is managed by its root pane, and the content pane contains the frame's GUI. Most of the API for using frames is related to Setting and Getting the Frame's Helper Objects.
The API for using frames falls into two categories:

Creating and Setting Up a Frame
Setting or Getting the Frame's Helper Objects

Creating and Setting Up a Frame
Method Purpose
JFrame() JFrame(String) Create a frame. The String argument provides a title for the frame.
void setDefaultCloseOperation(int) int getDefaultCloseOperation() Set or get the operation that occurs when the user pushes the close button on this frame. Possible choices are:

DO_NOTHING_ON_CLOSE
HIDE_ON_CLOSE (the default)
DISPOSE_ON_CLOSE
These constants are defined in the WindowConstants interface.

Setting and Getting the Frame's Helper Objects
Method Purpose
void setContentPane(Container) Container getContentPane() Set or get the frame's content pane. You can also set or get this through the frame's root pane.
JRootPane createRootPane() void setRootPane(JRootPane) JRootPane getRootPane() Create, set, or get the frame's root pane. The root pane manages the interior of the frame including the content pane, the glass pane, and so on.
void setJMenuBar(JMenuBar) JMenuBar getJMenuBar() Set or get the frame's menu bar. You can also set or get this through the frame's root pane.
void setGlassPane(Component) Component getGlassPane() Set or get the frame's glass pane. You can also set or get this through the frame's root pane.
void setLayeredPane(JLayeredPane) JLayeredPane getLayeredPane() Set or get the frame's layered pane. You can also set or get this through the frame's root pane.

Examples that Use Frames

This table lists examples that use JFrame and where those examples are described.

Example Where Described Notes
FrameDemo.java This page. A basic frame with one component.
TextFieldDemo.java How to Use Text Fields A subclass of JFrame.
TableDemo.java How to Use Tables A subclass of JFrame that sets the frame's content pane.
IconDemoApplet.java How to Use Icons Adds many components to the default content pane.
LayeredPaneDemo.java How to Use Layered Panes Illustrates the use of a frame's layered pane.
GlassPaneDemo.java The Glass Pane Illustrates the use of a frame's glass pane.
MenuDemo.java How to Use Menus Shows how to put a JMenuBar in a JFrame.

Solaris	Windows
	[PENDING: run this on Windows and get a snapshot]

Creating and Setting Up a Frame
Method	Purpose
`JFrame() JFrame(String)`	Create a frame. The `String` argument provides a title for the frame.
`void setDefaultCloseOperation(int) int getDefaultCloseOperation()`	Set or get the operation that occurs when the user pushes the close button on this frame. Possible choices are: `DO_NOTHING_ON_CLOSE` `HIDE_ON_CLOSE` (the default) `DISPOSE_ON_CLOSE` These constants are defined in the `WindowConstants` interface.

Setting and Getting the Frame's Helper Objects
Method	Purpose
`void setContentPane(Container) Container getContentPane()`	Set or get the frame's content pane. You can also set or get this through the frame's root pane.
`JRootPane createRootPane() void setRootPane(JRootPane) JRootPane getRootPane()`	Create, set, or get the frame's root pane. The root pane manages the interior of the frame including the content pane, the glass pane, and so on.
`void setJMenuBar(JMenuBar) JMenuBar getJMenuBar()`	Set or get the frame's menu bar. You can also set or get this through the frame's root pane.
`void setGlassPane(Component) Component getGlassPane()`	Set or get the frame's glass pane. You can also set or get this through the frame's root pane.
`void setLayeredPane(JLayeredPane) JLayeredPane getLayeredPane()`	Set or get the frame's layered pane. You can also set or get this through the frame's root pane.

Example	Where Described	Notes
`FrameDemo.java`	This page.	A basic frame with one component.
`TextFieldDemo.java`	How to Use Text Fields	A subclass of `JFrame`.
`TableDemo.java`	How to Use Tables	A subclass of `JFrame` that sets the frame's content pane.
`IconDemoApplet.java`	How to Use Icons	Adds many components to the default content pane.
`LayeredPaneDemo.java`	How to Use Layered Panes	Illustrates the use of a frame's layered pane.
`GlassPaneDemo.java`	The Glass Pane	Illustrates the use of a frame's glass pane.
`MenuDemo.java`	How to Use Menus	Shows how to put a `JMenuBar` in a `JFrame`.

Using the JFC/Swing Packages