layeredpane.html

jsf、swing的官方指南

<div class="linkBHEAD"><a href="passwordfield.html">How to Use Password Fields</a></div>
<div class="linkBHEAD"><a href="progress.html">How to Use Progress Bars</a></div>
<div class="linkBHEAD"><a href="rootpane.html">How to Use Root Panes</a></div>
<div class="linkBHEAD"><a href="scrollpane.html">How to Use Scroll Panes</a></div>
<div class="linkBHEAD"><a href="separator.html">How to Use Separators</a></div>
<div class="linkBHEAD"><a href="slider.html">How to Use Sliders</a></div>
<div class="linkBHEAD"><a href="spinner.html">How to Use Spinners</a></div>
<div class="linkBHEAD"><a href="splitpane.html">How to Use Split Panes</a></div>
<div class="linkBHEAD"><a href="tabbedpane.html">How to Use Tabbed Panes</a></div>
<div class="linkBHEAD"><a href="table.html">How to Use Tables</a></div>
<div class="linkBHEAD"><a href="textarea.html">How to Use Text Areas</a></div>
<div class="linkBHEAD"><a href="textfield.html">How to Use Text Fields</a></div>
<div class="linkBHEAD"><a href="toolbar.html">How to Use Tool Bars</a></div>
<div class="linkBHEAD"><a href="tooltip.html">How to Use Tool Tips</a></div>
<div class="linkBHEAD"><a href="tree.html">How to Use Trees</a></div>
<div class="linkAHEAD"><a href="icon.html">How to Use Icons</a></div>
<div class="linkAHEAD"><a href="border.html">How to Use Borders</a></div>
<div class="linkAHEAD"><a href="problems.html">Solving Common Component Problems</a></div>
</div>
    </div>
    <div id=MainFlow class=MainFlow_indented>
            <span id=BreadCrumbs>
                <a href=../../index.html target=_top>Home Page</a>
                &gt;
                <a href=../index.html target=_top>Creating a GUI with JFC/Swing</a>
                &gt;
                <a href=index.html target=_top>Using Swing Components</a>
            </span>
            <div class=NavBit>
                <a target=_top href=label.html>&laquo;&nbsp;Previous</a>&nbsp;&bull;&nbsp;<a target=_top href=../TOC.html>Trail</a>&nbsp;&bull;&nbsp;<a target=_top href=list.html>Next&nbsp;&raquo;</a>
            </div>
            <div id=PageTitle>How to Use Layered Panes</div>
            <blockquote>
A layered pane
is a Swing container that provides a third dimension 
for positioning components:
<em>depth</em>, also known as <em>Z order</em>.
When adding a component to a layered pane,
you specify its depth as an integer.
The higher the number, the higher the depth.
If components overlap,
components at a higher depth are drawn
on top of components at a lower depth.
The relationship between components at the same depth
is determined by their positions within the depth.

<blockquote><hr><strong>Version note:</strong>&nbsp;In 1.5, we expect that API will be added to allow
direct manipulation of a <code>Component</code>'s Z order
within a container.  When this is available, you won't
need to use a <code>JLayeredPane</code> to assign a
Z order to a lightweight component.
<hr></blockquote>

<p>
Every Swing container that has a 
<a href="rootpane.html">root pane</a> &#151;
such as 
<a href="frame.html"><code>JFrame</code></a>,
<a href="applet.html"><code>JApplet</code></a>,
<a href="dialog.html"><code>JDialog</code></a>, or
<a href="internalframe.html"><code>JInternalFrame</code></a> &#151;
automatically has a layered pane.
Most programs don't explicitly
use the root pane's layered pane,
so we don't discuss it in this section.
You can find information about it in
<a href="toplevel.html#rootpane">The Root Pane</a>,
which provides an overview, and
<a href="rootpane.html#layeredpane">The Layered Pane</a>,
which has further details.
This section concentrates on
telling you how to create your own layered pane
and use it anywhere you might use a regular Swing container.
<p>
Swing provides two layered pane classes.
The first, 
<a class="APILink" target="_blank" href="http://java.sun.com/javase/6/docs/api/javax/swing/JLayeredPane.html"><code>JLayeredPane</code></a>, is the class that root panes use
and is the class used by the
example in this section.
The second,
<code>JDesktopPane</code>,
is a <code>JLayeredPane</code> subclass
that's specialized for the task of holding internal frames.
For examples of using <code>JDesktopPane</code>,
see <a href="internalframe.html">How to Use Internal Frames</a>.

