Using Top-Level Containers

Figure 10 shows a snapshot and a diagram of a frame. The frame contains a menu bar (with no menus ) and, in the frame's content pane, a large blank label.

You can find the entire source for this example in TopLevelDemo.java . [4] Although the example uses a JFrame in a standalone application, the same concepts apply to JApplet s and JDialog s. [4] You can find the source files for TopLevelDemo on the CD at: JavaTutorial/uiswing/components/example-1dot4/index.html#TopLevelDemo .

The containment hierarchy for this example's GUI appears in Figure 11.

As the ellipses imply, we left some details. We'll reveal them a bit later.

Top-Level Containers and Containment Hierarchies

As we mentioned in the previous chapter, each program that uses Swing components has at least one top-level container. This top-level container is the root of a containment hierarchy that contains all of the Swing components that appear inside it.

As a rule, a standalone application with a Swing-based GUI has at least one containment hierarchy with a JFrame as its root. For example, if an application has one main window and two dialogs, it has three containment hierarchies and thus three top-level containers. One containment hierarchy has a JFrame as its root, and each of the other two has a JDialog object as its root.

A Swing-based applet has at least one containment hierarchy, exactly one of which is rooted by a JApplet object. For example, an applet that brings up a dialog has two containment hierarchies. The components in the browser window are in a containment hierarchy rooted by a JApplet object. The dialog has a containment hierarchy rooted by a JDialog object.

Note: To view the containment hierarchy for any frame or dialog, click its border to select it and then press Control-Shift-F1. The containment hierarchy will be written to the standard output stream.

Adding Components to the Content Pane

Here's the code that the preceding example uses to get a frame's content pane and to add the label to it:

frame.getContentPane().add(yellowLabel, BorderLayout.CENTER);

As shown, you find the content pane of a top-level container by calling the getContentPane method. The default content pane is a simple intermediate container that inherits from JComponent and uses a BorderLayout as its layout manager.

It's easy to customize the content pane ”setting the layout manager or adding a border, for example. However, there's one tiny hitch. The getContentPane method returns a Container object, not a JComponent object. This means that if you want to take advantage of the content pane's JComponent features you need to either typecast the return value or create your own component to be the content pane. Our examples generally take the second approach since it's a little cleaner. Another approach we sometimes take is to simply add a customized component to the content pane that covers it completely.

If you create your own content pane, make sure it's opaque. An opaque JPanel object makes a good content pane. Note that the default layout manager for JPanel is FlowLayout ; you'll probably want to change it.

To make a component the content pane, use the top-level container's setContentPane method. For example:

//Create a panel and add components to it.

JPanel contentPane = new JPanel(new BorderLayout());

contentPane.setBorder(someBorder);

contentPane.add(someComponent, BorderLayout.CENTER);

contentPane.add(anotherComponent, BorderLayout.PAGE_END);



//Make it the content pane.

contentPane.setOpaque(true);

topLevelContainer.setContentPane(contentPane);

Note: Don't use nonopaque containers such as JScrollPane , JSplitPane , and JTabbedPane as content panes. A nonopaque content pane results in messy repaints. Although you can make any Swing component opaque by invoking setOpaque(true) on it, some components don't look right that way. For example, tabbed panes generally let part of the underlying container show through so that the tabs look nonrectangular. An opaque tabbed pane just tends to look bad. In most look and feels, JPanel s are opaque by default. However, JPanel s in the GTK+ look and feel, which was introduced in v1.4.2, are not initially opaque. To be safe, we invoke set-Opaque on all JPanel s used as content panes.

frame.setJMenuBar(cyanMenuBar);