/*

 * Copyright (c) 1997, 2008, Oracle and/or its affiliates. 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.  Oracle designates this

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

 * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

package javax.swing;

import javax.swing.plaf.*;

import javax.swing.border.*;

import javax.swing.event.*;

import javax.accessibility.*;

import java.awt.Component;

import java.awt.ComponentOrientation;

import java.awt.Rectangle;

import java.awt.Insets;

import java.awt.LayoutManager;

import java.awt.Point;

import java.io.ObjectOutputStream;

import java.io.IOException;

import java.beans.PropertyChangeEvent;

import java.beans.PropertyChangeListener;

import java.beans.Transient;

/**

 * Provides a scrollable view of a lightweight component.

 * A <code>JScrollPane</code> manages a viewport, optional

 * vertical and horizontal scroll bars, and optional row and

 * column heading viewports.

 * You can find task-oriented documentation of <code>JScrollPane</code> in

 *  <a href="http://java.sun.com/docs/books/tutorial/uiswing/components/scrollpane.html">How to Use Scroll Panes</a>,

 * a section in <em>The Java Tutorial</em>.  Note that

 * <code>JScrollPane</code> does not support heavyweight components.

 * <p>

 * <TABLE ALIGN="RIGHT" BORDER="0" SUMMARY="layout">

 *    <TR>

 *    <TD ALIGN="CENTER">

 *      <P ALIGN="CENTER"><IMG SRC="doc-files/JScrollPane-1.gif"

 *      alt="The following text describes this image."

 *      WIDTH="256" HEIGHT="248" ALIGN="BOTTOM" BORDER="0">

 *    </TD>

 *    </TR>

 * </TABLE>

 * The <code>JViewport</code> provides a window,

 * or "viewport" onto a data

 * source -- for example, a text file. That data source is the

 * "scrollable client" (aka data model) displayed by the

 * <code>JViewport</code> view.

 * A <code>JScrollPane</code> basically consists of <code>JScrollBar</code>s,

 * a <code>JViewport</code>, and the wiring between them,

 * as shown in the diagram at right.

 * <p>

 * In addition to the scroll bars and viewport,

 * a <code>JScrollPane</code> can have a

 * column header and a row header. Each of these is a

 * <code>JViewport</code> object that

 * you specify with <code>setRowHeaderView</code>,

 * and <code>setColumnHeaderView</code>.

 * The column header viewport automatically scrolls left and right, tracking

 * the left-right scrolling of the main viewport.

 * (It never scrolls vertically, however.)

 * The row header acts in a similar fashion.

 * <p>

 * Where two scroll bars meet, the row header meets the column header,

 * or a scroll bar meets one of the headers, both components stop short

 * of the corner, leaving a rectangular space which is, by default, empty.

 * These spaces can potentially exist in any number of the four corners.

 * In the previous diagram, the top right space is present and identified

 * by the label "corner component".

 * <p>

 * Any number of these empty spaces can be replaced by using the

 * <code>setCorner</code> method to add a component to a particular corner.

 * (Note: The same component cannot be added to multiple corners.)

 * This is useful if there's

 * some extra decoration or function you'd like to add to the scroll pane.

 * The size of each corner component is entirely determined by the size of the

 * headers and/or scroll bars that surround it.

 * <p>

 * A corner component will only be visible if there is an empty space in that

 * corner for it to exist in. For example, consider a component set into the

 * top right corner of a scroll pane with a column header. If the scroll pane's

 * vertical scrollbar is not present, perhaps because the view component hasn't

 * grown large enough to require it, then the corner component will not be

 * shown (since there is no empty space in that corner created by the meeting

 * of the header and vertical scroll bar). Forcing the scroll bar to always be

 * shown, using

 * <code>setVerticalScrollBarPolicy(VERTICAL_SCROLLBAR_ALWAYS)</code>,

 * will ensure that the space for the corner component always exists.

 * <p>

 * To add a border around the main viewport,

 * you can use <code>setViewportBorder</code>.

 * (Of course, you can also add a border around the whole scroll pane using

 * <code>setBorder</code>.)

 * <p>

 * A common operation to want to do is to set the background color that will

 * be used if the main viewport view is smaller than the viewport, or is

 * not opaque. This can be accomplished by setting the background color

 * of the viewport, via <code>scrollPane.getViewport().setBackground()</code>.

 * The reason for setting the color of the viewport and not the scrollpane

 * is that by default <code>JViewport</code> is opaque

 * which, among other things, means it will completely fill

 * in its background using its background color.  Therefore when

 * <code>JScrollPane</code> draws its background the viewport will

 * usually draw over it.

 * <p>

 * By default <code>JScrollPane</code> uses <code>ScrollPaneLayout</code>

 * to handle the layout of its child Components. <code>ScrollPaneLayout</code>

 * determines the size to make the viewport view in one of two ways:

 * <ol>

 *   <li>If the view implements <code>Scrollable</code>

 *       a combination of <code>getPreferredScrollableViewportSize</code>,

 *       <code>getScrollableTracksViewportWidth</code> and

 *       <code>getScrollableTracksViewportHeight</code>is used, otherwise

 *   <li><code>getPreferredSize</code> is used.

 * </ol>

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

 * @see JViewport

 * @see ScrollPaneLayout

 * @see Scrollable

 * @see Component#getPreferredSize

 * @see #setViewportView

 * @see #setRowHeaderView

 * @see #setColumnHeaderView

 * @see #setCorner

 * @see #setViewportBorder

 *

 * @beaninfo

 *     attribute: isContainer true

 *     attribute: containerDelegate getViewport

 *   description: A specialized container that manages a viewport, optional scrollbars and headers

 *

 * @author Hans Muller

 */

