/*

 * Copyright 1995-2006 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 java.awt;

import java.awt.peer.ScrollbarPeer;

import java.awt.event.*;

import java.util.EventListener;

import java.io.ObjectOutputStream;

import java.io.ObjectInputStream;

import java.io.IOException;

import javax.accessibility.*;

/**

 * The <code>Scrollbar</code> class embodies a scroll bar, a

 * familiar user-interface object. A scroll bar provides a

 * convenient means for allowing a user to select from a

 * range of values. The following three vertical

 * scroll bars could be used as slider controls to pick

 * the red, green, and blue components of a color:

 * <p>

 * <img src="doc-files/Scrollbar-1.gif" alt="Image shows 3 vertical sliders, side-by-side."

 * ALIGN=center HSPACE=10 VSPACE=7>

 * <p>

 * Each scroll bar in this example could be created with

 * code similar to the following:

 * <p>

 * <hr><blockquote><pre>

 * redSlider=new Scrollbar(Scrollbar.VERTICAL, 0, 1, 0, 255);

 * add(redSlider);

 * </pre></blockquote><hr>

 * <p>

 * Alternatively, a scroll bar can represent a range of values. For

 * example, if a scroll bar is used for scrolling through text, the

 * width of the "bubble" (also called the "thumb" or "scroll box")

 * can be used to represent the amount of text that is visible.

 * Here is an example of a scroll bar that represents a range:

 * <p>

 * <img src="doc-files/Scrollbar-2.gif"

 * alt="Image shows horizontal slider with starting range of 0 and ending range of 300. The slider thumb is labeled 60."

 * ALIGN=center HSPACE=10 VSPACE=7>

 * <p>

 * The value range represented by the bubble in this example

 * is the <em>visible amount</em>. The horizontal scroll bar

 * in this example could be created with code like the following:

 * <p>

 * <hr><blockquote><pre>

 * ranger = new Scrollbar(Scrollbar.HORIZONTAL, 0, 60, 0, 300);

 * add(ranger);

 * </pre></blockquote><hr>

 * <p>

 * Note that the actual maximum value of the scroll bar is the

 * <code>maximum</code> minus the <code>visible amount</code>.

 * In the previous example, because the <code>maximum</code> is

 * 300 and the <code>visible amount</code> is 60, the actual maximum

 * value is 240.  The range of the scrollbar track is 0 - 300.

 * The left side of the bubble indicates the value of the

 * scroll bar.

 * <p>

 * Normally, the user changes the value of the scroll bar by

 * making a gesture with the mouse. For example, the user can

 * drag the scroll bar's bubble up and down, or click in the

 * scroll bar's unit increment or block increment areas. Keyboard

 * gestures can also be mapped to the scroll bar. By convention,

 * the <b>Page&nbsp;Up</b> and <b>Page&nbsp;Down</b>

 * keys are equivalent to clicking in the scroll bar's block

 * increment and block decrement areas.

 * <p>

 * When the user changes the value of the scroll bar, the scroll bar

 * receives an instance of <code>AdjustmentEvent</code>.

 * The scroll bar processes this event, passing it along to

 * any registered listeners.

 * <p>

 * Any object that wishes to be notified of changes to the

 * scroll bar's value should implement

 * <code>AdjustmentListener</code>, an interface defined in

 * the package <code>java.awt.event</code>.

 * Listeners can be added and removed dynamically by calling

 * the methods <code>addAdjustmentListener</code> and

 * <code>removeAdjustmentListener</code>.

 * <p>

 * The <code>AdjustmentEvent</code> class defines five types

 * of adjustment event, listed here:

 * <p>

 * <ul>

 * <li><code>AdjustmentEvent.TRACK</code> is sent out when the

 * user drags the scroll bar's bubble.

 * <li><code>AdjustmentEvent.UNIT_INCREMENT</code> is sent out

 * when the user clicks in the left arrow of a horizontal scroll

 * bar, or the top arrow of a vertical scroll bar, or makes the

 * equivalent gesture from the keyboard.

 * <li><code>AdjustmentEvent.UNIT_DECREMENT</code> is sent out

 * when the user clicks in the right arrow of a horizontal scroll

 * bar, or the bottom arrow of a vertical scroll bar, or makes the

 * equivalent gesture from the keyboard.

 * <li><code>AdjustmentEvent.BLOCK_INCREMENT</code> is sent out

 * when the user clicks in the track, to the left of the bubble

 * on a horizontal scroll bar, or above the bubble on a vertical

 * scroll bar. By convention, the <b>Page&nbsp;Up</b>

 * key is equivalent, if the user is using a keyboard that

 * defines a <b>Page&nbsp;Up</b> key.

 * <li><code>AdjustmentEvent.BLOCK_DECREMENT</code> is sent out

 * when the user clicks in the track, to the right of the bubble

 * on a horizontal scroll bar, or below the bubble on a vertical

 * scroll bar. By convention, the <b>Page&nbsp;Down</b>

 * key is equivalent, if the user is using a keyboard that

 * defines a <b>Page&nbsp;Down</b> key.

 * </ul>

 * <p>

 * The JDK 1.0 event system is supported for backwards

 * compatibility, but its use with newer versions of the platform is

 * discouraged. The five types of adjustment events introduced

 * with JDK 1.1 correspond to the five event types

 * that are associated with scroll bars in previous platform versions.

 * The following list gives the adjustment event type,

 * and the corresponding JDK 1.0 event type it replaces.

 * <p>

 * <ul>

 * <li><code>AdjustmentEvent.TRACK</code> replaces

 * <code>Event.SCROLL_ABSOLUTE</code>

 * <li><code>AdjustmentEvent.UNIT_INCREMENT</code> replaces

 * <code>Event.SCROLL_LINE_UP</code>

 * <li><code>AdjustmentEvent.UNIT_DECREMENT</code> replaces

 * <code>Event.SCROLL_LINE_DOWN</code>

 * <li><code>AdjustmentEvent.BLOCK_INCREMENT</code> replaces

 * <code>Event.SCROLL_PAGE_UP</code>

 * <li><code>AdjustmentEvent.BLOCK_DECREMENT</code> replaces

 * <code>Event.SCROLL_PAGE_DOWN</code>

 * </ul>

 * <p>

 * <b>Note</b>: We recommend using a <code>Scrollbar</code>

 * for value selection only.  If you want to implement

 * a scrollable component inside a container, we recommend you use

 * a {@link ScrollPane ScrollPane}. If you use a

 * <code>Scrollbar</code> for this purpose, you are likely to

 * encounter issues with painting, key handling, sizing and

 * positioning.

 *

 * @author      Sami Shaio

 * @see         java.awt.event.AdjustmentEvent

 * @see         java.awt.event.AdjustmentListener

 * @since       JDK1.0

 */

