FileDocCategorySizeDatePackage
JSplitPane.javaAPI DocJava SE 5 API40411Fri Aug 26 14:57:56 BST 2005javax.swing

JSplitPane

public class JSplitPane extends JComponent implements Accessible
JSplitPane is used to divide two (and only two) Components. The two Components are graphically divided based on the look and feel implementation, and the two Components can then be interactively resized by the user. Information on using JSplitPane is in How to Use Split Panes in The Java Tutorial.

The two Components in a split pane can be aligned left to right using JSplitPane.HORIZONTAL_SPLIT, or top to bottom using JSplitPane.VERTICAL_SPLIT. The preferred way to change the size of the Components is to invoke setDividerLocation where location is either the new x or y position, depending on the orientation of the JSplitPane.

To resize the Components to their preferred sizes invoke resetToPreferredSizes.

When the user is resizing the Components the minimum size of the Components is used to determine the maximum/minimum position the Components can be set to. If the minimum size of the two components is greater than the size of the split pane the divider will not allow you to resize it. To alter the minimum size of a JComponent, see {@link JComponent#setMinimumSize}.

When the user resizes the split pane the new space is distributed between the two components based on the resizeWeight property. A value of 0, the default, indicates the right/bottom component gets all the space, where as a value of 1 indicates the left/top component gets all the space.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see {@link java.beans.XMLEncoder}.

see
#setDividerLocation
see
#resetToPreferredSizes
version
1.76 12/19/03
author
Scott Violet

Fields Summary
private static final String
uiClassID
public static final int
VERTICAL_SPLIT
Vertical split indicates the Components are split along the y axis. For example the two Components will be split one on top of the other.
public static final int
HORIZONTAL_SPLIT
Horizontal split indicates the Components are split along the x axis. For example the two Components will be split one to the left of the other.
public static final String
LEFT
Used to add a Component to the left of the other Component.
public static final String
RIGHT
Used to add a Component to the right of the other Component.
public static final String
TOP
Used to add a Component above the other Component.
public static final String
BOTTOM
Used to add a Component below the other Component.
public static final String
DIVIDER
Used to add a Component that will represent the divider.
public static final String
ORIENTATION_PROPERTY
Bound property name for orientation (horizontal or vertical).
public static final String
CONTINUOUS_LAYOUT_PROPERTY
Bound property name for continuousLayout.
public static final String
DIVIDER_SIZE_PROPERTY
Bound property name for border.
public static final String
ONE_TOUCH_EXPANDABLE_PROPERTY
Bound property for oneTouchExpandable.
public static final String
LAST_DIVIDER_LOCATION_PROPERTY
Bound property for lastLocation.
public static final String
DIVIDER_LOCATION_PROPERTY
Bound property for the dividerLocation.
public static final String
RESIZE_WEIGHT_PROPERTY
Bound property for weight.
protected int
orientation
How the views are split.
protected boolean
continuousLayout
Whether or not the views are continuously redisplayed while resizing.
protected Component
leftComponent
The left or top component.
protected Component
rightComponent
The right or bottom component.
protected int
dividerSize
Size of the divider.
private boolean
dividerSizeSet
protected boolean
oneTouchExpandable
Is a little widget provided to quickly expand/collapse the split pane?
private boolean
oneTouchExpandableSet
protected int
lastDividerLocation
Previous location of the split pane.
private double
resizeWeight
How to distribute extra space.
private int
dividerLocation
Location of the divider, at least the value that was set, the UI may have a different value.
Constructors Summary
public JSplitPane()
Creates a new JSplitPane configured to arrange the child components side-by-side horizontally with no continuous layout, using two buttons for the components.



                                
      
        this(JSplitPane.HORIZONTAL_SPLIT, false,
            new JButton(UIManager.getString("SplitPane.leftButtonText")),
            new JButton(UIManager.getString("SplitPane.rightButtonText")));
    
public JSplitPane(int newOrientation)
Creates a new JSplitPane configured with the specified orientation and no continuous layout.

param
newOrientation JSplitPane.HORIZONTAL_SPLIT or JSplitPane.VERTICAL_SPLIT
exception
IllegalArgumentException if orientation is not one of HORIZONTAL_SPLIT or VERTICAL_SPLIT.

        this(newOrientation, false);
    
public JSplitPane(int newOrientation, boolean newContinuousLayout)
Creates a new JSplitPane with the specified orientation and redrawing style.

param
newOrientation JSplitPane.HORIZONTAL_SPLIT or JSplitPane.VERTICAL_SPLIT
param
newContinuousLayout a boolean, true for the components to redraw continuously as the divider changes position, false to wait until the divider position stops changing to redraw
exception
IllegalArgumentException if orientation is not one of HORIZONTAL_SPLIT or VERTICAL_SPLIT

        this(newOrientation, newContinuousLayout, null, null);
    
public JSplitPane(int newOrientation, Component newLeftComponent, Component newRightComponent)
Creates a new JSplitPane with the specified orientation and with the specified components that do not do continuous redrawing.

param
newOrientation JSplitPane.HORIZONTAL_SPLIT or JSplitPane.VERTICAL_SPLIT
param
newLeftComponent the Component that will appear on the left of a horizontally-split pane, or at the top of a vertically-split pane
param
newRightComponent the Component that will appear on the right of a horizontally-split pane, or at the bottom of a vertically-split pane
exception
IllegalArgumentException if orientation is not one of: HORIZONTAL_SPLIT or VERTICAL_SPLIT

        this(newOrientation, false, newLeftComponent, newRightComponent);
    
public JSplitPane(int newOrientation, boolean newContinuousLayout, Component newLeftComponent, Component newRightComponent)
Creates a new JSplitPane with the specified orientation and redrawing style, and with the specified components.

param
newOrientation JSplitPane.HORIZONTAL_SPLIT or JSplitPane.VERTICAL_SPLIT
param
newContinuousLayout a boolean, true for the components to redraw continuously as the divider changes position, false to wait until the divider position stops changing to redraw
param
newLeftComponent the Component that will appear on the left of a horizontally-split pane, or at the top of a vertically-split pane
param
newRightComponent the Component that will appear on the right of a horizontally-split pane, or at the bottom of a vertically-split pane
exception
IllegalArgumentException if orientation is not one of HORIZONTAL_SPLIT or VERTICAL_SPLIT

        super();

	dividerLocation = -1;
        setLayout(null);
	setUIProperty("opaque", Boolean.TRUE);
        orientation = newOrientation;
        if (orientation != HORIZONTAL_SPLIT && orientation != VERTICAL_SPLIT)
            throw new IllegalArgumentException("cannot create JSplitPane, " +
                                               "orientation must be one of " +
                                               "JSplitPane.HORIZONTAL_SPLIT " +
                                               "or JSplitPane.VERTICAL_SPLIT");
        continuousLayout = newContinuousLayout;
        if (newLeftComponent != null)
            setLeftComponent(newLeftComponent);
        if (newRightComponent != null)
            setRightComponent(newRightComponent);
        updateUI();

    
Methods Summary
protected voidaddImpl(java.awt.Component comp, java.lang.Object constraints, int index)
Adds the specified component to this split pane. If constraints identifies the left/top or right/bottom child component, and a component with that identifier was previously added, it will be removed and then comp will be added in its place. If constraints is not one of the known identifiers the layout manager may throw an IllegalArgumentException.

The possible constraints objects (Strings) are:

  • JSplitPane.TOP
  • JSplitPane.LEFT
  • JSplitPane.BOTTOM
  • JSplitPane.RIGHT
If the constraints object is null, the component is added in the first available position (left/top if open, else right/bottom).

param
comp the component to add
param
constraints an Object specifying the layout constraints (position) for this component
param
index an integer specifying the index in the container's list.
exception
IllegalArgumentException if the constraints object does not match an existing component
see
java.awt.Container#addImpl(Component, Object, int)

        Component             toRemove;

        if (constraints != null && !(constraints instanceof String)) {
            throw new IllegalArgumentException("cannot add to layout: " +
                                               "constraint must be a string " +
                                               "(or null)");
        }

        /* If the constraints are null and the left/right component is
           invalid, add it at the left/right component. */
        if (constraints == null) {
            if (getLeftComponent() == null) {
                constraints = JSplitPane.LEFT;
            } else if (getRightComponent() == null) {
                constraints = JSplitPane.RIGHT;
            }
        }
            
        /* Find the Component that already exists and remove it. */
        if (constraints != null && (constraints.equals(JSplitPane.LEFT) ||
                                   constraints.equals(JSplitPane.TOP))) {
            toRemove = getLeftComponent();
            if (toRemove != null) {
                remove(toRemove);
            }
            leftComponent = comp;
            index = -1;
        } else if (constraints != null &&
                   (constraints.equals(JSplitPane.RIGHT) ||
                    constraints.equals(JSplitPane.BOTTOM))) {
            toRemove = getRightComponent();
            if (toRemove != null) {
                remove(toRemove);
            }
            rightComponent = comp;
            index = -1;
        } else if (constraints != null &&
                constraints.equals(JSplitPane.DIVIDER)) {
            index = -1;
        }
        /* LayoutManager should raise for else condition here. */

        super.addImpl(comp, constraints, index);

        // Update the JSplitPane on the screen
        revalidate();
        repaint();
    
public javax.accessibility.AccessibleContextgetAccessibleContext()
Gets the AccessibleContext associated with this JSplitPane. For split panes, the AccessibleContext takes the form of an AccessibleJSplitPane. A new AccessibleJSplitPane instance is created if necessary.

return
an AccessibleJSplitPane that serves as the AccessibleContext of this JSplitPane
beaninfo
expert: true description: The AccessibleContext associated with this SplitPane.

        if (accessibleContext == null) {
            accessibleContext = new AccessibleJSplitPane();
        }
        return accessibleContext;
    
public java.awt.ComponentgetBottomComponent()
Returns the component below, or to the right of the divider.

return
the Component displayed in that position

        return rightComponent;
    
public intgetDividerLocation()
Returns the last value passed to setDividerLocation. The value returned from this method may differ from the actual divider location (if setDividerLocation was passed a value bigger than the curent size).

return
an integer specifying the location of the divider

	return dividerLocation;
    
public intgetDividerSize()
Returns the size of the divider.

return
an integer giving the size of the divider in pixels

        return dividerSize;
    
public intgetLastDividerLocation()
Returns the last location the divider was at.

return
an integer specifying the last divider location as a count of pixels from the left (or upper) edge of the pane to the left (or upper) edge of the divider

        return lastDividerLocation;
    
public java.awt.ComponentgetLeftComponent()
Returns the component to the left (or above) the divider.

return
the Component displayed in that position
beaninfo
preferred: true description: The component to the left (or above) the divider.

        return leftComponent;
    
public intgetMaximumDividerLocation()
Returns the maximum location of the divider from the look and feel implementation.

return
an integer specifying a UI-specific value for the maximum location (typically a pixel count); or -1 if the UI is null

        SplitPaneUI         ui = getUI();

        if (ui != null) {
            return ui.getMaximumDividerLocation(this);
        }
        return -1;
    
public intgetMinimumDividerLocation()
Returns the minimum location of the divider from the look and feel implementation.

return
an integer specifying a UI-specific value for the minimum location (typically a pixel count); or -1 if the UI is null
beaninfo
description: The minimum location of the divider from the L&F.

        SplitPaneUI         ui = getUI();

        if (ui != null) {
            return ui.getMinimumDividerLocation(this);
        }
        return -1;
    
public intgetOrientation()
Returns the orientation.

return
an integer giving the orientation
see
#setOrientation

        return orientation;
    
public doublegetResizeWeight()
Returns the number that determines how extra space is distributed.

return
how extra space is to be distributed on a resize of the split pane
since
1.3

	return resizeWeight;
    
public java.awt.ComponentgetRightComponent()
Returns the component to the right (or below) the divider.

return
the Component displayed in that position

        return rightComponent;
    
public java.awt.ComponentgetTopComponent()
Returns the component above, or to the left of the divider.

return
the Component displayed in that position

        return leftComponent;
    
public javax.swing.plaf.SplitPaneUIgetUI()
Returns the SplitPaneUI that is providing the current look and feel.

return
the SplitPaneUI object that renders this component
beaninfo
expert: true description: The L&F object that renders this component.

        return (SplitPaneUI)ui;
    
public java.lang.StringgetUIClassID()
Returns the name of the L&F class that renders this component.

return
the string "SplitPaneUI"
see
JComponent#getUIClassID
see
UIDefaults#getUI
beaninfo
expert: true description: A string that specifies the name of the L&F class.

        return uiClassID;
    
public booleanisContinuousLayout()
Gets the continuousLayout property.

return
the value of the continuousLayout property
see
#setContinuousLayout

        return continuousLayout;
    
public booleanisOneTouchExpandable()
Gets the oneTouchExpandable property.

return
the value of the oneTouchExpandable property
see
#setOneTouchExpandable

        return oneTouchExpandable;
    
public booleanisValidateRoot()
Returns true, so that calls to revalidate on any descendant of this JSplitPane will cause a request to be queued that will validate the JSplitPane and all its descendants.

return
true
see
JComponent#revalidate
beaninfo
hidden: true

        return true;
    
protected voidpaintChildren(java.awt.Graphics g)
Subclassed to message the UI with finishedPaintingChildren after super has been messaged, as well as painting the border.

param
g the Graphics context within which to paint

        super.paintChildren(g);

        SplitPaneUI        ui = getUI();

        if (ui != null) {
            Graphics           tempG = g.create();
            ui.finishedPaintingChildren(this, tempG);
            tempG.dispose();
        }
    
protected java.lang.StringparamString()
Returns a string representation of this JSplitPane. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

return
a string representation of this JSplitPane.

        String orientationString = (orientation == HORIZONTAL_SPLIT ?
                                    "HORIZONTAL_SPLIT" : "VERTICAL_SPLIT");
        String continuousLayoutString = (continuousLayout ?
                                         "true" : "false");
        String oneTouchExpandableString = (oneTouchExpandable ?
                                           "true" : "false");

        return super.paramString() +
        ",continuousLayout=" + continuousLayoutString +
        ",dividerSize=" + dividerSize +
        ",lastDividerLocation=" + lastDividerLocation +
        ",oneTouchExpandable=" + oneTouchExpandableString +
        ",orientation=" + orientationString;
    
public voidremove(java.awt.Component component)
Removes the child component, component from the pane. Resets the leftComponent or rightComponent instance variable, as necessary.

param
component the Component to remove

        if (component == leftComponent) {
            leftComponent = null;
        } else if (component == rightComponent) {
            rightComponent = null;
        }
        super.remove(component);

        // Update the JSplitPane on the screen
        revalidate();
        repaint();
    
public voidremove(int index)
Removes the Component at the specified index. Updates the leftComponent and rightComponent instance variables as necessary, and then messages super.

param
index an integer specifying the component to remove, where 1 specifies the left/top component and 2 specifies the bottom/right component

        Component    comp = getComponent(index);

        if (comp == leftComponent) {
            leftComponent = null;
        } else if (comp == rightComponent) {
            rightComponent = null;
        }
        super.remove(index);

        // Update the JSplitPane on the screen
        revalidate();
        repaint();
    
public voidremoveAll()
Removes all the child components from the split pane. Resets the leftComonent and rightComponent instance variables.

        leftComponent = rightComponent = null;
        super.removeAll();

        // Update the JSplitPane on the screen
        revalidate();
        repaint();
    
public voidresetToPreferredSizes()
Lays out the JSplitPane layout based on the preferred size of the children components. This will likely result in changing the divider location.

        SplitPaneUI         ui = getUI();

        if (ui != null) {
            ui.resetToPreferredSizes(this);
        }
    
public voidsetBottomComponent(java.awt.Component comp)
Sets the component below, or to the right of the divider.

param
comp the Component to display in that position
beaninfo
description: The component below, or to the right of the divider.

        setRightComponent(comp);
    
public voidsetContinuousLayout(boolean newContinuousLayout)
Sets the value of the continuousLayout property, which must be true for the child components to be continuously redisplayed and laid out during user intervention. The default value of this property is false. Some look and feels might not support continuous layout; they will ignore this property.

param
newContinuousLayout true if the components should continuously be redrawn as the divider changes position
beaninfo
bound: true description: Whether the child components are continuously redisplayed and laid out during user intervention.
see
#isContinuousLayout

        boolean           oldCD = continuousLayout;

        continuousLayout = newContinuousLayout;
        firePropertyChange(CONTINUOUS_LAYOUT_PROPERTY, oldCD,
                           newContinuousLayout);
    
public voidsetDividerLocation(double proportionalLocation)
Sets the divider location as a percentage of the JSplitPane's size.

This method is implemented in terms of setDividerLocation(int). This method immediately changes the size of the split pane based on its current size. If the split pane is not correctly realized and on screen, this method will have no effect (new divider location will become (current size * proportionalLocation) which is 0).

param
proportionalLocation a double-precision floating point value that specifies a percentage, from zero (top/left) to 1.0 (bottom/right)
exception
IllegalArgumentException if the specified location is < 0 or > 1.0
beaninfo
description: The location of the divider.

        if (proportionalLocation < 0.0 || 
           proportionalLocation > 1.0) {
            throw new IllegalArgumentException("proportional location must " +
                                               "be between 0.0 and 1.0.");
        }
        if (getOrientation() == VERTICAL_SPLIT) {
            setDividerLocation((int)((double)(getHeight() - getDividerSize()) *
                                     proportionalLocation));
        } else {
            setDividerLocation((int)((double)(getWidth() - getDividerSize()) *
                                     proportionalLocation));
        }
    
public voidsetDividerLocation(int location)
Sets the location of the divider. This is passed off to the look and feel implementation, and then listeners are notified. A value less than 0 implies the divider should be reset to a value that attempts to honor the preferred size of the left/top component. After notifying the listeners, the last divider location is updated, via setLastDividerLocation.

param
location an int specifying a UI-specific value (typically a pixel count)
beaninfo
bound: true description: The location of the divider.

	int                 oldValue = dividerLocation;

	dividerLocation = location;

	// Notify UI.
        SplitPaneUI         ui = getUI();

        if (ui != null) {
            ui.setDividerLocation(this, location);
        }

	// Then listeners
	firePropertyChange(DIVIDER_LOCATION_PROPERTY, oldValue, location);

	// And update the last divider location.
	setLastDividerLocation(oldValue);
    
public voidsetDividerSize(int newSize)
Sets the size of the divider.

param
newSize an integer giving the size of the divider in pixels
beaninfo
bound: true description: The size of the divider.

        int           oldSize = dividerSize;

	dividerSizeSet = true;
        if (oldSize != newSize) {
            dividerSize = newSize;
            firePropertyChange(DIVIDER_SIZE_PROPERTY, oldSize, newSize);
        }
    
public voidsetLastDividerLocation(int newLastLocation)
Sets the last location the divider was at to newLastLocation.

param
newLastLocation an integer specifying the last divider location in pixels, from the left (or upper) edge of the pane to the left (or upper) edge of the divider
beaninfo
bound: true description: The last location the divider was at.

        int               oldLocation = lastDividerLocation;

        lastDividerLocation = newLastLocation;
        firePropertyChange(LAST_DIVIDER_LOCATION_PROPERTY, oldLocation,
                           newLastLocation);
    
public voidsetLeftComponent(java.awt.Component comp)
Sets the component to the left (or above) the divider.

param
comp the Component to display in that position

        if (comp == null) {
            if (leftComponent != null) {
                remove(leftComponent);
                leftComponent = null;
            }
        } else {
            add(comp, JSplitPane.LEFT);
        }
    
public voidsetOneTouchExpandable(boolean newValue)
Sets the value of the oneTouchExpandable property, which must be true for the JSplitPane to provide a UI widget on the divider to quickly expand/collapse the divider. The default value of this property is false. Some look and feels might not support one-touch expanding; they will ignore this property.

param
newValue true to specify that the split pane should provide a collapse/expand widget
beaninfo
bound: true description: UI widget on the divider to quickly expand/collapse the divider.
see
#isOneTouchExpandable

        boolean           oldValue = oneTouchExpandable;

        oneTouchExpandable = newValue;
        oneTouchExpandableSet = true;
        firePropertyChange(ONE_TOUCH_EXPANDABLE_PROPERTY, oldValue, newValue);
        repaint();
    
public voidsetOrientation(int orientation)
Sets the orientation, or how the splitter is divided. The options are:
  • JSplitPane.VERTICAL_SPLIT (above/below orientation of components)
  • JSplitPane.HORIZONTAL_SPLIT (left/right orientation of components)

param
orientation an integer specifying the orientation
exception
IllegalArgumentException if orientation is not one of: HORIZONTAL_SPLIT or VERTICAL_SPLIT.
beaninfo
bound: true description: The orientation, or how the splitter is divided. enum: HORIZONTAL_SPLIT JSplitPane.HORIZONTAL_SPLIT VERTICAL_SPLIT JSplitPane.VERTICAL_SPLIT

        if ((orientation != VERTICAL_SPLIT) &&
            (orientation != HORIZONTAL_SPLIT)) {
           throw new IllegalArgumentException("JSplitPane: orientation must " +
                                              "be one of " +
                                              "JSplitPane.VERTICAL_SPLIT or " +
                                              "JSplitPane.HORIZONTAL_SPLIT");
        }

        int           oldOrientation = this.orientation;

        this.orientation = orientation;
        firePropertyChange(ORIENTATION_PROPERTY, oldOrientation, orientation);
    
public voidsetResizeWeight(double value)
Specifies how to distribute extra space when the size of the split pane changes. A value of 0, the default, indicates the right/bottom component gets all the extra space (the left/top component acts fixed), where as a value of 1 specifies the left/top component gets all the extra space (the right/bottom component acts fixed). Specifically, the left/top component gets (weight * diff) extra space and the right/bottom component gets (1 - weight) * diff extra space.

param
value as described above
exception
IllegalArgumentException if value is < 0 or > 1
since
1.3
beaninfo
bound: true description: Specifies how to distribute extra space when the split pane resizes.

	if (value < 0 || value > 1) {
	    throw new IllegalArgumentException("JSplitPane weight must be between 0 and 1");
	}
	double         oldWeight = resizeWeight;

	resizeWeight = value;
	firePropertyChange(RESIZE_WEIGHT_PROPERTY, oldWeight, value);
    
public voidsetRightComponent(java.awt.Component comp)
Sets the component to the right (or below) the divider.

param
comp the Component to display in that position
beaninfo
preferred: true description: The component to the right (or below) the divider.

        if (comp == null) {
            if (rightComponent != null) {
                remove(rightComponent);
                rightComponent = null;
            }
        } else {
            add(comp, JSplitPane.RIGHT);
        }
    
public voidsetTopComponent(java.awt.Component comp)
Sets the component above, or to the left of the divider.

param
comp the Component to display in that position
beaninfo
description: The component above, or to the left of the divider.

        setLeftComponent(comp);
    
public voidsetUI(javax.swing.plaf.SplitPaneUI ui)
Sets the L&F object that renders this component.

param
ui the SplitPaneUI L&F object
see
UIDefaults#getUI
beaninfo
bound: true hidden: true attribute: visualUpdate true description: The UI object that implements the Component's LookAndFeel.

        if ((SplitPaneUI)this.ui != ui) {
            super.setUI(ui);
            revalidate();
        }
    
voidsetUIProperty(java.lang.String propertyName, java.lang.Object value)

        if (propertyName == "dividerSize") {
	    if (!dividerSizeSet) {
		setDividerSize(((Number)value).intValue());
		dividerSizeSet = false;
	    }
        } else if (propertyName == "oneTouchExpandable") {
            if (!oneTouchExpandableSet) {
                setOneTouchExpandable(((Boolean)value).booleanValue());
                oneTouchExpandableSet = false;
            }
	} else {
	    super.setUIProperty(propertyName, value);
	}
    
public voidupdateUI()
Notification from the UIManager that the L&F has changed. Replaces the current UI object with the latest version from the UIManager.

see
JComponent#updateUI

        setUI((SplitPaneUI)UIManager.getUI(this));
        revalidate();
    
private voidwriteObject(java.io.ObjectOutputStream s)
See readObject and writeObject in JComponent for more information about serialization in Swing.

        s.defaultWriteObject();
        if (getUIClassID().equals(uiClassID)) {
            byte count = JComponent.getWriteObjCounter(this);
            JComponent.setWriteObjCounter(this, --count);
            if (count == 0 && ui != null) {
                ui.installUI(this);
            }
        }