splitpane.html

jsf、swing的官方指南

<li> If you want the bottom or right component to stay the same size
     and the top or left component to be flexible when the split pane
     gets bigger,
     set the resize weight to 1.0.
     You can do this by invoking <code>setResizeWeight</code>:

<blockquote><pre>
splitPane.setResizeWeight(1.0);
</pre></blockquote>

<p>
<li> If you want both halves of the split pane to share
     in the split pane's extra or removed space,
     set the resize weight to 0.5:

<blockquote><pre>
splitPane.setResizeWeight(0.5);
</pre></blockquote>

<p>
<li> Make sure each component contained by a split pane has a reasonable
     preferred size. 
     If the component is a panel that uses a layout manager, 
     you can generally just use the value it returns.
     If the component is a scroll pane,
     you have a few choices.
     You can invoke the <code>setPreferredSize</code>
     method on the scroll pane,
     invoke the appropriate method on the component in the scroll pane
     (such as the <code>setVisibleRowCount</code> method
     for <code>JList</code> or <code>JTree</code>),
     or just set the split pane's preferred size
     and the divider's location.

<p>
<li> Make sure each component contained by a split pane
     can display itself reasonably in varying amounts of space.
     For example, panels that contain multiple components
     should use layout managers 
     that use extra space in a reasonable way.

<p>
<li> If you want
     to set the size of contained components to something other than their
     preferred sizes,
     use the <code>setDividerLocation</code> method.
     For example, to make the left component
     150 pixels wide:

<blockquote><pre>
splitPane.setDividerLocation(150 + splitPane.getInsets().left);
</pre></blockquote>

     To make the right component 150 pixels wide:

<blockquote><pre>
splitPane.setDividerLocation(splitPane.getSize().width
                             - splitPane.getInsets().right
                             - splitPane.getDividerSize()
                             - 150);
</pre></blockquote>

    If the split pane is already visible,
    you can set the divider location as a percentage
    of the split pane.  
    For example, to make 25% of the space go to left/top:

<blockquote><pre>
splitPane.setDividerLocation(0.25);
</pre></blockquote>

<li>
<p>
To lay out the split pane
as if it just came up, 
likely repositioning the divider in the process,
invoke <code>resetToPreferredSizes()</code> 
on the split pane.

<blockquote><hr><strong>Note:</strong>&nbsp;Just changing the contained components' preferred sizes &#151;
even if you invoke <code>revalidate</code> afterwards &#151;
is not enough to cause the split pane to lay itself out again.
You must invoke <code>resetToPreferredSizes</code> as well.
<hr></blockquote>
</ul>
 
The following snapshot shows an example
named SplitPaneDividerDemo
that demonstrates 
split pane component sizes and divider placement.

<p>
<p><center><IMG SRC="../../figures/uiswing/components/SplitPaneDividerDemo.png" WIDTH="270" HEIGHT="197" ALIGN="BOTTOM" ALT="A snapshot of SplitPaneDividerDemo"></center></p>
<p>
Like SplitPaneDemo,
SplitPaneDividerDemo
features a horizontal split pane
with one-touch buttons.
SplitPaneDividerDemo has the following additional features:

<ul>
<li> The split pane's <em>resize weight</em>
     is explicitly set (to 0.5).
<li> The split pane 
     is displayed at its default preferred size.
<li> A Reset button at the bottom of the window
     invokes 
     <code>resetToPreferredSizes</code> on the split pane.
<li> The components in the split pane
     are instances of a custom <code>JComponent</code> subclass
     called <code>SizeDisplayer</code>.
     A <code>SizeDisplayer</code>
     displays optional text 
     against the background of a faded (and also optional) image.
     More importantly, 
     it has rectangles that show its preferred and minimum sizes.
<li> SplitPaneDividerDemo sets up its
     <code>SizeDisplayer</code>s 
     to have equal preferred sizes
     (due to the equally large images they show)
     but unequal minimum sizes.
</ul>

<blockquote><hr><strong>Try this:</strong>&nbsp;
<ol>
<li> <a href="http://java.sun.com/docs/books/tutorialJWS/uiswing/components/examples/SplitPaneDividerDemo.jnlp">Run SplitPaneDividerDemo</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#SplitPaneDividerDemo">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 by default
is just big enough for the <code>SizeDisplayer</code>s
to be at their preferred sizes.
The preferred size of each <code>SizeDisplayer</code> 
is indicated by a red rectangle.
The divider is automatically placed so that both components
are at their preferred widths.

<p>
<strong>Note:</strong>
If you're running the example in Java Web Start,
the <code>SizeDisplayer</code> components
might be taller than their preferred sizes.
This is due to bug #
<a class="OutsideLink" target="_blank" href="http://developer.java.sun.com/developer/bugParade/bugs/4777616.html">4777616</a>:
windows decorated by the Java look and feel
don't account for the window warning string.

<li> 
Make the window wider.
<br>
Because the split pane's resize weight is 0.5,
the extra space is divided evenly between the left and right components.
The divider moves accordingly.