public class JScrollPane extends JComponent implements ScrollPaneConstants, Accessible

{

    private Border viewportBorder;

    /**

     * @see #getUIClassID

     * @see #readObject

     */

    private static final String uiClassID = "ScrollPaneUI";

    /**

     * The display policy for the vertical scrollbar.

     * The default is

     * <code>ScrollPaneConstants.VERTICAL_SCROLLBAR_AS_NEEDED</code>.

     * @see #setVerticalScrollBarPolicy

     */

    protected int verticalScrollBarPolicy = VERTICAL_SCROLLBAR_AS_NEEDED;

    /**

     * The display policy for the horizontal scrollbar.

     * The default is

     * <code>ScrollPaneConstants.HORIZONTAL_SCROLLBAR_AS_NEEDED</code>.

     * @see #setHorizontalScrollBarPolicy

     */

    protected int horizontalScrollBarPolicy = HORIZONTAL_SCROLLBAR_AS_NEEDED;

    /**

     * The scrollpane's viewport child.  Default is an empty

     * <code>JViewport</code>.

     * @see #setViewport

     */

    protected JViewport viewport;

    /**

     * The scrollpane's vertical scrollbar child.

     * Default is a <code>JScrollBar</code>.

     * @see #setVerticalScrollBar

     */

    protected JScrollBar verticalScrollBar;

    /**

     * The scrollpane's horizontal scrollbar child.

     * Default is a <code>JScrollBar</code>.

     * @see #setHorizontalScrollBar

     */

    protected JScrollBar horizontalScrollBar;

    /**

     * The row header child.  Default is <code>null</code>.

     * @see #setRowHeader

     */

    protected JViewport rowHeader;

    /**

     * The column header child.  Default is <code>null</code>.

     * @see #setColumnHeader

     */

    protected JViewport columnHeader;

    /**

     * The component to display in the lower left corner.

     * Default is <code>null</code>.

     * @see #setCorner

     */

    protected Component lowerLeft;

    /**

     * The component to display in the lower right corner.

     * Default is <code>null</code>.

     * @see #setCorner

     */

    protected Component lowerRight;

    /**

     * The component to display in the upper left corner.

     * Default is <code>null</code>.

     * @see #setCorner

     */

    protected Component upperLeft;

    /**

     * The component to display in the upper right corner.

     * Default is <code>null</code>.

     * @see #setCorner

     */

    protected Component upperRight;

    /*

     * State flag for mouse wheel scrolling

     */

    private boolean wheelScrollState = true;

