Using the JFC/Swing Packages

How to Use Layered Panes

A layered pane is a Swing container that provides a third dimension for positioning components: depth, also known as Z order. When adding a component to a layered pane, you specify its depth. Frames at a higher depth always overlap frames at a lower depth and frames at a lower depth are always under frames at a higher depth. Frames at the same depth can switch positions. For convenience, layered pane defines several layers within the possible range of depths for specific functions. For example, you can put a component on the highest functional layer, the drag layer, when dragging components.

Every Swing container that has a root pane -- such as JFrame, JApplet, JDialog, and JInternalFrame -- automatically has a layered pane, although many programs don't explicitly use the layered pane. You can also create your own layered pane and use it anywhere you can use a regular Swing container.

Swing provides two layered pane classes. The first, JLayeredPane, is the class that root panes use. The second, JDesktopPane, is a JLayeredPane subclass that's specialized for the task of holding internal frames. The example in this section uses an instance of JLayeredPane. For examples of using JDesktopPane, see How to Use Internal Frames.

Here's a picture of a demo application that uses a layered pane to manage JInternalFrames on different layers:

---

Try this:

1. Compile and run the application. The source file is LayeredPaneDemo.java. You will also need five image files: Bird.gif, Cat.gif, Dog.gif, Rabbit.gif, and Pig.gif.
   See Getting Started with Swing if you need help compiling or running the program.
2. On startup, the program creates five internal frames. To create another frame, select a layer from the combo box then click the Create a Frame button.
3. Move the frames around. Notice the relationship of the frames on different layers and frames on the same layer.
4. Note that you can drag the internal frames over the controls at the top of the program. The controls are in the main frame's content pane which is on a layer that is lower than all of the layers available from the menu.

---

The JFrame, JApplet, JDialog, and JInternalFrame classes provide a convenience method, getLayeredPane, for getting their root pane's layered pane. LayeredPaneDemo.java uses this method to get the layered pane to which it adds the internal frames:

public class LayeredPaneDemo extends JFrame ... {
    ...
    public LayeredPaneDemo() {
        ...
        layeredPane = getLayeredPane();
    ...

Now here's the code that creates and adds internal frames to the layered pane:

private void addNewInternalFrame(int index) {
    JInternalFrame newFrame = new JInternalFrame();
    ...
    numFrames++;
    newFrame.setBounds(30*(numFrames%10), 30*(numFrames%10)+55, 200, 160);
    ...
    Integer layer = layerValues[index];
    layeredPane.add(newFrame, layer);
    try { newFrame.setSelected(true); } catch (java.beans.PropertyVetoException e2) {}
}

The bold lines show where the frame is added to the layered pane. The add method used in this program takes two arguments. The first is the component to add; the second is an Integer indicating the depth at which to put the component. The value can be any Integer. However, most programs will use one of those defined by the JLayeredPane class:

	Layer Name	Value	Description
	FRAME_CONTENT_LAYER	new Integer(-30000)	This layer is used to position the frame's content pane and menu bar. Most programs won't use this.
	DEFAULT_LAYER	new Integer(0)	Most components go in this layer.
	PALETTE_LAYER	new Integer(100)	This layer is useful for floating toolbars and palettes.
	MODAL_LAYER	new Integer(200)	Modal dialogs, such as those provided by JOptionPane, belong in this layer.
	POPUP_LAYER	new Integer(300)	Popups go in this layer because they need to appear above just about everything.
	DRAG_LAYER	new Integer(400)	Move a component to this layer when dragging. Return the component to its regular layer when dropped.

A component's position determines its relationship with other components on the same layer. Unlike layer numbers, the lower the position number, the higher the component within its layer.

You can set a component's position when you add it to a layered pane by providing a third argument to the add method. Positions are specified with an int between -1 and (N-1), where N is the number of components in the layer. Using -1 is the same as using N-1; it indicates the bottom-most position. Using 0 specifies that the component should be in the topmost position within its layer. As the following figure shows, with the exception of -1, a lower position number indicates a higher position within a layer.

Both a component's layer and its relative position within its layer can change. To change a component's layer, you typically use the setLayer method. To change a component's position within its layer, you usually use the moveToBack and moveToFront methods provided by JLayeredPane.

---

A Note of Caution: When adding a component to a layered pane you specify the layer with an Integer. When using setLayer to change a component's layer, you use an int. Use the API tables below to check the types of the arguments and return values for other methods in this class that deal with layers.

---

The Layered Pane API

The following tables list the commonly used JLayeredPane constructors and methods. Other methods you're likely to call are defined by the JComponent and Component classes and include [PENDING: anything in particular for JLayeredPane?]. [Link to JComponent and Component discussions.]

The API for using layered pane falls into these categories:

• Creating or Getting a Layered Pane
• Layering Components
• Positioning Components Within a Layer

Creating or Getting a Layered Pane

Method	Purpose
JLayeredPane()	Create a layered pane.
JLayeredPane getLayeredPane() (in JApplet, JDialog, JFrame, and JInternalFrame)	Get the layered pane in an applet, dialog, frame, or internal frame.

Layering Components

Method	Purpose
void add(Component, Integer) void add(Component, Integer, int)	Add the specified component to the layered pane. The second argument indicates the layer. The third argument, when present, indicates the component's position within its layer.
void setLayer(Component, int) void setLayer(Component, int, int)	Change the component's layer. The second argument indicates the layer. The third argument, when present, indicates the component's position within its layer.
int getLayer(Component) int getLayer(JComponent)	Get the layer for the specified component.
int getComponentCountInLayer(int)	Get the number of components in the specified layer. The value returned by this method can be useful for computing position values.
Component[] getComponentsInLayer(int)	Get an array of all the components in the specified layer.
int highestLayer() int lowestLayer()	Compute the highest or lowest layer currently in use.

Positioning Components Within a Layer

Method	Purpose
void setPosition(Component, int) int getPosition(Component)	Set or get the position for the specified component within its layer.
void moveToFront(Component) void moveToBack(Component)	Move the specified component to the front or back of its layer.

Examples that Use Layered Panes

This table shows the examples that use JLayeredPane and where those examples are described.

Example	Where Described	Notes
LayeredPaneDemo.java	This page.	Illustrates layers and intra-layer positions of a JLayeredPane.
InternalFrameDemo.java	How to Use Internal Frames	Uses a JDesktopFrame to manage internal frames.

Using the JFC/Swing Packages