/*

 * Copyright 1997-2008 Sun Microsystems, Inc.  All Rights Reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Sun designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Sun in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

 * CA 95054 USA or visit www.sun.com if you need additional information or

 * have any questions.

 */

package javax.swing;

import java.beans.ConstructorProperties;

import javax.swing.plaf.*;

import javax.accessibility.*;

import java.awt.*;

import java.io.ObjectOutputStream;

import java.io.ObjectInputStream;

import java.io.IOException;

/**

 * <code>JSplitPane</code> is used to divide two (and only two)

 * <code>Component</code>s. The two <code>Component</code>s

 * are graphically divided based on the look and feel

 * implementation, and the two <code>Component</code>s can then be

 * interactively resized by the user.

 * Information on using <code>JSplitPane</code> is in

 * <a

 href="http://java.sun.com/docs/books/tutorial/uiswing/components/splitpane.html">How to Use Split Panes</a> in

 * <em>The Java Tutorial</em>.

 * <p>

 * The two <code>Component</code>s in a split pane can be aligned

 * left to right using

 * <code>JSplitPane.HORIZONTAL_SPLIT</code>, or top to bottom using

 * <code>JSplitPane.VERTICAL_SPLIT</code>.

 * The preferred way to change the size of the <code>Component</code>s

 * is to invoke

 * <code>setDividerLocation</code> where <code>location</code> is either

 * the new x or y position, depending on the orientation of the

 * <code>JSplitPane</code>.

 * <p>

 * To resize the <code>Component</code>s to their preferred sizes invoke

 * <code>resetToPreferredSizes</code>.

 * <p>

 * When the user is resizing the <code>Component</code>s the minimum

 * size of the <code>Components</code> is used to determine the

 * maximum/minimum position the <code>Component</code>s

 * 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

 * <code>JComponent</code>, see {@link JComponent#setMinimumSize}.

 * <p>

 * When the user resizes the split pane the new space is distributed between

 * the two components based on the <code>resizeWeight</code> 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.

 * <p>

 * <strong>Warning:</strong> Swing is not thread safe. For more

 * information see <a

 * href="package-summary.html#threading">Swing's Threading

 * Policy</a>.

 * <p>

 * <strong>Warning:</strong>

 * 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 JavaBeans<sup><font size="-2">TM</font></sup>

 * has been added to the <code>java.beans</code> package.

 * Please see {@link java.beans.XMLEncoder}.

 *

 * @see #setDividerLocation

 * @see #resetToPreferredSizes

 *

 * @author Scott Violet

 */

public class JSplitPane extends JComponent implements Accessible

{

    /**

     * @see #getUIClassID

     * @see #readObject

     */

    private static final String uiClassID = "SplitPaneUI";

    /**

     * Vertical split indicates the <code>Component</code>s are

     * split along the y axis.  For example the two

     * <code>Component</code>s will be split one on top of the other.

     */

    public final static int VERTICAL_SPLIT = 0;

    /**

     * Horizontal split indicates the <code>Component</code>s are

     * split along the x axis.  For example the two

     * <code>Component</code>s will be split one to the left of the

     * other.

     */

    public final static int HORIZONTAL_SPLIT = 1;

    /**

     * Used to add a <code>Component</code> to the left of the other

     * <code>Component</code>.

     */

    public final static String LEFT = "left";

    /**

     * Used to add a <code>Component</code> to the right of the other

     * <code>Component</code>.

     */

    public final static String RIGHT = "right";

    /**

     * Used to add a <code>Component</code> above the other

     * <code>Component</code>.

     */

    public final static String TOP = "top";

    /**

     * Used to add a <code>Component</code> below the other

     * <code>Component</code>.

     */

    public final static String BOTTOM = "bottom";

    /**

     * Used to add a <code>Component</code> that will represent the divider.

     */

    public final static String DIVIDER = "divider";

    /**

     * Bound property name for orientation (horizontal or vertical).

     */

    public final static String ORIENTATION_PROPERTY = "orientation";

    /**

     * Bound property name for continuousLayout.

     */

    public final static String CONTINUOUS_LAYOUT_PROPERTY = "continuousLayout";

    /**

     * Bound property name for border.

     */

    public final static String DIVIDER_SIZE_PROPERTY = "dividerSize";

    /**

     * Bound property for oneTouchExpandable.

     */