public class Scrollbar extends Component implements Adjustable, Accessible {

    /**

     * A constant that indicates a horizontal scroll bar.

     */

    public static final int     HORIZONTAL = 0;

    /**

     * A constant that indicates a vertical scroll bar.

     */

    public static final int     VERTICAL   = 1;

    /**

     * The value of the <code>Scrollbar</code>.

     * This property must be greater than or equal to <code>minimum</code>

     * and less than or equal to

     * <code>maximum - visibleAmount</code>

     *

     * @serial

     * @see #getValue

     * @see #setValue

     */

    int value;

    /**

     * The maximum value of the <code>Scrollbar</code>.

     * This value must be greater than the <code>minimum</code>

     * value.<br>

     *

     * @serial

     * @see #getMaximum

     * @see #setMaximum

     */

    int maximum;

    /**

     * The minimum value of the <code>Scrollbar</code>.

     * This value must be less than the <code>maximum</code>

     * value.<br>

     *

     * @serial

     * @see #getMinimum

     * @see #setMinimum

     */

    int minimum;

    /**

     * The size of the <code>Scrollbar</code>'s bubble.

     * When a scroll bar is used to select a range of values,

     * the visibleAmount represents the size of this range.

     * This is visually indicated by the size of the bubble.

     *

     * @serial

     * @see #getVisibleAmount

     * @see #setVisibleAmount

     */

    int visibleAmount;

    /**

     * The <code>Scrollbar</code>'s orientation--being either horizontal

     * or vertical.

     * This value should be specified when the scrollbar is created.<BR>

     * orientation can be either : <code>VERTICAL</code> or

     * <code>HORIZONTAL</code> only.

     *

     * @serial

     * @see #getOrientation

     * @see #setOrientation

     */

    int orientation;

    /**

     * The amount by which the scrollbar value will change when going

     * up or down by a line.

     * This value must be greater than zero.

     *

     * @serial

     * @see #getLineIncrement

     * @see #setLineIncrement

     */

    int lineIncrement = 1;

