General Rules for Using Swing Components

This section has general information on how to write a program that contains Swing components. Two important things to remember are to avoid using non-Swing heavyweight components, and to put your Swing components into a top-level Swing container.
[PENDING: This page has some overlap with Swing Features and Concepts . We need to remove confusing/unnecessary overlap.]
The Swing package defines two types of components:

top-level containers (JFrame, JApplet, JWindow, JDialog)
lightweight components (Jeverything-else, such as JButton, JPanel, and JMenu)

The top-level containers provide the framework in which the lightweight components exist. Specifically, a top-level Swing container provides an area in which lightweight Swing components can draw themselves. Top-level Swing containers also provide Swing features such as menu-bar placement, enhanced event handling and painting, and accessibility support.
In general, every Swing component should have a top-level Swing container above it in the container hierarchy. For example, every applet containing Swing components should be implemented as a subclass of JApplet (which is itself a subclass of Applet). Similarly, every main window that contains Swing components should be implemented with a JFrame.
Here's a picture of the GUI hierarchy for a typical Swing program that implements a window containing two buttons, a text field, and a list:
Here's another hierarchy figure for the same GUI, except that the GUI is in an applet running in a browser:

The content pane in the preceding figures is an ordinary Container that's under every top-level Swing container. A top-level Swing container is a Swing subclass of a heavyweight AWT component. Top-level Swing containers add Swing necessities -- including a content pane -- to the heavyweight AWT component.
Here's the code that constructs the GUI hierarchies shown in the preceding figures:
//Set up the JPanel, which contains the text field and list.
JPanel panel = new JPanel();
panel.setLayout(new SomeLayoutManager());
panel.add(textField);
panel.add(list);

//topLevel is an instance of JApplet or JFrame
Container contentPane = topLevel.getContentPane();
contentPane.setLayout(new AnotherLayoutManager());
contentPane.add(button1);
contentPane.add(button2);
contentPane.add(panel);
Note: You cannot add a component directly to a top-level component:
    topLevel.add(something);  //CAN'T DO THIS!!!
In general, you should avoid using heavyweight components in Swing GUIs (except for the top-level Swing container that hosts the GUI, of course). The most noticeable problem with mixing heavyweight and lightweight components is that when they overlap within a container, the heavyweight component is always drawn on top of the lightweight component. See Mixing Heavy and Light Components in The Swing Connection for more information about mixing the two types of components.

Using Swing Components