11.1 The JSplitPane Class

The JSplitPane component allows you to place two (and only two) components side by side in a single pane. You can separate the pane horizontally or vertically, and the user can adjust this separator graphically at runtime. You have probably seen such a split pane approach in things like a file chooser or a news reader. The top or left side holds the list of directories or news subject lines while the bottom (or right side) contains the files or body of the currently selected directory or article. To get started, Figure 11-2 shows a simple split pane example that shows two text areas with a horizontal split. You can adjust the width of the split by grabbing the divider and sliding it left or right.

Figure 11-2. Simple JSplitPane with two text areas

Even with the code required to make the text areas behave (more on that in Chapter 19), the following example is still fairly simple. If you are looking to get up and running with a quick split pane, this is the way to go.

// SimpleSplitPane.java
// A quick test of the JSplitPane class
//
import java.awt.*;
import java.awt.event.*;
import javax.swing.*;

public class SimpleSplitPane extends JFrame {

  static String sometext = "This is a simple text string that is long enough " +
    "to wrap over a few lines in the simple demo we're about to build.  We'll " +
    "put two text areas side by side in a split pane.";

  public SimpleSplitPane( ) {
    super("Simple SplitPane Frame");
    setSize(450, 200);
    setDefaultCloseOperation(EXIT_ON_CLOSE);

    JTextArea jt1 = new JTextArea(sometext);
    JTextArea jt2 = new JTextArea(sometext);

    // Make sure our text boxes do line wrapping and have reasonable minimum sizes.
    jt1.setLineWrap(true);
    jt2.setLineWrap(true);
    jt1.setMinimumSize(new Dimension(150, 150));
    jt2.setMinimumSize(new Dimension(150, 150));
    jt1.setPreferredSize(new Dimension(250, 200));
    JSplitPane sp = new JSplitPane(JSplitPane.HORIZONTAL_SPLIT, jt1, jt2);
    getContentPane( ).add(sp, BorderLayout.CENTER);
  }

  public static void main(String args[]) {
    SimpleSplitPane ssb = new SimpleSplitPane( );
    ssb.setVisible(true);
  }
}

11.1.1 Properties

Table 11-1 shows the properties contained in the JSplitPane class.

Table 11-1. JSplitPane properties

Property	Data type	get	is	set	Default value
accessibleContexto	AccessibleContext	·			JSplitPane.AccessibleJSplitPane( )
bottomComponent	Component	·		·	null
continuousLayoutb	boolean		·	·	false
dividerLocationb,*	int	·		·	-1
dividerSizeb	int	·		·	5
lastDividerLocation	int	·		·	0
leftComponent	Component	·		·	null
maximumDividerLocation*	int	·			-1
minimumDividerLocation*	int	·			-1
oneTouchExpandableb	boolean		·	·	false
orientationb	int	·		·	HORIZONTAL_SPLIT
resizeWeightb, 1.3	double	·		·	0.0
rightComponent	Component	·		·	null
topComponent	Component	·		·	null
UIb	SplitPaneUI	·			From L&F
UIClassIDo	String	·			"SplitPaneUI"
1.3since 1.3, bbound, ooverridden *These properties return -1 only if no UI is defined for this component. Normally, the UI is queried for its current value. See also properties from the JComponent class (Table 3-6).

The properties of JSplitPane primarily relate to the divider. You can get and set its size, location, and orientation, and its minimum and maximum bounds. Of particular interest is the oneTouchExpandable property. If this value is set to true, the UI should provide a component that can quickly collapse or expand the divider. For your programming convenience, four component properties are available. Note that the component properties bottomComponent and rightComponent refer to the same object, as do topComponent and leftComponent. This way, you can refer to your components in a fashion that's consistent with the orientation of your split pane. The resizeWeight property affects how new space is allocated if the split pane itself is resized. The default of 0.0 distributes all of the size change to the bottom-right component; 1.0 goes entirely to the top-left component. If the continuousLayout property is true, both sides of the pane are updated as often as possible while the user moves the divider. Otherwise, the components are resized and redrawn only after the divider location is set. Continuous layout can be a performance problem and is often just awkward. The lastDividerLocation property saves the previous location of the divider and can be used to undo a change in the divider's position.

11.1.2 Constants

Several constants are defined for use with the JSplitPane class (see Table 11-2). Some of these constants name the various properties in a split pane while others provide constraints for where to place a component or where to place the split.

