/*

 * 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 java.io.Serializable;

import java.awt.Component;

import java.awt.Adjustable;

import java.awt.Dimension;

import java.awt.event.AdjustmentListener;

import java.awt.event.AdjustmentEvent;

import java.awt.Graphics;

import javax.swing.event.*;

import javax.swing.plaf.*;

import javax.accessibility.*;

import java.io.ObjectOutputStream;

import java.io.ObjectInputStream;

import java.io.IOException;

/**

 * An implementation of a scrollbar. The user positions the knob in the

 * scrollbar to determine the contents of the viewing area. The

 * program typically adjusts the display so that the end of the

 * scrollbar represents the end of the displayable contents, or 100%

 * of the contents. The start of the scrollbar is the beginning of the

 * displayable contents, or 0%. The position of the knob within

 * those bounds then translates to the corresponding percentage of

 * the displayable contents.

 * <p>

 * Typically, as the position of the knob in the scrollbar changes

 * a corresponding change is made to the position of the JViewport on

 * the underlying view, changing the contents of the JViewport.

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

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

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

 *

 * @see JScrollPane

 * @beaninfo

 *      attribute: isContainer false

 *    description: A component that helps determine the visible content range of an area.

 *

 * @author David Kloba

 */

public class JScrollBar extends JComponent implements Adjustable, Accessible

{

    /**

     * @see #getUIClassID

     * @see #readObject

     */

    private static final String uiClassID = "ScrollBarUI";

    /**

     * All changes from the model are treated as though the user moved

     * the scrollbar knob.

     */

    private ChangeListener fwdAdjustmentEvents = new ModelListener();

    /**

     * The model that represents the scrollbar's minimum, maximum, extent

     * (aka "visibleAmount") and current value.

     * @see #setModel

     */

    protected BoundedRangeModel model;

    /**

     * @see #setOrientation

     */

    protected int orientation;

    /**

     * @see #setUnitIncrement

     */

    protected int unitIncrement;

    /**

     * @see #setBlockIncrement

     */

    protected int blockIncrement;

    private void checkOrientation(int orientation) {

        switch (orientation) {

        case VERTICAL:

        case HORIZONTAL:

            break;

        default:

            throw new IllegalArgumentException("orientation must be one of: VERTICAL, HORIZONTAL");

        }

    }

    /**

     * Creates a scrollbar with the specified orientation,

     * value, extent, minimum, and maximum.

     * The "extent" is the size of the viewable area. It is also known

     * as the "visible amount".

     * <p>

     * Note: Use <code>setBlockIncrement</code> to set the block

     * increment to a size slightly smaller than the view's extent.

     * That way, when the user jumps the knob to an adjacent position,

     * one or two lines of the original contents remain in view.

     *

     * @exception IllegalArgumentException if orientation is not one of VERTICAL, HORIZONTAL

     *

     * @see #setOrientation

     * @see #setValue

     * @see #setVisibleAmount

     * @see #setMinimum

     * @see #setMaximum

     */

    public JScrollBar(int orientation, int value, int extent, int min, int max)

    {

        checkOrientation(orientation);

        this.unitIncrement = 1;

        this.blockIncrement = (extent == 0) ? 1 : extent;

        this.orientation = orientation;

        this.model = new DefaultBoundedRangeModel(value, extent, min, max);

        this.model.addChangeListener(fwdAdjustmentEvents);

        setRequestFocusEnabled(false);

        updateUI();

    }

    /**

     * Creates a scrollbar with the specified orientation

     * and the following initial values:

     * <pre>

     * minimum = 0

     * maximum = 100

     * value = 0

     * extent = 10

     * </pre>

     */

    public JScrollBar(int orientation) {

        this(orientation, 0, 10, 0, 100);

    }

    /**

     * Creates a vertical scrollbar with the following initial values:

     * <pre>

     * minimum = 0

     * maximum = 100

     * value = 0

     * extent = 10

     * </pre>

     */

    public JScrollBar() {

        this(VERTICAL);

    }

    /**

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

     *

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

     * @see UIDefaults#getUI

     * @since 1.4

     * @beaninfo

     *        bound: true

     *       hidden: true

     *    attribute: visualUpdate true

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

     */

    public void setUI(ScrollBarUI ui) {

        super.setUI(ui);

    }

    /**

     * Returns the delegate that implements the look and feel for

     * this component.

     *

     * @see JComponent#setUI

     */

