splitpane.html

jsf、swing的官方指南

<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=spinner.html>&laquo;&nbsp;Previous</a>&nbsp;&bull;&nbsp;<a target=_top href=../TOC.html>Trail</a>&nbsp;&bull;&nbsp;<a target=_top href=tabbedpane.html>Next&nbsp;&raquo;</a>
            </div>
            <div id=PageTitle>How to Use Split Panes</div>
            <blockquote>
A 
<a class="APILink" target="_blank" href="http://java.sun.com/javase/6/docs/api/javax/swing/JSplitPane.html"><code>JSplitPane</code></a> displays two components,
either side by side or one on top of the other.
By dragging the divider that appears between the components,
the user can specify 
how much of the split pane's total area goes to each component.
You can divide screen space among three or more components
by putting split panes inside of split panes,
as described in <a href="#nesting">Nesting Split Panes</a>.

<p>

Instead of adding the components of interest 
directly to a split pane,
you often put each component into a 
<a href="scrollpane.html">scroll pane</a>.
You then put the scroll panes into the split pane.
This allows the user to view any part of a component of interest,
without requiring the component to take up a lot of screen space
or adapt to displaying itself in varying amounts of screen space.

<p>
Here's a picture of an application that
uses a split pane to display a list
and an image side by side:

<p><center><IMG SRC="../../figures/uiswing/components/SplitPaneDemo.png" WIDTH="408" HEIGHT="234" ALIGN="BOTTOM" ALT="A snapshot of SplitPaneDemo"></center></p>
<blockquote><hr><strong>Try this:</strong>&nbsp;
<ol>
<li> <a href="http://java.sun.com/docs/books/tutorialJWS/uiswing/components/examples/SplitPaneDemo.jnlp">Run SplitPaneDemo</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#SplitPaneDemo">example index</a>.

<li> Drag the dimpled line that divides the list
     and the image to the left or right.
     Try to drag the divider
     all the way to the window's edge.
<li> Click the tiny arrows on the divider
     to hide/expand the left or right component.
</ol>
<hr></blockquote>

Below is the code from <code>SplitPaneDemo</code>
that creates and sets up the split pane.
<blockquote><pre>
//Create a split pane with the two scroll panes in it.
<strong>splitPane = new JSplitPane(JSplitPane.HORIZONTAL_SPLIT,
                           listScrollPane, pictureScrollPane);</strong>
splitPane.setOneTouchExpandable(true);
splitPane.setDividerLocation(150);

//Provide minimum sizes for the two components in the split pane
Dimension minimumSize = new Dimension(100, 50);
listScrollPane.setMinimumSize(minimumSize);
pictureScrollPane.setMinimumSize(minimumSize);
</pre></blockquote>

The constructor used by this example
takes three arguments.
The first indicates the split direction.
The other arguments are the two components to put in the split pane.
Refer to
<a href="#adding">Setting the Components in a Split Pane</a>
for information about <code>JSplitPane</code>
methods that set the components dynamically.
<p>
The split pane in this example is split horizontally &#151; the
two components appear side by side &#151; as
specified by the <code>JSplitPane.HORIZONTAL_SPLIT</code>
argument to the constructor.
Split pane provides one other option,
specified with <code>JSplitPane.VERTICAL_SPLIT</code>,
that places one component above the other.
You can change the split direction
after the split pane has been created with
the <code>setOrientation</code> method.

<p>
Two small arrows appear at the top of the divider
in the example's split pane.
These arrows let the user collapse (and then expand)
either of the components with a single click.
The current look and feel determines
whether these controls appear by default.
In the Java look and feel,
they are turned off by default.
The example turned them on
using the <code>setOneTouchExpandable</code> method.

<p>
The range of a split pane's divider
is determined in part by 
the minimum sizes of the components within the split pane.
See <a href="#divider">Positioning the Divider and Restricting its Range</a>
for details.
<p>
The rest of this section covers these topics:
<ul>
<li> <a href="#adding">Setting the Components in a Split Pane</a>
<li> <a href="#divider">Positioning the Divider and Restricting its Range</a>
<li> <a href="#nesting">Nesting Split Panes</a>
<li> <a href="#api">The Split Pane API</a>
<li> <a href="#eg">Examples that Use Split Panes</a>
</ul>

<a name="adding">
</blockquote>
<h3>Setting the Components in a Split Pane</h3>
</a>
<blockquote>
A program can set a split pane's two components
dynamically with these four methods:
<ul>
<li><code>setLeftComponent</code>
<li><code>setRightComponent</code>
<li><code>setTopComponent</code>
<li><code>setBottomComponent</code>
</ul>
You can use any of these methods at any time
regardless of the split pane's current split direction.
Calls to <code>setLeftComponent</code> and
<code>setTopComponent</code> are equivalent and
set the specified component in the top or left position,
depending on the split pane's current split orientation.
Similarly, calls to <code>setRightComponent</code> and
<code>setBottomComponent</code> are equivalent.
These methods replace whatever component is already
in that position with the new one.
<p>
Like other containers,
<code>JSplitPane</code> supports the <code>add</code> method.
Split pane puts the first component added
in the left or top position.
The danger of using <code>add</code> is that
you can inadvertantly call it too many times,
in which case the split pane's layout manager
will throw a rather esoteric-looking exception.
If you are using the <code>add</code> method
and a split pane is already populated,
you first need to remove the existing components
with <code>remove</code>.
<p>
If you put only one component in a split pane,
then the divider will be stuck at the right side or
the bottom of the split pane,
depending on its split direction.
</blockquote>