<p>
Here's a picture of an application that
creates a layered pane and places overlapping, colored
<a href="label.html">labels</a> at different depths:

<p><center><IMG SRC="../../figures/uiswing/components/LayeredPaneDemoMetal.png" WIDTH="308" HEIGHT="425" ALIGN="BOTTOM" ALT="A snapshot of LayeredPaneDemo"></center></p>

<blockquote><hr><strong>Try this:</strong>&nbsp;
<ol>
<li> <a href="http://java.sun.com/docs/books/tutorialJWS/uiswing/components/examples/LayeredPaneDemo.jnlp">Run LayeredPaneDemo</a> (it requires release 6) using
<a class="TutorialLink" target="_top" href="../../information/javawebstart.html">Java<sup><font size=-2>TM</font></sup> Web Start</a>.    Or, to compile and run the example yourself,
     consult the
     <a href="examples/index.html#LayeredPaneDemo">example index</a>.

<li> Move the mouse around in the lower part of the window.
     The image of Duke drags behind
     the green and red labels,
     but in front of the other three labels.
<li> Use the combo box at the top of the window to change Duke's depth.
     Use the check box to set
     whether Duke is in the top position &#151; position 0 &#151; within
     the current depth.
</ol>
<hr></blockquote>

Here's the code from 
<a class="SourceLink" target="_blank" href="examples/LayeredPaneDemo.java"><code>LayeredPaneDemo.java</code></a> that creates the layered pane:
<blockquote><pre>
layeredPane = new JLayeredPane();
layeredPane.setPreferredSize(new Dimension(300, 310));
layeredPane.setBorder(BorderFactory.createTitledBorder(
                                    "Move the Mouse to Move Duke"));
layeredPane.addMouseMotionListener(new MouseMotionAdapter() {
    ...
});
</pre></blockquote>
The code uses <code>JLayeredPane</code>'s only constructor &#151; the
no-argument constructor &#151; to create the layered pane.
The rest of the code
uses methods inherited from superclasses
to give the layered pane a preferred size and a border,
and add a mouse-motion listener to it.
The mouse-motion listener
just moves the Duke image around in response to mouse movement.
Although we don't show the code here,
the example adds the layered pane to the frame's content pane.

<p>
As we'll show you a bit later,
you add components to a layered pane using
an <code>add</code> method.
When adding a component to a layered pane,
you specify the component's depth,
and optionally, its position within its depth.
The layered pane in the demo program contains
six labels &#151; the five colored labels
and a sixth one that displays the Duke image.
As the program demonstrates,
both the depth of a component
and its position with that depth
can change dynamically.

<p>

The rest of this section covers these topics:
<ul>
<li> <a href="#depth">Adding Components and Setting Component Depth</a>
<li> <a href="#position">Setting a Component's Position Within Its Depth</a>
<li> <a href="#layout">Laying Out Components in a Layered Pane</a>
<li> <a href="#api">The Layered Pane API</a>
<li> <a href="#eg">Examples that Use Layered Panes</a>
</ul>

<a name="depth">
</blockquote>
<h3>Adding Components and Setting Component Depth</h3>
</a>
<blockquote>
Here's the code from the sample program that
adds the colored labels to the layered pane:
<blockquote><pre>
for (int i = 0; i < <em>...number of labels...</em>; i++) {
    JLabel label = createColoredLabel(<em>...</em>);
    <strong>layeredPane.add(label, new Integer(i));</strong>
    ...
}
</pre></blockquote>
You can find the implementation of
the <code>createColoredLabel</code> method
in the source code for the program.
It just creates an opaque <code>JLabel</code>
initialized with a background color,
a border, some text, and a size.
<p>
The example program uses a two-argument version
of the <code>add</code> method.
The first argument is the component to add,
the second is an <code>Integer</code> object,
specifying the depth.
This program uses the <code>for</code> loop's
iteration variable to specify depths.
The actual values don't matter much.
What matters is the relative value of the depths
and that you are consistent within your program
in how you use each depth.