Table 11-2. JSplitPane constants

Constant	Type	Description
BOTTOM	String	Add a component to the bottom of a vertically split pane.
CONTINUOUS_LAYOUT_PROPERTY	String	Used in property change events to specify that the continuousLayout property has been changed.
DIVIDER	String	Add a component as the divider for the pane.
DIVIDER_LOCATION_PROPERTY1.3	String	Used in property change events to specify that the dividerLocation property has changed.
DIVIDER_SIZE_PROPERTY	String	Used in property change events to specify that the dividerSize property has changed.
HORIZONTAL_SPLIT	int	One of the valid values for the orientation property of a JSplitPane object. This type of split creates a vertical divider, resulting in a set of left/right components.
LAST_DIVIDER_LOCATION_PROPERTY	String	Used in property change events to specify that the lastDividerLocation property has changed.
LEFT	String	Add a component to the left of a horizontally split pane.
ONE_TOUCH_EXPANDABLE_PROPERTY	String	Used in property change events to specify that the oneTouchExpandable property has changed.
ORIENTATION_PROPERTY	String	Used in property change events to specify that the orientation property has changed.
RESIZE_WEIGHT_PROPERTY1.3	String	Used in property change events to specify that the resizeWeight property has changed.
RIGHT	String	Add a component to the right of a horizontally split pane.
TOP	String	Add a component to the top of a vertically split pane.
VERTICAL_SPLIT	int	One of the valid values for the orientation property of a JSplitPane object. This type of split creates a horizontal divider, resulting in a set of top/bottom components.
1.3since 1.3

11.1.3 Constructors

public JSplitPane( )

This constructor is a "demo" constructor. It sets up a horizontal split with a left button and right button (both JButton components) already defined and added.

public JSplitPane(int orientation)

public JSplitPane(int orientation, boolean continuousLayout)

These constructors allow you to pick your initial split (horizontal or vertical) using the constants HORIZONTAL_SPLIT and VERTICAL_SPLIT. No components are added to either pane. If you give a true value as the continuousLayout argument to the second constructor, both panes are repainted continuously as the user moves the divider. (This property is false by default—you just see a line showing the proposed divider location while you move the divider.)

public JSplitPane(int orientation, Component leftOrTop, Component bottomOrRight)

public JSplitPane(int orientation, boolean continuousLayout, Component leftOrTop, Component bottomOrRight)

These constructors allow you to pick your orientation and the initial components for each pane. Depending on the orientation you choose, the first component is placed in the left or top pane, and the second component fills the other pane. If you give a true value as the continuousLayout argument to the second constructor, both panes are repainted continuously as the user moves the divider.

11.1.4 Control Methods

public void remove(Component comp)

public void remove(int index)

public void removeAll( )

Remove components from the split pane. Typically, you use the first of these methods to remove one component at a time.

public void resetToPreferredSizes( )

Reset the sizes of the components to their preferred sizes. The preferred size of a component is determined by the UI manager for the split pane. The preferred size of a split pane is the sum of the preferred sizes of its children (including the divider).

public void setDividerLocation(double position)

This convenience method does the pixel calculating for you so that you can specify a position for the divider. The position you give is the fraction of the whole pane given to the left of the pane (for a horizontal split) or the top of the pane (for a vertical split). For example, with a horizontal split, a value of 0.75 assigns 75% of the pane to the component on the left. The position must be a value between 0 and 1. If it isn't, you get an IllegalArgumentException.

11.1.5 Minimum and Preferred Sizes

When setting up your split panes, watch out for the minimum and preferred sizes of the two components. If you look back at the code for Figure 11-2, you can see we forcibly set the minimum sizes of the two text areas. The boundaries observed by the divider in a split pane are dictated by the minimum sizes of the two components. Some components, such as JTextArea, define their minimum size as the size they are initially shown with. That often works fine, but in the case of the split pane, it means that you cannot adjust the division between the two text areas (as both are already at their minimum sizes). The same is true for containers such as panels or the JScrollPane we discuss in the next section.

You should also set the preferred size of the first component if you want the split pane to come up correctly the first time. In the previous example, if you remove the line that sets the preferred size of jt1, then jt1 comes up with room for one row of text, and jt2 takes everything else. Of course, you could also set the dividerLocation property before making the split pane visible. (Note that if you are using an older version of the JDK—such as 1.2.2—you have to set the preferred size.)