How to Use Root Panes

Using Top-Level Containers tells you the basics of using root panes — getting the content pane, setting its layout manager, and adding Swing components to it. This section tells you more about root panes, including the components that make up a root pane and how you can use them.

The glass pane

Hidden, by default. If you make the glass pane visible, then it's like a sheet of glass over all the other parts of the root pane. It's completely transparent unless you implement the glass pane's paintComponent method so that it does something, and it can intercept input events for the root pane. In the next section, you'll see an example of using a glass pane.

The layered pane

Serves to position its contents, which consist of the content pane and the optional menu bar. Can also hold other components in a specified Z order. For information, see The Layered Pane.

The content pane

The container of the root pane's visible components, excluding the menu bar. For information on using the content pane, see Using Top-Level Containers.

The optional menu bar

The home for the root pane's container's menus. If the container has a menu bar, you generally use the container's setJMenuBar method to put the menu bar in the appropriate place. For more information on using menus and menu bars, see How to Use Menus.

The Glass Pane

Here's a picture of an application that demonstrates glass pane features. It contains a check box that lets you set whether the glass pane is "visible" — whether it can get events and paint itself onscreen. When the glass pane is visible, it blocks all input events from reaching the components in the content pane. It also paints a red dot in the place where it last detected a mouse-pressed event.

The following code from GlassPaneDemo.java shows and hides the glass pane. This program happens to create its own glass pane. However, if a glass pane doesn't do any painting, the program might simply attach listeners to the default glass pane, as returned by getGlassPane.

myGlassPane = new MyGlassPane(...);
changeButton.addItemListener(myGlassPane);
frame.setGlassPane(myGlassPane);
...
class MyGlassPane extends JComponent
                  implements ItemListener {
    ...
    //React to change button clicks.
    public void itemStateChanged(ItemEvent e) {
        setVisible(e.getStateChange() == ItemEvent.SELECTED);
    }
...
}

The next code snippet implements the mouse-event handling for the glass pane. If a mouse event occurs over the check box, then the glass pane redispatches the event so that the check box receives it.

...//In the implementation of the glass pane's mouse listener:
public void mouseMoved(MouseEvent e) {
    redispatchMouseEvent(e, false);
}

.../* The mouseDragged, mouseClicked, mouseEntered,
    * mouseExited, and mousePressed methods have the same
    * implementation as mouseMoved. */...

public void mouseReleased(MouseEvent e) {
    redispatchMouseEvent(e, true);
}

private void redispatchMouseEvent(MouseEvent e,
                                  boolean repaint) {
    Point glassPanePoint = e.getPoint();
    Container container = contentPane;
    Point containerPoint = SwingUtilities.convertPoint(
                                    glassPane,
                                    glassPanePoint,
                                    contentPane);

    if (containerPoint.y < 0) { //we're not in the content pane
        //Could have special code to handle mouse events over
        //the menu bar or non-system window decorations, such as
        //the ones provided by the Java look and feel.
    } else {
        //The mouse event is probably over the content pane.
        //Find out exactly which component it's over.
        Component component =
            SwingUtilities.getDeepestComponentAt(
                                    container,
                                    containerPoint.x,
                                    containerPoint.y);

        if ((component != null)
            && (component.equals(liveButton))) {
            //Forward events over the check box.
            Point componentPoint = SwingUtilities.convertPoint(
                                        glassPane,
                                        glassPanePoint,
                                        component);
            component.dispatchEvent(new MouseEvent(component,
                                                 e.getID(),
                                                 e.getWhen(),
                                                 e.getModifiers(),
                                                 componentPoint.x,
                                                 componentPoint.y,
                                                 e.getClickCount(),
                                                 e.isPopupTrigger()));
        }
    }

    //Update the glass pane if requested.
    if (repaint) {
        glassPane.setPoint(glassPanePoint);
        glassPane.repaint();
    }
}

protected void paintComponent(Graphics g) {
    if (point != null) {
        g.setColor(Color.red);
        g.fillOval(point.x - 10, point.y - 10, 20, 20);
    }
}

The Layered Pane

Each root pane places its menu bar and content pane in an instance of JLayeredPane. The Z ordering that the layered pane provides enables behavior such as displaying popup menus above other components.

You can choose to put components in the root pane's layered pane. If you do, then you should be aware that certain depths are defined to be used for specific functions, and you should use the depths as intended. Otherwise, your components might not play well with the others. Here's a diagram that shows the functional layers and their relationship:

Here is a picture of RootLayeredPaneDemo, which is a version of LayeredPaneDemo that uses the root pane's layered pane, rather than creating a new layered pane.

The Root Pane API

• Using a Root Pane
• Setting or Getting the Root Pane's Contents

The API for using other parts of the root pane is described elsewhere:

• The Layered Pane API
• The Menu API

Using a Root Pane

Method	Purpose
JRootPane getRootPane() (in JApplet, JDialog, JFrame, JInternalFrame, and JWindow)	Get the root pane of the applet, dialog, frame, internal frame, or window.
static JRootPane getRootPane(Component) (in SwingUtilities)	If the component contains a root pane, return that root pane. Otherwise, return the root pane (if any) that contains the component.
JRootPane getRootPane() (in JComponent)	Invoke the SwingUtilities getRootPane method for the JComponent.
void setDefaultButton(JButton) JButton getDefaultButton()	Set or get which button (if any) is the default button in the root pane. A look-and-feel-specific action, such as pressing Enter, causes the button's action to be performed.

Setting or Getting the Root Pane's Contents
The following methods are defined in JApplet, JDialog, JFrame, JInternalFrame, JRootPane, and JWindow, unless noted otherwise.

Method	Purpose
void setGlassPane(Component) Component getGlassPane()	Set or get the glass pane.
void setLayeredPane(JLayeredPane) Container getLayeredPane()	Set or get the layered pane.
void setContentPane(Container) Container getContentPane()	Set or get the content pane.
void setJMenuBar(JMenuBar) JMenuBar getJMenuBar() (not defined in JWindow)	Set or get the menu bar.

Examples that Use Root Panes

• Examples that Use Layered Panes
• Examples that Use Menus
• Examples that Use Frames (for examples of using content panes)

Example	Where Described	Notes
GlassPaneDemo	This section	Uses a glass pane that paints a bit and redispatches events.
RootLayeredPaneDemo	This section	Adapts LayeredPaneDemo to use the root pane's layered pane.
ListDialog	How to Use Lists	Sets the default button for a JDialog.
FrameDemo2	How to Make Frames	Sets the default button for a JFrame.