scrollbar.java

《移动Agent技术》一书的所有章节源代码。

/*
 * @(#)Scrollbar.java	1.55 98/07/01
 *
 * Copyright 1995-1998 by Sun Microsystems, Inc.,
 * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
 * All rights reserved.
 * 
 * This software is the confidential and proprietary information
 * of Sun Microsystems, Inc. ("Confidential Information").  You
 * shall not disclose such Confidential Information and shall use
 * it only in accordance with the terms of the license agreement
 * you entered into with Sun.
 */
package java.awt;

import java.awt.peer.ScrollbarPeer;
import java.awt.event.*;
import java.io.ObjectOutputStream;
import java.io.ObjectInputStream;
import java.io.IOException;


/**
 * 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="images-awt/Scrollbar-1.gif"
 * 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" or "thumb" can represent the amount of text 
 * that is visible. Here is an example of a scroll bar that 
 * represents a range:
 * <p>
 * <img src="images-awt/Scrollbar-2.gif" 
 * ALIGN=center HSPACE=10 VSPACE=7> 
 * <p>
 * The value range represented by the bubble is the <em>visible</em> 
 * range of the scroll bar. 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, 64, 0, 255);
 * add(ranger);
 * </pre></blockquote><hr>
 * <p>
 * Note that the maximum value above, 255, is the maximum value for 
 * the scroll bar's bubble. The actual width of the 
 * scroll bar's track is 255&nbsp;+&nbsp;64. When the scroll bar
 * is set to its maximum value, the left side of the bubble
 * is at 255, and the right side is at 255&nbsp;+&nbsp;64.
 * <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&nbsp;1.0 event system is supported for backwards
 * compatibility, but its use with newer versions of JDK is 
 * discouraged. The fives types of adjustment event introduced
 * with JDK&nbsp;1.1 correspond to the five event types 
 * that are associated with scroll bars in previous JDK versions.
 * The following list gives the adjustment event type, 
 * and the corresponding JDK&nbsp;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>
 *
 * @version	1.55 07/01/98
 * @author 	Sami Shaio
 * @see         java.awt.event.AdjustmentEvent
 * @see         java.awt.event.AdjustmentListener
 * @since       JDK1.0
 */
public class Scrollbar extends Component implements Adjustable {
  
    /**
     * A constant that indicates a horizontal scroll bar.
     * @since     JDK1.0
     */
    public static final int	HORIZONTAL = 0;

    /**
     * A constant that indicates a vertical scroll bar.
     * @since     JDK1.0
     */
    public static final int	VERTICAL   = 1;

    /**
     * The value of the Scrollbar.
     */
    int	value;

    /**
     * The maximum value of the Scrollbar.
     */
    int	maximum;

    /**
     * The minimum value of the Scrollbar.
     */
    int	minimum;

    /**
     * The size of the visible portion of the Scrollbar.
     */
    int	visibleAmount;

    /**
     * The Scrollbar's orientation--being either horizontal or vertical.
     */
    int	orientation;

    /**
     * The amount by which the scrollbar value will change when going
     * up or down by a line.
     */
    int lineIncrement = 1;

    /**
     * The amount by which the scrollbar value will change when going
     * up or down by a page.
     */
    int pageIncrement = 10;

    transient AdjustmentListener adjustmentListener;

    private static final String base = "scrollbar";
    private static int nameCounter = 0;
    
    /*
     * JDK 1.1 serialVersionUID 
     */
    private static final long serialVersionUID = 8451667562882310543L;

    /**
     * Constructs a new vertical scroll bar.
     * @since   JDK1.0
     */
    public Scrollbar() {
	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.
     * @since       JDK1.0
     */
    public Scrollbar(int orientation) {
        this(orientation, 0, 10, 0, 100);
    }

    /**
     * Constructs a new scroll bar with the specified orientation, 
     * initial value, page size, 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>
     * If the specified maximum value is less than the minimum value, it 
     * is changed to be the same as the minimum value. If the initial 
     * value is lower than the minimum value, it is changed to be the 
     * minimum value; if it is greater than the maximum value, it is 
     * changed to be the maximum value. 
     * @param     orientation   indicates the orientation of the scroll bar.
     * @param     value     the initial value of the scroll bar.
     * @param     visible   the size of the scroll bar's bubble, representing
     *                      the visible portion; the scroll bar uses this 
                            value when paging up or down by a page.
     * @param     minimum   the minimum value of the scroll bar.
     * @param     maximum   the maximum value of the scroll bar.
     * @since     JDK1.0
     */
    public Scrollbar(int orientation, int value, int visible, int minimum, int maximum) {
	switch (orientation) {
	  case HORIZONTAL:
	  case VERTICAL:
	    this.orientation = orientation;
	    break;
	  default:
	    throw new IllegalArgumentException("illegal scrollbar orientation");
	}
	setValues(value, visible, minimum, maximum);
    }

    /**
     * Construct a name for this component.  Called by getName() when the
     * name is null.
     */
    String constructComponentName() {
        return base + nameCounter++;
    }

    /**
     * Creates the Scrollbar's peer.  The peer allows you to modify
     * the appearance of the Scrollbar without changing any of its
     * functionality.
     */

    public void addNotify() {
      synchronized (getTreeLock()) {
	  if (peer == null)
		peer = getToolkit().createScrollbar(this);
	super.addNotify();
      }
    }

    /**
     * Determines 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
     * @since     JDK1.0
     */
    public int getOrientation() {
	return orientation;
    }

    /**
     * Sets the orientation for this scroll bar. 
     * @param     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();
	    }
	}
    }

    /**
     * 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
     * @since       JDK1.0
     */
    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 minimum or 
     * greater than the current maximum, then one of those values
     * 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.
     * @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
     * @since       JDK1.0
     */
    public void setValue(int newValue) {
	/* Use setValues so that a consistent policy
    	 * relating minimum, maximum, and value is enforced.
    	 */
    	setValues(newValue, visibleAmount, minimum, maximum);
    }

    /**
     * Gets the minimum value of this scroll bar.
     * @return      the minimum value of this scroll bar.
     * @see         java.awt.Scrollbar#getValue
     * @see         java.awt.Scrollbar#getMaximum
     * @since       JDK1.0
     */
    public int getMinimum() {
	return minimum;
    }