    public final static String ONE_TOUCH_EXPANDABLE_PROPERTY =

                               "oneTouchExpandable";

    /**

     * Bound property for lastLocation.

     */

    public final static String LAST_DIVIDER_LOCATION_PROPERTY =

                               "lastDividerLocation";

    /**

     * Bound property for the dividerLocation.

     * @since 1.3

     */

    public final static String DIVIDER_LOCATION_PROPERTY = "dividerLocation";

    /**

     * Bound property for weight.

     * @since 1.3

     */

    public final static String RESIZE_WEIGHT_PROPERTY = "resizeWeight";

    /**

     * How the views are split.

     */

    protected int orientation;

    /**

     * Whether or not the views are continuously redisplayed while

     * resizing.

     */

    protected boolean continuousLayout;

    /**

     * The left or top component.

     */

    protected Component leftComponent;

    /**

     * The right or bottom component.

     */

    protected Component rightComponent;

    /**

     * Size of the divider.

     */

    protected int dividerSize;

    private boolean dividerSizeSet = false;

    /**

     * Is a little widget provided to quickly expand/collapse the

     * split pane?

     */

    protected boolean oneTouchExpandable;

    private boolean oneTouchExpandableSet;

    /**

     * Previous location of the split pane.

     */

    protected int lastDividerLocation;

    /**

     * How to distribute extra space.

     */

    private double resizeWeight;

    /**

     * Location of the divider, at least the value that was set, the UI may

     * have a different value.

     */

    private int dividerLocation;

    /**

     * Creates a new <code>JSplitPane</code> configured to arrange the child

     * components side-by-side horizontally with no continuous

     * layout, using two buttons for the components.

     */

    public JSplitPane() {

        this(JSplitPane.HORIZONTAL_SPLIT,

            UIManager.getBoolean("SplitPane.continuousLayout"),

            new JButton(UIManager.getString("SplitPane.leftButtonText")),

            new JButton(UIManager.getString("SplitPane.rightButtonText")));

    }

    /**

     * Creates a new <code>JSplitPane</code> configured with the

     * specified orientation and no continuous layout.

     *

     * @param newOrientation  <code>JSplitPane.HORIZONTAL_SPLIT</code> or

     *                        <code>JSplitPane.VERTICAL_SPLIT</code>

     * @exception IllegalArgumentException if <code>orientation</code>

     *          is not one of HORIZONTAL_SPLIT or VERTICAL_SPLIT.

     */

    @ConstructorProperties({"orientation"})

    public JSplitPane(int newOrientation) {

        this(newOrientation,

            UIManager.getBoolean("SplitPane.continuousLayout"));

    }

    /**

     * Creates a new <code>JSplitPane</code> with the specified

     * orientation and redrawing style.

     *

     * @param newOrientation  <code>JSplitPane.HORIZONTAL_SPLIT</code> or

     *                        <code>JSplitPane.VERTICAL_SPLIT</code>

     * @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 <code>orientation</code>

     *          is not one of HORIZONTAL_SPLIT or VERTICAL_SPLIT

     */

    public JSplitPane(int newOrientation,

                      boolean newContinuousLayout) {

        this(newOrientation, newContinuousLayout, null, null);

    }

    /**

     * Creates a new <code>JSplitPane</code> with the specified

     * orientation and

     * with the specified components that do not do continuous

     * redrawing.

     *

     * @param newOrientation  <code>JSplitPane.HORIZONTAL_SPLIT</code> or

     *                        <code>JSplitPane.VERTICAL_SPLIT</code>

     * @param newLeftComponent the <code>Component</code> that will

     *          appear on the left

     *          of a horizontally-split pane, or at the top of a

     *          vertically-split pane

     * @param newRightComponent the <code>Component</code> that will

     *          appear on the right

     *          of a horizontally-split pane, or at the bottom of a

     *          vertically-split pane

     * @exception IllegalArgumentException if <code>orientation</code>

     *          is not one of: HORIZONTAL_SPLIT or VERTICAL_SPLIT

     */

    public JSplitPane(int newOrientation,

                      Component newLeftComponent,

                      Component newRightComponent){

        this(newOrientation,

            UIManager.getBoolean("SplitPane.continuousLayout"),

            newLeftComponent, newRightComponent);

    }