    public ScrollBarUI getUI() {

        return (ScrollBarUI)ui;

    }

    /**

     * Overrides <code>JComponent.updateUI</code>.

     * @see JComponent#updateUI

     */

    public void updateUI() {

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

    }

    /**

     * Returns the name of the LookAndFeel class for this component.

     *

     * @return "ScrollBarUI"

     * @see JComponent#getUIClassID

     * @see UIDefaults#getUI

     */

    public String getUIClassID() {

        return uiClassID;

    }

    /**

     * Returns the component's orientation (horizontal or vertical).

     *

     * @return VERTICAL or HORIZONTAL

     * @see #setOrientation

     * @see java.awt.Adjustable#getOrientation

     */

    public int getOrientation() {

        return orientation;

    }

    /**

     * Set the scrollbar's orientation to either VERTICAL or

     * HORIZONTAL.

     *

     * @exception IllegalArgumentException if orientation is not one of VERTICAL, HORIZONTAL

     * @see #getOrientation

     * @beaninfo

     *    preferred: true

     *        bound: true

     *    attribute: visualUpdate true

     *  description: The scrollbar's orientation.

     *         enum: VERTICAL JScrollBar.VERTICAL

     *               HORIZONTAL JScrollBar.HORIZONTAL

     */

    public void setOrientation(int orientation)

    {

        checkOrientation(orientation);

        int oldValue = this.orientation;

        this.orientation = orientation;

        firePropertyChange("orientation", oldValue, orientation);

        if ((oldValue != orientation) && (accessibleContext != null)) {

            accessibleContext.firePropertyChange(

                    AccessibleContext.ACCESSIBLE_STATE_PROPERTY,

                    ((oldValue == VERTICAL)

                     ? AccessibleState.VERTICAL : AccessibleState.HORIZONTAL),

                    ((orientation == VERTICAL)

                     ? AccessibleState.VERTICAL : AccessibleState.HORIZONTAL));

        }

        if (orientation != oldValue) {

            revalidate();

        }

    }

    /**

     * Returns data model that handles the scrollbar's four

     * fundamental properties: minimum, maximum, value, extent.

     *

     * @see #setModel

     */

    public BoundedRangeModel getModel() {

        return model;

    }

    /**

     * Sets the model that handles the scrollbar's four

     * fundamental properties: minimum, maximum, value, extent.

     *

     * @see #getModel

     * @beaninfo

     *       bound: true

     *       expert: true

     * description: The scrollbar's BoundedRangeModel.

     */

    public void setModel(BoundedRangeModel newModel) {

        Integer oldValue = null;

        BoundedRangeModel oldModel = model;

        if (model != null) {

            model.removeChangeListener(fwdAdjustmentEvents);

            oldValue = Integer.valueOf(model.getValue());

        }

        model = newModel;

        if (model != null) {

            model.addChangeListener(fwdAdjustmentEvents);

        }

        firePropertyChange("model", oldModel, model);

        if (accessibleContext != null) {

            accessibleContext.firePropertyChange(

                    AccessibleContext.ACCESSIBLE_VALUE_PROPERTY,

                    oldValue, new Integer(model.getValue()));

        }

    }

    /**

     * Returns the amount to change the scrollbar's value by,

     * given a unit up/down request.  A ScrollBarUI implementation

     * typically calls this method when the user clicks on a scrollbar

     * up/down arrow and uses the result to update the scrollbar's

     * value.   Subclasses my override this method to compute

     * a value, e.g. the change required to scroll up or down one

     * (variable height) line text or one row in a table.

     * <p>

     * The JScrollPane component creates scrollbars (by default)

     * that override this method and delegate to the viewports

     * Scrollable view, if it has one.  The Scrollable interface

     * provides a more specialized version of this method.

     * <p>

     * Some look and feels implement custom scrolling behavior

     * and ignore this property.

     *

     * @param direction is -1 or 1 for up/down respectively

     * @return the value of the unitIncrement property

     * @see #setUnitIncrement

     * @see #setValue

     * @see Scrollable#getScrollableUnitIncrement

     */

    public int getUnitIncrement(int direction) {

        return unitIncrement;

    }