<li>
Make the window as narrow as possible.
<br>
Assuming the window uses the Java look and feel-provided decorations,
it will not let you size the window smaller
than the split pane's minimum size,
which is determined by the minimum size of the <code>SizeDisplayers</code>
it contains.
The minimum size of each <code>SizeDisplayer</code> 
is indicated by a bright blue rectangle.

<li>
Make the window a bit 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.

<li>
After making sure the split pane 
is smaller than its preferred size,
click the Reset button.
<br>
Note that the two <code>SizeDisplayer</code>s
are displayed at the different sizes, 
even though when the application
came up they had equal sizes.
The reason is that 
although their preferred sizes are equal,
their minimum sizes are not.
Because the split pane can't
display them at their preferred sizes or larger,
it lays them out using their minimum sizes.
The leftover space
is divided equally between the components,
since the split pane's resize weight is 0.5.

<li>
Widen the split pane 
so that it's large enough 
for both <code>SizeDisplayer</code>s
to be shown at their preferred sizes,
and then
click the Reset button.
<br>
The divider is placed in the middle again,
so that both components are the same size.
</ol>
<hr></blockquote>

Here is the code that creates the GUI
for SplitPaneDividerDemo:

<blockquote><pre>
public class SplitPaneDividerDemo extends JPanel ... {

    private JSplitPane splitPane;
   
    public SplitPaneDividerDemo() {
        super(new BorderLayout());

        Font font = new Font("Serif", Font.ITALIC, 24);

        ImageIcon icon = createImageIcon("images/Cat.gif");
        SizeDisplayer sd1 = new SizeDisplayer("left", icon);
        sd1.setMinimumSize(new Dimension(30,30));
        sd1.setFont(font);
        
        icon = createImageIcon("images/Dog.gif");
        SizeDisplayer sd2 = new SizeDisplayer("right", icon);
        sd2.setMinimumSize(new Dimension(60,60));
        sd2.setFont(font);
        
        splitPane = new JSplitPane(JSplitPane.HORIZONTAL_SPLIT,
                                   sd1, sd2);
        splitPane.setResizeWeight(0.5);
        splitPane.setOneTouchExpandable(true);
        splitPane.setContinuousLayout(true);

        add(splitPane, BorderLayout.CENTER);
        add(createControlPanel(), BorderLayout.PAGE_END);
    }
    ...
}
</pre></blockquote>

The code is fairly self explanatory,
except perhaps for the call to <code>setContinuousLayout</code>.
Setting the <em>continuousLayout</em> property to true
makes the split pane's contents be painted continuously
while the user is moving the divider.
Continuous layout is not on, by default,
because it can have a negative performance impact.
However, it makes sense to use it in this demo,
when having the split pane's components as up-to-date
as possible can improve the user experience.


</blockquote>
<a name="nesting">
<h3>Nesting Split Panes</h3>
</a>
<blockquote>
Here's a picture of a program that achieves a three-way
split by nesting one split pane inside of another:

<p><center><IMG SRC="../../figures/uiswing/components/SplitPaneDemo2.png" WIDTH="410" HEIGHT="270" ALIGN="BOTTOM" ALT="A snapshot of SplitPaneDemo2"></center></p>
If the top portion of the split pane looks familiar
to you, it's because the program puts the split pane created by
<code>SplitPaneDemo</code> inside a second split pane.
A simple <code>JLabel</code> is the other component
in the second split pane.
This is not the most practical use of a 
nested split pane, but it gets the point across.

<p>

You can <b><a href="http://java.sun.com/docs/books/tutorialJWS/uiswing/components/examples/SplitPaneDemo2.jnlp">run SplitPaneDemo2</a></b> (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#SplitPaneDemo2">example index</a>.
Here's the interesting part of the code, which you can find in

<a class="SourceLink" target="_blank" href="examples/SplitPaneDemo2.java"><code>SplitPaneDemo2.java</code></a>:

<blockquote><pre>
//Create an instance of SplitPaneDemo
SplitPaneDemo splitPaneDemo = new SplitPaneDemo();
JSplitPane top = splitPaneDemo.getSplitPane();

...
//Create a regular old label
label = new JLabel("Click on an image name in the list.",
		   JLabel.CENTER);

//Create a split pane and put "top" (a split pane)
//and JLabel instance in it.
JSplitPane splitPane = new JSplitPane(JSplitPane.VERTICAL_SPLIT,
				      top, label);
</pre></blockquote>
Refer to
<a href="problems.html#nestedborders">
Solving Common Component Problems</a>
for information about fixing a border problem
that can appear when nesting split panes.
</blockquote>

<h3>
<a name="api">The Split Pane API</a>
</h3>
<blockquote>
The following tables list the commonly used
<code>JSplitPane</code> constructors and methods.
Other methods you are most likely to invoke on
a <code>JSplitPane</code> object are those
such as <code>setPreferredSize</code>
that its superclasses provide.
See
<a href="jcomponent.html#api">The JComponent API</a>
for tables of commonly used inherited methods.

<p>
The API for using lists falls into these categories:

<ul>
<li><a href="#settingupapi">Setting up the Split Pane</a>
<li><a href="#contentsapi">Managing the Split Pane's Contents</a>
<li><a href="#dividerapi">Positioning the Divider</a>
</ul>