    /**

     * Creates a new <code>JSplitPane</code> with the specified

     * orientation and

     * redrawing style, and with the specified components.

     *

     * @param newOrientation  <code>JSplitPane.HORIZONTAL_SPLIT</code> or

     *                        <code>JSplitPane.VERTICAL_SPLIT</code>

     * @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 <code>Component</code> that will

     *          appear on the left

     *          of a horizontally-split pane, or at the top of a

     *          vertically-split pane

     * @param newRightComponent the <code>Component</code> that will

     *          appear on the right

     *          of a horizontally-split pane, or at the bottom of a

     *          vertically-split pane

     * @exception IllegalArgumentException if <code>orientation</code>

     *          is not one of HORIZONTAL_SPLIT or VERTICAL_SPLIT

     */

    public JSplitPane(int newOrientation,

                      boolean newContinuousLayout,

                      Component newLeftComponent,

                      Component newRightComponent){

        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();

    }

    /**

     * Sets the L&F object that renders this component.

     *

     * @param ui  the <code>SplitPaneUI</code> L&F object

     * @see UIDefaults#getUI

     * @beaninfo

     *        bound: true

     *       hidden: true

     *    attribute: visualUpdate true

     *  description: The UI object that implements the Component's LookAndFeel.

     */

    public void setUI(SplitPaneUI ui) {

        if ((SplitPaneUI)this.ui != ui) {

            super.setUI(ui);

            revalidate();

        }

    }

    /**

     * Returns the <code>SplitPaneUI</code> that is providing the

     * current look and feel.

     *

     * @return the <code>SplitPaneUI</code> object that renders this component

     * @beaninfo

     *       expert: true

     *  description: The L&F object that renders this component.

     */

    public SplitPaneUI getUI() {

        return (SplitPaneUI)ui;

    }

    /**

     * Notification from the <code>UIManager</code> that the L&F has changed.

     * Replaces the current UI object with the latest version from the

     * <code>UIManager</code>.

     *

     * @see JComponent#updateUI

     */

    public void updateUI() {

        setUI((SplitPaneUI)UIManager.getUI(this));

        revalidate();

    }

    /**

     * 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.

     */

    public String getUIClassID() {

        return uiClassID;

    }

    /**

     * 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.

     */

    public void setDividerSize(int newSize) {

        int           oldSize = dividerSize;

        dividerSizeSet = true;

        if (oldSize != newSize) {

            dividerSize = newSize;

            firePropertyChange(DIVIDER_SIZE_PROPERTY, oldSize, newSize);

        }

    }

    /**

     * Returns the size of the divider.

     *

     * @return an integer giving the size of the divider in pixels

     */

    public int getDividerSize() {

        return dividerSize;

    }

    /**

     * Sets the component to the left (or above) the divider.

     *

     * @param comp the <code>Component</code> to display in that position

     */

    public void setLeftComponent(Component comp) {

        if (comp == null) {

            if (leftComponent != null) {

                remove(leftComponent);

                leftComponent = null;

            }

        } else {

            add(comp, JSplitPane.LEFT);

        }

    }

    /**

     * Returns the component to the left (or above) the divider.

     *

     * @return the <code>Component</code> displayed in that position

     * @beaninfo

     *    preferred: true

     *  description: The component to the left (or above) the divider.

     */

    public Component getLeftComponent() {

        return leftComponent;

    }

    /**

     * Sets the component above, or to the left of the divider.

     *

     * @param comp the <code>Component</code> to display in that position

     * @beaninfo

     *  description: The component above, or to the left of the divider.

     */

    public void setTopComponent(Component comp) {

        setLeftComponent(comp);

    }

    /**

     * Returns the component above, or to the left of the divider.

     *

     * @return the <code>Component</code> displayed in that position

     */

    public Component getTopComponent() {

        return leftComponent;

    }

    /**

     * Sets the component to the right (or below) the divider.

     *

     * @param comp the <code>Component</code> to display in that position

     * @beaninfo

     *    preferred: true

     *  description: The component to the right (or below) the divider.

     */

    public void setRightComponent(Component comp) {

        if (comp == null) {

            if (rightComponent != null) {

                remove(rightComponent);

                rightComponent = null;

            }

        } else {

            add(comp, JSplitPane.RIGHT);

        }

    }

    /**

     * Returns the component to the right (or below) the divider.