    /**

     * The amount by which the scrollbar value will change when going

     * up or down by a page.

     * This value must be greater than zero.

     *

     * @serial

     * @see #getPageIncrement

     * @see #setPageIncrement

     */

    int pageIncrement = 10;

    /**

     * The adjusting status of the <code>Scrollbar</code>.

     * True if the value is in the process of changing as a result of

     * actions being taken by the user.

     *

     * @see #getValueIsAdjusting

     * @see #setValueIsAdjusting

     * @since 1.4

     */

    transient boolean isAdjusting;

    transient AdjustmentListener adjustmentListener;

    private static final String base = "scrollbar";

    private static int nameCounter = 0;

    /*

     * JDK 1.1 serialVersionUID

     */

    private static final long serialVersionUID = 8451667562882310543L;

    /**

     * Initialize JNI field and method IDs.

     */

    private static native void initIDs();

    static {

        /* ensure that the necessary native libraries are loaded */

        Toolkit.loadLibraries();

        if (!GraphicsEnvironment.isHeadless()) {

            initIDs();

        }

    }

    /**

     * Constructs a new vertical scroll bar.

     * The default properties of the scroll bar are listed in

     * the following table:

     * <p> </p>

     * <table border=1 summary="Scrollbar default properties">

     * <tr>

     *   <th>Property</th>

     *   <th>Description</th>

     *   <th>Default Value</th>

     * </tr>

     * <tr>

     *   <td>orientation</td>

     *   <td>indicates whether the scroll bar is vertical

     *   <br>or horizontal</td>

     *   <td><code>Scrollbar.VERTICAL</code></td>

     * </tr>

     * <tr>

     *   <td>value</td>

     *   <td>value which controls the location

     *   <br>of the scroll bar's bubble</td>

     *   <td>0</td>

     * </tr>

     * <tr>

     *   <td>visible amount</td>

     *   <td>visible amount of the scroll bar's range,

     *   <br>typically represented by the size of the

     *   <br>scroll bar's bubble</td>

     *   <td>10</td>

     * </tr>

     * <tr>

     *   <td>minimum</td>

     *   <td>minimum value of the scroll bar</td>

     *   <td>0</td>

     * </tr>

     * <tr>

     *   <td>maximum</td>

     *   <td>maximum value of the scroll bar</td>

     *   <td>100</td>

     * </tr>

     * <tr>

     *   <td>unit increment</td>

     *   <td>amount the value changes when the

     *   <br>Line Up or Line Down key is pressed,

     *   <br>or when the end arrows of the scrollbar

     *   <br>are clicked </td>

     *   <td>1</td>

     * </tr>

     * <tr>

     *   <td>block increment</td>

     *   <td>amount the value changes when the

     *   <br>Page Up or Page Down key is pressed,

     *   <br>or when the scrollbar track is clicked

     *   <br>on either side of the bubble </td>

     *   <td>10</td>

     * </tr>

     * </table>

     *

     * @exception HeadlessException if GraphicsEnvironment.isHeadless()

     * returns true.

     * @see java.awt.GraphicsEnvironment#isHeadless

     */

    public Scrollbar() throws HeadlessException {

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

    }

    /**

     * Constructs a new scroll bar with the specified orientation.

     * <p>

     * The <code>orientation</code> argument must take one of the two

     * values <code>Scrollbar.HORIZONTAL</code>,

     * or <code>Scrollbar.VERTICAL</code>,

     * indicating a horizontal or vertical scroll bar, respectively.

     *

     * @param       orientation   indicates the orientation of the scroll bar

     * @exception   IllegalArgumentException    when an illegal value for

     *                    the <code>orientation</code> argument is supplied

     * @exception HeadlessException if GraphicsEnvironment.isHeadless()

     * returns true.

     * @see java.awt.GraphicsEnvironment#isHeadless

     */

    public Scrollbar(int orientation) throws HeadlessException {

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

    }

    /**

     * Constructs a new scroll bar with the specified orientation,

     * initial value, visible amount, and minimum and maximum values.

     * <p>

     * The <code>orientation</code> argument must take one of the two

     * values <code>Scrollbar.HORIZONTAL</code>,

     * or <code>Scrollbar.VERTICAL</code>,

     * indicating a horizontal or vertical scroll bar, respectively.

     * <p>

     * The parameters supplied to this constructor are subject to the

     * constraints described in {@link #setValues(int, int, int, int)}.

     *

     * @param     orientation   indicates the orientation of the scroll bar.

     * @param     value     the initial value of the scroll bar

     * @param     visible   the visible amount of the scroll bar, typically

     *                      represented by the size of the bubble

     * @param     minimum   the minimum value of the scroll bar

     * @param     maximum   the maximum value of the scroll bar

     * @exception IllegalArgumentException    when an illegal value for

     *                    the <code>orientation</code> argument is supplied

     * @exception HeadlessException if GraphicsEnvironment.isHeadless()

     * returns true.

     * @see #setValues

     * @see java.awt.GraphicsEnvironment#isHeadless

     */

