Using Swing Components

How to Use Split Panes

A JSplitPane contains two components (and only two), separated by a divider. By dragging the divider, the user can specify how much area goes to each component. Use a split pane when two components contain related information and you want the user to be able to change the components' sizes in relation to one another. One common use of a split pane is to contain a list of choices and a view of the current choice. An example of this is a mailer program that displays a list of mail messages and the contents of the currently selected message.

If you want to put more than two components in a split pane, then consider using nested split panes. That is, put one split pane inside another. SplitPaneDemo2 is an example of this.

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

---

Try this:

1. Compile and run the application. The main source file is SplitPaneDemo.java. imagenames.properties provides the image names to put in the JList. You can download the entire swing lesson to get the image files listed, or you can modify the properties file to list images you already have.
   See Getting Started with Swing if you need help.
2. 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.
3. Use the arrows on the divider to hide the left or right component.
4. Check out SplitPaneDemo2.java. It puts an instance of SplitPaneDemo within another split pane to split the area of a frame three ways.

---

The main class in the split pane demo program is called SplitPaneDemo. Below is the code from SplitPaneDemo's constructor that creates and sets up the split pane:

public SplitPaneDemo() {

    //Create the list of images and put it in a scroll pane.
    ...
    //Set up the picture label and put it in a scroll pane.
    ...
    //Create a split pane with the two scroll panes in it.
    splitPane = new JSplitPane(JSplitPane.HORIZONTAL_SPLIT);
    splitPane.setLeftComponent(listScrollPane);
    splitPane.setRightComponent(pictureScrollPane);
    splitPane.setOneTouchExpandable(true);
 
    //Provide minimum sizes for the two components in the split pane
    Dimension minimumSize = new Dimension(100, 50);
    listScrollPane.setMinimumSize(minimumSize);
    pictureScrollPane.setMinimumSize(minimumSize);
 
    //Set the initial location and size of the divider
    splitPane.setDividerLocation(150);
    splitPane.setDividerSize(10);
 
    //Provide a preferred size for the split pane
    splitPane.setPreferredSize(new Dimension(400, 200));
}

The bold line creates a split pane that is divided horizontally, thereby putting the two components side by side. Split pane provides one other option, VERTICAL_SPLIT, that places the two components one above the other. You can change the split direction after the split pane has been created with the setOrientation method.

The constructor uses setLeftComponent and setRightComponent to place the list and the image label in the split pane. If the split pane was oriented vertically, you might choose to use setTopComponent and setBottomComponent instead. However, each of the setXxxxComponent methods works regardless of the split pane's orientation. Top and left are equivalent, and bottom and right are equivalent. Alternatively, you can use the add method, which puts the first component in the left or top position.

Next the code sets "one touch expandable" to true. With this option turned on, the split pane displays controls that allow the user to hide one of the components and allocate all of the split pane's space to the other.

You might have noticed that the preceding code makes a fuss about the minimum sizes of the two components contained by the split pane. The reason is that a split pane uses its components' minimum sizes to determine where the user can position the divider. A split pane does not allow the user to make either of the components smaller than the component's minimum size by dragging the divider. The user can use the one touch expandable buttons to hide one component. If this example did not explicitly set the minimum size for at least one of split pane's components, the divider would be immovable because each component in the split pane would already be smaller than its minimum size.

The Split Pane API

The following tables list the commonly used JSplitPane constructors and methods. Other methods you're likely to call are defined by the JComponent, Container, and Component classes and include [PENDING: anything in particular for JSplitPane?]. [Link to JComponent and Component discussions.] The API for using lists falls into these categories:

• Setting up the Split Pane
• Managing the Split Pane's Contents
• Positioning the Divider

Setting Up the Split Pane

Method	Purpose
JSplitPane() JSplitPane(int) JSplitPane(int, boolean) JSplitPane(int, Component, Component) JSplitPane(int, boolean, Component, Component)	Create a split pane. When present, the int parameter indicates the split pane's orientation, either HORIZONTAL_SPLIT or VERTICAL_SPLIT. The boolean parameter sets whether the components continually repaint as the user drags the split pane. The Component parameters set the initial left and right, or top and bottom components, respectively.
void setOrientation(int) int getOrientation()	Set or get the split pane's orientation. Use either HORIZONTAL_SPLIT or VERTICAL_SPLIT defined in JSplitPane.
void setDividerSize(int) int getDividerSize()	Set or get the size of the divider in pixels.
void setContinuousLayout(boolean) boolean getContinuousLayout()	Set or get whether the split pane's components are continually layed out and painted while the user is dragging the divider.
void setOneTouchExpandable(boolean) boolean getOneTouchExpandable()	Set or get whether the split pane displays the one touch expandable controls.

Managing the Split Pane's Contents

Method	Purpose
void setTopComponent(Component) void setBottomComponent(Component) void setLeftComponent(Component) void setRightComponent(Component) Component getTopComponent() Component getBottomComponent() Component getLeftComponent() Component getRightComponent()	Set or get the indicated component. Each method works regardless of the split pane's orientation. Top and left are equivalent, and bottom and right are equivalent.
void remove(Component) void removeAll()	Remove the indicated component from the split pane.
void add(Component)	Add the component to the split pane. You can add only two components to a split pane. The first component added is the top/left component. The second component added is the bottom/right component.

Positioning the Divider

Method	Purpose
void setDividerLocation(double) void setDividerLocation(int) int getDividerLocation()	Set or get the current divider location. When setting the divider location, you can specify the new location as a percentage (double) or a pixel location (int).
void setLastDividerLocation(int) int getLastDividerLocation()	Set or get the previous position of the divider.
int getMaximumDividerLocation() int getMinimumDividerLocation()	Get the minimum and maximum locations for the divider. These are set implicitly by setting the minimum sizes of the split pane's two components.

Examples that Use Split Panes

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

Example	Where Described	Notes
SplitPaneDemo.java	This page and How to Use Lists.	Shows a split pane with a horizontal split.
TreeDemo.java	How to Use Trees	Uses a split pane with a vertical split and with one touch expandable turned off.
SplitPaneDemo2.java	This page	Puts a split pane within a split pane to create a three-way split.

Using Swing Components