    /**

     * Creates a <code>JScrollPane</code> that displays the view

     * component in a viewport

     * whose view position can be controlled with a pair of scrollbars.

     * The scrollbar policies specify when the scrollbars are displayed,

     * For example, if <code>vsbPolicy</code> is

     * <code>VERTICAL_SCROLLBAR_AS_NEEDED</code>

     * then the vertical scrollbar only appears if the view doesn't fit

     * vertically. The available policy settings are listed at

     * {@link #setVerticalScrollBarPolicy} and

     * {@link #setHorizontalScrollBarPolicy}.

     *

     * @see #setViewportView

     *

     * @param view the component to display in the scrollpanes viewport

     * @param vsbPolicy an integer that specifies the vertical

     *          scrollbar policy

     * @param hsbPolicy an integer that specifies the horizontal

     *          scrollbar policy

     */

    public JScrollPane(Component view, int vsbPolicy, int hsbPolicy)

    {

        setLayout(new ScrollPaneLayout.UIResource());

        setVerticalScrollBarPolicy(vsbPolicy);

        setHorizontalScrollBarPolicy(hsbPolicy);

        setViewport(createViewport());

        setVerticalScrollBar(createVerticalScrollBar());

        setHorizontalScrollBar(createHorizontalScrollBar());

        if (view != null) {

            setViewportView(view);

        }

        setUIProperty("opaque",true);

        updateUI();

        if (!this.getComponentOrientation().isLeftToRight()) {

            viewport.setViewPosition(new Point(Integer.MAX_VALUE, 0));

        }

    }

    /**

     * Creates a <code>JScrollPane</code> that displays the

     * contents of the specified

     * component, where both horizontal and vertical scrollbars appear

     * whenever the component's contents are larger than the view.

     *

     * @see #setViewportView

     * @param view the component to display in the scrollpane's viewport

     */

    public JScrollPane(Component view) {

        this(view, VERTICAL_SCROLLBAR_AS_NEEDED, HORIZONTAL_SCROLLBAR_AS_NEEDED);

    }

    /**

     * Creates an empty (no viewport view) <code>JScrollPane</code>

     * with specified

     * scrollbar policies. The available policy settings are listed at

     * {@link #setVerticalScrollBarPolicy} and

     * {@link #setHorizontalScrollBarPolicy}.

     *

     * @see #setViewportView

     *

     * @param vsbPolicy an integer that specifies the vertical

     *          scrollbar policy

     * @param hsbPolicy an integer that specifies the horizontal

     *          scrollbar policy

     */

    public JScrollPane(int vsbPolicy, int hsbPolicy) {

        this(null, vsbPolicy, hsbPolicy);

    }

    /**

     * Creates an empty (no viewport view) <code>JScrollPane</code>

     * where both horizontal and vertical scrollbars appear when needed.

     */

    public JScrollPane() {

        this(null, VERTICAL_SCROLLBAR_AS_NEEDED, HORIZONTAL_SCROLLBAR_AS_NEEDED);

    }

    /**

     * Returns the look and feel (L&F) object that renders this component.

     *

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

     *                          component

     * @see #setUI

     * @beaninfo

     *        bound: true

     *       hidden: true

     *    attribute: visualUpdate true

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

     */

    public ScrollPaneUI getUI() {

        return (ScrollPaneUI)ui;

    }

    /**

     * Sets the <code>ScrollPaneUI</code> object that provides the

     * look and feel (L&F) for this component.

     *

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

     * @see #getUI

     */

    public void setUI(ScrollPaneUI ui) {

        super.setUI(ui);

    }

    /**

     * Replaces the current <code>ScrollPaneUI</code> object with a version

     * from the current default look and feel.

     * To be called when the default look and feel changes.

     *

     * @see JComponent#updateUI

     * @see UIManager#getUI

     */

    public void updateUI() {

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

    }

    /**

     * Returns the suffix used to construct the name of the L&F class used to

     * render this component.

     *

     * @return the string "ScrollPaneUI"

     * @see JComponent#getUIClassID

     * @see UIDefaults#getUI

     *

     * @beaninfo

     *    hidden: true

     */

    public String getUIClassID() {

        return uiClassID;

    }