<a name="divider">
<h3>Positioning the Divider and Restricting Its Range</h3>
</a>
<blockquote>
To make your split pane work well,
you often need to set 
the minimum sizes of components in the split pane,
as well as the preferred size of either the split pane
or its contained components.
Choosing which sizes you should set
is an art that requires 
understanding how a split pane's preferred size and divider location
are determined.
Before we get into details, let's take another look at
SplitPaneDemo.
Or, if you're in a hurry, 
you can skip to the <a href="#rules">list of rules</a>.

<blockquote><hr><strong>Try this:</strong>&nbsp;
<ol>
<li> <a href="http://java.sun.com/docs/books/tutorialJWS/uiswing/components/examples/SplitPaneDemo.jnlp">Run SplitPaneDemo</a> (it requires release 6) using
<a class="TutorialLink" target="_top" href="../../information/javawebstart.html">Java Web Start</a>.    Or, to compile and run the example yourself,
     consult the
     <a href="examples/index.html#SplitPaneDemo">example index</a>.
<br>
Because the size of the demo's frame 
is set using the <code>pack</code> method,
the split pane is at its preferred size,
which SplitPaneDemo happens to set explicitly.
The divider is automatically placed
so that the left component
is at its preferred width
and all remaining space goes to the right component.

<li> 
Make the window wider.
<br>
The divider stays where it is,
and the extra space goes to the component at the right.

<li>
Make the window noticeably narrower than when it first came up &#151;
perhaps twice as wide as the left component.
<br>
Again, the left component's size and the divider position stay the same.
Only the size of the right component changes.

<li>
Make the window as narrow as possible.
<br>
Assuming the window uses the Java look and feel-provided decorations,
you can't size the window smaller
than the split pane's minimum size,
which is determined by the minimum size of the components
contained by the split pane.
SplitPaneDemo sets the minimum size of these contained components explicitly.

<li>
Make the window wider, and then drag the divider 
as far as it will go to the right.
<br>
The divider goes only as far as the right component's
minimum size allows.
If you drag the divider to the left,
you'll see that it also respects the left component's minimum size.
</ol>
<hr></blockquote>

<p>
Now that you've seen the default behavior of split panes,
we can tell you what's happening behind the scenes
and how you can affect it.
In this discussion,
when we refer to a component's preferred or minimum size,
we often mean the preferred or minimum width of the component
if the split pane is horizontal,
or its preferred or minimum height if the split pane is vertical.

<p>
By default,
a split pane's preferred size and divider location
are initialized so that
the two components in the split pane are at their preferred sizes.
If the split pane isn't displayed at this preferred size
and the program hasn't set the divider's location explicitly,
then the initial position of the divider
(and thus the sizes of the two components)
depends on a
split pane property called the <em>resize weight</em>.
If the split pane is initially at its preferred size or bigger,
then the contained components start out at their preferred sizes,
before adjusting for the resize weight.
If the split pane is initially too small to display
both components at their preferred sizes,
then they start out at their <em>minimum</em> sizes,
before adjusting for the resize weight.

<p>
A split pane's resize weight
has a value between 0.0 and 1.0
and determines
how space is distributed between the two contained components
when the split pane's size is set &#151;
whether programmatically
or by the user resizing the split pane
(enlarging its containing window, for example).
The resize weight of a split pane is 0.0 by default,
indicating that the left or top component's size is fixed,
and the right or bottom component 
adjusts its size to fit the remaining space.
Setting the resize weight to 0.5 
splits any extra or missing space evenly between the two components.
Setting the resize weight to 1.0 
makes the right or bottom component's
size remain fixed.
The resize weight has no effect,
however, 
when the user drags the divider.

<p>
The user can drag the divider
to any position
<em>as long as</em>
neither contained component goes below its minimum size.
If the divider has one-touch buttons,
the user can use them
to make the divider move completely to one side or the other &#151;
no matter what the minimum sizes of the components are.
</p>

<a name="rules">
<p>
Now that you know the factors
that affect a split pane's size and divider location,
here are some rules for making them work well:
</a>

<ul>
<li> To ensure that the divider can be dragged
     when the split pane is at its preferred size,
     make sure the minimum size of one or both contained components
     is smaller than the contained component's preferred size.
     You can set the minimum size of a component either by 
     invoking <code>setMinimumSize</code> on it 
     or by overriding its <code>getMinimumSize</code> method.
     For example, if you want the user
     to be able to drag the divider all the way to both sides:

<blockquote><pre>
Dimension minimumSize = new Dimension(0, 0);
leftComponent.setMinimumSize(minimumSize);
rightComponent.setMinimumSize(minimumSize);
</pre></blockquote>

<li> To guarantee that both contained components appear,
     make sure that either the split pane 
     is initially at or above its preferred size,
     or the minimum sizes of the contained components
     are greater than zero.

<p>