    public Scrollbar(int orientation, int value, int visible, int minimum,

        int maximum) throws HeadlessException {

        GraphicsEnvironment.checkHeadless();

        switch (orientation) {

          case HORIZONTAL:

          case VERTICAL:

            this.orientation = orientation;

            break;

          default:

            throw new IllegalArgumentException("illegal scrollbar orientation");

        }

        setValues(value, visible, minimum, maximum);

    }

    /**

     * Constructs a name for this component.  Called by <code>getName</code>

     * when the name is <code>null</code>.

     */

    String constructComponentName() {

        synchronized (Scrollbar.class) {

            return base + nameCounter++;

        }

    }

    /**

     * Creates the <code>Scrollbar</code>'s peer.  The peer allows you to modify

     * the appearance of the <code>Scrollbar</code> without changing any of its

     * functionality.

     */

    public void addNotify() {

        synchronized (getTreeLock()) {

            if (peer == null)

                peer = getToolkit().createScrollbar(this);

            super.addNotify();

        }

    }

    /**

     * Returns the orientation of this scroll bar.

     *

     * @return    the orientation of this scroll bar, either

     *               <code>Scrollbar.HORIZONTAL</code> or

     *               <code>Scrollbar.VERTICAL</code>

     * @see       java.awt.Scrollbar#setOrientation

     */

    public int getOrientation() {

        return orientation;

    }

    /**

     * Sets the orientation for this scroll bar.

     *

     * @param orientation  the orientation of this scroll bar, either

     *               <code>Scrollbar.HORIZONTAL</code> or

     *               <code>Scrollbar.VERTICAL</code>

     * @see       java.awt.Scrollbar#getOrientation

     * @exception   IllegalArgumentException  if the value supplied

     *                   for <code>orientation</code> is not a

     *                   legal value

     * @since     JDK1.1

     */

    public void setOrientation(int orientation) {

        synchronized (getTreeLock()) {

            if (orientation == this.orientation) {

                return;

            }

            switch (orientation) {

                case HORIZONTAL:

                case VERTICAL:

                    this.orientation = orientation;

                    break;

                default:

                    throw new IllegalArgumentException("illegal scrollbar orientation");

            }

            /* Create a new peer with the specified orientation. */

            if (peer != null) {

                removeNotify();

                addNotify();

                invalidate();

            }

        }

        if (accessibleContext != null) {

            accessibleContext.firePropertyChange(

                    AccessibleContext.ACCESSIBLE_STATE_PROPERTY,

                    ((orientation == VERTICAL)

                     ? AccessibleState.HORIZONTAL : AccessibleState.VERTICAL),

                    ((orientation == VERTICAL)

                     ? AccessibleState.VERTICAL : AccessibleState.HORIZONTAL));

        }

    }

    /**

     * Gets the current value of this scroll bar.

     *

     * @return      the current value of this scroll bar

     * @see         java.awt.Scrollbar#getMinimum

     * @see         java.awt.Scrollbar#getMaximum

     */

    public int getValue() {

        return value;

    }

    /**

     * Sets the value of this scroll bar to the specified value.

     * <p>

     * If the value supplied is less than the current <code>minimum</code>

     * or greater than the current <code>maximum - visibleAmount</code>,

     * then either <code>minimum</code> or <code>maximum - visibleAmount</code>

     * is substituted, as appropriate.

     * <p>

     * Normally, a program should change a scroll bar's

     * value only by calling <code>setValues</code>.

     * The <code>setValues</code> method simultaneously

     * and synchronously sets the minimum, maximum, visible amount,

     * and value properties of a scroll bar, so that they are

     * mutually consistent.

     * <p>

     * Calling this method does not fire an

     * <code>AdjustmentEvent</code>.

     *

     * @param       newValue   the new value of the scroll bar

     * @see         java.awt.Scrollbar#setValues

     * @see         java.awt.Scrollbar#getValue

     * @see         java.awt.Scrollbar#getMinimum

     * @see         java.awt.Scrollbar#getMaximum

     */