/*

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

 * <p>

 * Each scroll bar in this example could be created with

 * code similar to the following:

 *

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

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

 *

 * <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} minus the {@code visible amount}.

 * In the previous example, because the {@code maximum} is

 * 300 and the {@code visible amount} 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}.

 * 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}, an interface defined in

 * the package {@code java.awt.event}.

 * Listeners can be added and removed dynamically by calling

 * the methods {@code addAdjustmentListener} and

 * {@code removeAdjustmentListener}.

 * <p>

 * The {@code AdjustmentEvent} class defines five types

 * of adjustment event, listed here:

 *

 * <ul>

 * <li>{@code AdjustmentEvent.TRACK} is sent out when the

 * user drags the scroll bar's bubble.

 * <li>{@code AdjustmentEvent.UNIT_INCREMENT} 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} 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} 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} 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.

 *

 * <ul>

 * <li>{@code AdjustmentEvent.TRACK} replaces

 * {@code Event.SCROLL_ABSOLUTE}

 * <li>{@code AdjustmentEvent.UNIT_INCREMENT} replaces

 * {@code Event.SCROLL_LINE_UP}

 * <li>{@code AdjustmentEvent.UNIT_DECREMENT} replaces

 * {@code Event.SCROLL_LINE_DOWN}

 * <li>{@code AdjustmentEvent.BLOCK_INCREMENT} replaces

 * {@code Event.SCROLL_PAGE_UP}

 * <li>{@code AdjustmentEvent.BLOCK_DECREMENT} replaces

 * {@code Event.SCROLL_PAGE_DOWN}

 * </ul>

 * <p>

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

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

     * This property must be greater than or equal to {@code minimum}

     * and less than or equal to

     * {@code maximum - visibleAmount}

     *

     * @serial

     * @see #getValue

     * @see #setValue

     */

    int value;

    /**

     * The maximum value of the {@code Scrollbar}.

     * This value must be greater than the {@code minimum}

     * value.<br>

     *

     * @serial

     * @see #getMaximum

     * @see #setMaximum

     */

    int maximum;

    /**

     * The minimum value of the {@code Scrollbar}.

     * This value must be less than the {@code maximum}

     * value.<br>

     *

     * @serial

     * @see #getMinimum

     * @see #setMinimum

     */

    int minimum;

    /**

     * The size of the {@code Scrollbar}'s bubble.

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

     * the visibleAmount represents the size of this range.

     * Depending on platform, this may be visually indicated

     * by the size of the bubble.

     *

     * @serial

     * @see #getVisibleAmount

     * @see #setVisibleAmount

     */

    int visibleAmount;

    /**

     * The {@code Scrollbar}'s orientation--being either horizontal

     * or vertical.

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

     * orientation can be either : {@code VERTICAL} or

     * {@code HORIZONTAL} 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}.

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

     *

     * <table class="striped">

     * <caption>Scrollbar default properties</caption>

     * <thead>

     *   <tr>

     *     <th scope="col">Property

     *     <th scope="col">Description

     *     <th scope="col">Default Value

     * </thead>

     * <tbody>

     *   <tr>

     *     <th scope="row">orientation

     *     <td>indicates whether the scroll bar is vertical or horizontal

     *     <td>{@code Scrollbar.VERTICAL}

     *   <tr>

     *     <th scope="row">value

     *     <td>value which controls the location of the scroll bar's bubble

     *     <td>0

     *   <tr>

     *     <th scope="row">visible amount

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

     *     by the size of the scroll bar's bubble

     *     <td>10

     *   <tr>

     *     <th scope="row">minimum

     *     <td>minimum value of the scroll bar

     *     <td>0

     *   <tr>

     *     <th scope="row">maximum

     *     <td>maximum value of the scroll bar

     *     <td>100

     *   <tr>

     *     <th scope="row">unit increment

     *     <td>amount the value changes when the Line Up or Line Down key is

     *     pressed, or when the end arrows of the scrollbar are clicked

     *     <td>1

     *   <tr>

     *     <th scope="row">block increment

     *     <td>amount the value changes when the Page Up or Page Down key is

     *     pressed, or when the scrollbar track is clicked<br>on either side of

     *     the bubble

     *     <td>10

     * </tbody>

     * </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} argument must take one of the two

     * values {@code Scrollbar.HORIZONTAL},

     * or {@code Scrollbar.VERTICAL},

     * 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} 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} argument must take one of the two

     * values {@code Scrollbar.HORIZONTAL},

     * or {@code Scrollbar.VERTICAL},

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

     * when the name is {@code null}.

     */

    String constructComponentName() {

        synchronized (Scrollbar.class) {

            return base + nameCounter++;

        }

    }

    /**

     * Creates the {@code Scrollbar}'s peer.  The peer allows you to modify

     * the appearance of the {@code Scrollbar} without changing any of its

     * functionality.

     */

    public void addNotify() {

        synchronized (getTreeLock()) {

            if (peer == null)

                peer = getComponentFactory().createScrollbar(this);

            super.addNotify();

        }

    }

    /**

     * Returns the orientation of this scroll bar.

     *

     * @return    the orientation of this scroll bar, either

     *               {@code Scrollbar.HORIZONTAL} or

     *               {@code Scrollbar.VERTICAL}

     * @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} or

     *               {@code Scrollbar.VERTICAL}

     * @see       java.awt.Scrollbar#getOrientation

     * @exception   IllegalArgumentException  if the value supplied

     *                   for {@code orientation} is not a

     *                   legal value

     * @since     1.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}

     * or greater than the current {@code maximum - visibleAmount},

     * then either {@code minimum} or {@code maximum - visibleAmount}

     * is substituted, as appropriate.

     * <p>

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

     * value only by calling {@code setValues}.

     * The {@code setValues} 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}.

     *