<blockquote><hr><strong>Note:</strong>&nbsp;
If you use the root pane's layered pane,
be sure to use its depth conventions.
Refer to
<a href="rootpane.html#layeredpane">The Layered Pane</a>
for details.
That section shows you how to modify
<code>LayeredPaneDemo</code> to use
the root pane's layered pane.
With the modifications,
you can see how the dragging Duke image
relates to the combo box in the control panel.
<hr></blockquote>

<p>
As you can see from the example program,
if components overlap,
components at a higher depth
are on top of components at a lower depth.
To change a component's depth dynamically,
use the <code>setLayer</code> method.
In the example,
the user can change Duke's layer
by making a selection from the combo box.
Here's the <code>actionPerformed</code> method
of the action listener registered on the combo box:
<blockquote><pre>
public void actionPerformed(ActionEvent e) {
    int position = onTop.isSelected() ? 0 : 1;
    layeredPane.setLayer(dukeLabel,
                         layerList.getSelectedIndex(),
                         position);
}
</pre></blockquote>
The <code>setLayer</code> method used here
takes three arguments:
the component whose depth is to be set,
the new depth, and the position within the depth.
<code>JLayeredPane</code> has a two-argument version
of <code>setLayer</code>
that takes only the component and the new depth.
That method puts the component at the bottom position in its depth.


<blockquote><hr><strong>A note of caution:</strong>&nbsp;
When adding a component to a layered pane you specify
the layer with an <code>Integer</code>.
When using <code>setLayer</code> to change a component's
layer, you use an <code>int</code>.
You might think that
if you use an <code>int</code>
instead of an <code>Integer</code> with the <code>add</code>
method, the compiler would complain
or your program would throw an illegal argument exception.
But the compiler says nothing, which results in a
<a href="problems.html#layeredpane">common layered pane problem</a>.
You can use the API tables at the end of this section
to check the types of the arguments and return values
for methods that deal with layers.
<hr></blockquote>
</blockquote>

<a name="position">
<h3>Setting a Component's Position Within Its Depth</h3>
</a>
<blockquote>
The following code creates the label that displays Duke's image,
and then adds the label to the layered pane.
<blockquote><pre>
final ImageIcon icon = createImageIcon("images/dukeWaveRed.gif");
...
dukeLabel = new JLabel(icon);
...
dukeLabel.setBounds(15, 225,
                    icon.getIconWidth(),
                    icon.getIconHeight());
...
layeredPane.add(dukeLabel, new Integer(2), 0);
</pre></blockquote>
This code uses the three-argument version of the
<code>add</code> method.
The third argument specifies the Duke label's
position within its depth,
which determines the component's relationship with
other components at the same depth.
<p>
Positions are specified with an <code>int</code>
between -1 and (<em>n</em> - 1),
where <em>n</em> is the number of components at the depth.
Unlike layer numbers,
the smaller the position number,
the higher the component within its depth.
Using -1 is the same as using <em>n</em> - 1;
it indicates the bottom-most position.
Using 0 specifies that the component should be
in the top-most position within its depth.
As the following figure shows, 
with the exception of -1, 
a lower position number indicates a higher position within a depth.

<p><center><IMG SRC="../../figures/uiswing/components/positions.gif" WIDTH="251" HEIGHT="91" ALIGN="BOTTOM" ALT="How positions affect layering"></center></p>
A component's position within its layer can change dynamically.
In the example, you can use the check box to
determine whether Duke label is in the top position at its depth.
Here's the <code>actionPerformed</code> method
for the action listener registered on the check box:
<blockquote><pre>
public void actionPerformed(ActionEvent e) {
    if (onTop.isSelected())
        layeredPane.moveToFront(dukeLabel);
    else
        layeredPane.moveToBack(dukeLabel);
}
</pre></blockquote>
When the user selects the check box,
the <code>moveToFront</code> method moves Duke to the front (position 0).
And when the user deselects check box,
Duke gets moved to the back with the <code>moveToBack</code> method.
You can also use the <code>setPosition</code> method or
the three-argument version of <code>setLayer</code>