    /**

     * Sets the layout manager for this <code>JScrollPane</code>.

     * This method overrides <code>setLayout</code> in

     * <code>java.awt.Container</code> to ensure that only

     * <code>LayoutManager</code>s which

     * are subclasses of <code>ScrollPaneLayout</code> can be used in a

     * <code>JScrollPane</code>. If <code>layout</code> is non-null, this

     * will invoke <code>syncWithScrollPane</code> on it.

     *

     * @param layout the specified layout manager

     * @exception ClassCastException if layout is not a

     *                  <code>ScrollPaneLayout</code>

     * @see java.awt.Container#getLayout

     * @see java.awt.Container#setLayout

     *

     * @beaninfo

     *    hidden: true

     */

    public void setLayout(LayoutManager layout) {

        if (layout instanceof ScrollPaneLayout) {

            super.setLayout(layout);

            ((ScrollPaneLayout)layout).syncWithScrollPane(this);

        }

        else if (layout == null) {

            super.setLayout(layout);

        }

        else {

            String s = "layout of JScrollPane must be a ScrollPaneLayout";

            throw new ClassCastException(s);

        }

    }

    /**

     * Overridden to return true so that any calls to <code>revalidate</code>

     * on any descendants of this <code>JScrollPane</code> will cause the

     * entire tree beginning with this <code>JScrollPane</code> to be

     * validated.

     *

     * @return true

     * @see java.awt.Container#validate

     * @see JComponent#revalidate

     * @see JComponent#isValidateRoot

     * @see java.awt.Container#isValidateRoot

     *

     * @beaninfo

     *    hidden: true

     */

    @Override

    public boolean isValidateRoot() {

        return true;

    }

    /**

     * Returns the vertical scroll bar policy value.

     * @return the <code>verticalScrollBarPolicy</code> property

     * @see #setVerticalScrollBarPolicy

     */

    public int getVerticalScrollBarPolicy() {

        return verticalScrollBarPolicy;

    }

    /**

     * Determines when the vertical scrollbar appears in the scrollpane.

     * Legal values are:

     * <ul>

     * <li><code>ScrollPaneConstants.VERTICAL_SCROLLBAR_AS_NEEDED</code>

     * <li><code>ScrollPaneConstants.VERTICAL_SCROLLBAR_NEVER</code>

     * <li><code>ScrollPaneConstants.VERTICAL_SCROLLBAR_ALWAYS</code>

     * </ul>

     *

     * @param policy one of the three values listed above

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

     *                          is not one of the legal values shown above

     * @see #getVerticalScrollBarPolicy

     *

     * @beaninfo

     *   preferred: true

     *       bound: true

     * description: The scrollpane vertical scrollbar policy

     *        enum: VERTICAL_SCROLLBAR_AS_NEEDED ScrollPaneConstants.VERTICAL_SCROLLBAR_AS_NEEDED

     *              VERTICAL_SCROLLBAR_NEVER ScrollPaneConstants.VERTICAL_SCROLLBAR_NEVER

     *              VERTICAL_SCROLLBAR_ALWAYS ScrollPaneConstants.VERTICAL_SCROLLBAR_ALWAYS

     */

    public void setVerticalScrollBarPolicy(int policy) {

        switch (policy) {

        case VERTICAL_SCROLLBAR_AS_NEEDED:

        case VERTICAL_SCROLLBAR_NEVER:

        case VERTICAL_SCROLLBAR_ALWAYS:

                break;

        default:

            throw new IllegalArgumentException("invalid verticalScrollBarPolicy");

        }

        int old = verticalScrollBarPolicy;

        verticalScrollBarPolicy = policy;

        firePropertyChange("verticalScrollBarPolicy", old, policy);

        revalidate();

        repaint();

    }

    /**

     * Returns the horizontal scroll bar policy value.

     * @return the <code>horizontalScrollBarPolicy</code> property

     * @see #setHorizontalScrollBarPolicy

     */

    public int getHorizontalScrollBarPolicy() {

        return horizontalScrollBarPolicy;

    }

    /**

     * Determines when the horizontal scrollbar appears in the scrollpane.