    /**

     * Sets the unitIncrement property.

     * <p>

     * Note, that if the argument is equal to the value of Integer.MIN_VALUE,

     * the most look and feels will not provide the scrolling to the right/down.

     * <p>

     * Some look and feels implement custom scrolling behavior

     * and ignore this property.

     *

     * @see #getUnitIncrement

     * @beaninfo

     *   preferred: true

     *       bound: true

     * description: The scrollbar's unit increment.

     */

    public void setUnitIncrement(int unitIncrement) {

        int oldValue = this.unitIncrement;

        this.unitIncrement = unitIncrement;

        firePropertyChange("unitIncrement", oldValue, unitIncrement);

    }

    /**

     * Returns the amount to change the scrollbar's value by,

     * given a block (usually "page") up/down request.  A ScrollBarUI

     * implementation typically calls this method when the user clicks

     * above or below the scrollbar "knob" to change the value

     * up or down by large amount.  Subclasses my override this

     * method to compute a value, e.g. the change required to scroll

     * up or down one paragraph in a text document.

     * <p>

     * The JScrollPane component creates scrollbars (by default)

     * that override this method and delegate to the viewports

     * Scrollable view, if it has one.  The Scrollable interface

     * provides a more specialized version of this method.

     * <p>

     * Some look and feels implement custom scrolling behavior

     * and ignore this property.

     *

     * @param direction is -1 or 1 for up/down respectively

     * @return the value of the blockIncrement property

     * @see #setBlockIncrement

     * @see #setValue

     * @see Scrollable#getScrollableBlockIncrement

     */

    public int getBlockIncrement(int direction) {

        return blockIncrement;

    }

    /**

     * Sets the blockIncrement property.

     * <p>

     * Note, that if the argument is equal to the value of Integer.MIN_VALUE,

     * the most look and feels will not provide the scrolling to the right/down.

     * <p>

     * Some look and feels implement custom scrolling behavior

     * and ignore this property.

     *

     * @see #getBlockIncrement()

     * @beaninfo

     *   preferred: true

     *       bound: true

     * description: The scrollbar's block increment.

     */

    public void setBlockIncrement(int blockIncrement) {

        int oldValue = this.blockIncrement;

        this.blockIncrement = blockIncrement;

        firePropertyChange("blockIncrement", oldValue, blockIncrement);

    }

    /**

     * For backwards compatibility with java.awt.Scrollbar.

     * @see Adjustable#getUnitIncrement

     * @see #getUnitIncrement(int)

     */

    public int getUnitIncrement() {

        return unitIncrement;

    }

    /**

     * For backwards compatibility with java.awt.Scrollbar.

     * @see Adjustable#getBlockIncrement

     * @see #getBlockIncrement(int)

     */

    public int getBlockIncrement() {

        return blockIncrement;

    }

    /**

     * Returns the scrollbar's value.

     * @return the model's value property

     * @see #setValue

     */

    public int getValue() {

        return getModel().getValue();

    }

    /**

     * Sets the scrollbar's value.  This method just forwards the value

     * to the model.

     *

     * @see #getValue

     * @see BoundedRangeModel#setValue

     * @beaninfo

     *   preferred: true

     * description: The scrollbar's current value.

     */

    public void setValue(int value) {

        BoundedRangeModel m = getModel();

        int oldValue = m.getValue();

        m.setValue(value);

        if (accessibleContext != null) {

            accessibleContext.firePropertyChange(

                    AccessibleContext.ACCESSIBLE_VALUE_PROPERTY,

                    Integer.valueOf(oldValue),

                    Integer.valueOf(m.getValue()));

        }

    }

    /**

     * Returns the scrollbar's extent, aka its "visibleAmount".  In many

     * scrollbar look and feel implementations the size of the

     * scrollbar "knob" or "thumb" is proportional to the extent.

     *

     * @return the value of the model's extent property

     * @see #setVisibleAmount

     */

    public int getVisibleAmount() {

        return getModel().getExtent();

    }

    /**

     * Set the model's extent property.

     *

     * @see #getVisibleAmount

     * @see BoundedRangeModel#setExtent

     * @beaninfo

     *   preferred: true

     * description: The amount of the view that is currently visible.

     */

    public void setVisibleAmount(int extent) {

        getModel().setExtent(extent);

    }

    /**

     * Returns the minimum value supported by the scrollbar

     * (usually zero).

     *

     * @return the value of the model's minimum property

     * @see #setMinimum

     */

    public int getMinimum() {

        return getModel().getMinimum();

    }