Java > Open Source Codes > java > awt > Scrollbar


1 /*
2  * @(#)Scrollbar.java 1.108 04/05/18
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */
7 package java.awt;
8
9 import java.awt.peer.ScrollbarPeer;
10 import java.awt.event.*;
11 import java.util.EventListener ;
12 import java.io.ObjectOutputStream ;
13 import java.io.ObjectInputStream ;
14 import java.io.IOException ;
15 import javax.accessibility.*;
16
17
18 /**
19  * The <code>Scrollbar</code> class embodies a scroll bar, a
20  * familiar user-interface object. A scroll bar provides a
21  * convenient means for allowing a user to select from a
22  * range of values. The following three vertical
23  * scroll bars could be used as slider controls to pick
24  * the red, green, and blue components of a color:
25  * <p>
26  * <img SRC="doc-files/Scrollbar-1.gif" alt="Image shows 3 vertical sliders, side-by-side."
27  * ALIGN=center HSPACE=10 VSPACE=7>
28  * <p>
29  * Each scroll bar in this example could be created with
30  * code similar to the following:
31  * <p>
32  * <hr><blockquote><pre>
33  * redSlider=new Scrollbar(Scrollbar.VERTICAL, 0, 1, 0, 255);
34  * add(redSlider);
35  * </pre></blockquote><hr>
36  * <p>
37  * Alternatively, a scroll bar can represent a range of values. For
38  * example, if a scroll bar is used for scrolling through text, the
39  * width of the "bubble" (also called the "thumb" or "scroll box")
40  * can be used to represent the amount of text that is visible.
41  * Here is an example of a scroll bar that represents a range:
42  * <p>
43  * <img SRC="doc-files/Scrollbar-2.gif"
44  * alt="Image shows horizontal slider with starting range of 0 and ending range of 300. The slider thumb is labeled 60."
45  * ALIGN=center HSPACE=10 VSPACE=7>
46  * <p>
47  * The value range represented by the bubble in this example
48  * is the <em>visible amount</em>. The horizontal scroll bar
49  * in this example could be created with code like the following:
50  * <p>
51  * <hr><blockquote><pre>
52  * ranger = new Scrollbar(Scrollbar.HORIZONTAL, 0, 60, 0, 300);
53  * add(ranger);
54  * </pre></blockquote><hr>
55  * <p>
56  * Note that the actual maximum value of the scroll bar is the
57  * <code>maximum</code> minus the <code>visible amount</code>.
58  * In the previous example, because the <code>maximum</code> is
59  * 300 and the <code>visible amount</code> is 60, the actual maximum
60  * value is 240. The range of the scrollbar track is 0 - 300.
61  * The left side of the bubble indicates the value of the
62  * scroll bar.
63  * <p>
64  * Normally, the user changes the value of the scroll bar by
65  * making a gesture with the mouse. For example, the user can
66  * drag the scroll bar's bubble up and down, or click in the
67  * scroll bar's unit increment or block increment areas. Keyboard
68  * gestures can also be mapped to the scroll bar. By convention,
69  * the <b>Page&nbsp;Up</b> and <b>Page&nbsp;Down</b>
70  * keys are equivalent to clicking in the scroll bar's block
71  * increment and block decrement areas.
72  * <p>
73  * When the user changes the value of the scroll bar, the scroll bar
74  * receives an instance of <code>AdjustmentEvent</code>.
75  * The scroll bar processes this event, passing it along to
76  * any registered listeners.
77  * <p>
78  * Any object that wishes to be notified of changes to the
79  * scroll bar's value should implement
80  * <code>AdjustmentListener</code>, an interface defined in
81  * the package <code>java.awt.event</code>.
82  * Listeners can be added and removed dynamically by calling
83  * the methods <code>addAdjustmentListener</code> and
84  * <code>removeAdjustmentListener</code>.
85  * <p>
86  * The <code>AdjustmentEvent</code> class defines five types
87  * of adjustment event, listed here:
88  * <p>
89  * <ul>
90  * <li><code>AdjustmentEvent.TRACK</code> is sent out when the
91  * user drags the scroll bar's bubble.
92  * <li><code>AdjustmentEvent.UNIT_INCREMENT</code> is sent out
93  * when the user clicks in the left arrow of a horizontal scroll
94  * bar, or the top arrow of a vertical scroll bar, or makes the
95  * equivalent gesture from the keyboard.
96  * <li><code>AdjustmentEvent.UNIT_DECREMENT</code> is sent out
97  * when the user clicks in the right arrow of a horizontal scroll
98  * bar, or the bottom arrow of a vertical scroll bar, or makes the
99  * equivalent gesture from the keyboard.
100  * <li><code>AdjustmentEvent.BLOCK_INCREMENT</code> is sent out
101  * when the user clicks in the track, to the left of the bubble
102  * on a horizontal scroll bar, or above the bubble on a vertical
103  * scroll bar. By convention, the <b>Page&nbsp;Up</b>
104  * key is equivalent, if the user is using a keyboard that
105  * defines a <b>Page&nbsp;Up</b> key.
106  * <li><code>AdjustmentEvent.BLOCK_DECREMENT</code> is sent out
107  * when the user clicks in the track, to the right of the bubble
108  * on a horizontal scroll bar, or below the bubble on a vertical
109  * scroll bar. By convention, the <b>Page&nbsp;Down</b>
110  * key is equivalent, if the user is using a keyboard that
111  * defines a <b>Page&nbsp;Down</b> key.
112  * </ul>
113  * <p>
114  * The JDK&nbsp;1.0 event system is supported for backwards
115  * compatibility, but its use with newer versions of the platform is
116  * discouraged. The five types of adjustment events introduced
117  * with JDK&nbsp;1.1 correspond to the five event types
118  * that are associated with scroll bars in previous platform versions.
119  * The following list gives the adjustment event type,
120  * and the corresponding JDK&nbsp;1.0 event type it replaces.
121  * <p>
122  * <ul>
123  * <li><code>AdjustmentEvent.TRACK</code> replaces
124  * <code>Event.SCROLL_ABSOLUTE</code>
125  * <li><code>AdjustmentEvent.UNIT_INCREMENT</code> replaces
126  * <code>Event.SCROLL_LINE_UP</code>
127  * <li><code>AdjustmentEvent.UNIT_DECREMENT</code> replaces
128  * <code>Event.SCROLL_LINE_DOWN</code>
129  * <li><code>AdjustmentEvent.BLOCK_INCREMENT</code> replaces
130  * <code>Event.SCROLL_PAGE_UP</code>
131  * <li><code>AdjustmentEvent.BLOCK_DECREMENT</code> replaces
132  * <code>Event.SCROLL_PAGE_DOWN</code>
133  * </ul>
134  * <p>
135  * <b>Note</b>: We recommend using a <code>Scrollbar</code>
136  * for value selection only. If you want to implement
137  * a scrollable component inside a container, we recommend you use
138  * a {@link ScrollPane ScrollPane}. If you use a
139  * <code>Scrollbar</code> for this purpose, you are likely to
140  * encounter issues with painting, key handling, sizing and
141  * positioning.
142  *
143  * @version 1.108, 05/18/04
144  * @author Sami Shaio
145  * @see java.awt.event.AdjustmentEvent
146  * @see java.awt.event.AdjustmentListener
147  * @since JDK1.0
148  */
149 public class Scrollbar extends Component implements Adjustable , Accessible {
150
151     /**
152      * A constant that indicates a horizontal scroll bar.
153      */
154     public static final int HORIZONTAL = 0;
155
156     /**
157      * A constant that indicates a vertical scroll bar.
158      */
159     public static final int VERTICAL = 1;
160
161     /**
162      * The value of the <code>Scrollbar</code>.
163      * This property must be greater than or equal to <code>minimum</code>
164      * and less than or equal to
165      * <code>maximum - visibleAmount</code>
166      *
167      * @serial
168      * @see #getValue
169      * @see #setValue
170      */
171     int value;
172
173     /**
174      * The maximum value of the <code>Scrollbar</code>.
175      * This value must be greater than the <code>minimum</code>
176      * value.<br>
177      *
178      * @serial
179      * @see #getMaximum
180      * @see #setMaximum
181      */
182     int maximum;
183
184     /**
185      * The minimum value of the <code>Scrollbar</code>.
186      * This value must be less than the <code>maximum</code>
187      * value.<br>
188      *
189      * @serial
190      * @see #getMinimum
191      * @see #setMinimum
192      */
193     int minimum;
194
195     /**
196      * The size of the <code>Scrollbar</code>'s bubble.
197      * When a scroll bar is used to select a range of values,
198      * the visibleAmount represents the size of this range.
199      * This is visually indicated by the size of the bubble.
200      *
201      * @serial
202      * @see #getVisibleAmount
203      * @see #setVisibleAmount
204      */
205     int visibleAmount;
206
207     /**
208      * The <code>Scrollbar</code>'s orientation--being either horizontal
209      * or vertical.
210      * This value should be specified when the scrollbar is created.<BR>
211      * orientation can be either : <code>VERTICAL</code> or
212      * <code>HORIZONTAL</code> only.
213      *
214      * @serial
215      * @see #getOrientation
216      * @see #setOrientation
217      */
218     int orientation;
219
220     /**
221      * The amount by which the scrollbar value will change when going
222      * up or down by a line.
223      * This value must be greater than zero.
224      *
225      * @serial
226      * @see #getLineIncrement
227      * @see #setLineIncrement
228      */
229     int lineIncrement = 1;
230
231     /**
232      * The amount by which the scrollbar value will change when going
233      * up or down by a page.
234      * This value must be greater than zero.
235      *
236      * @serial
237      * @see #getPageIncrement
238      * @see #setPageIncrement
239      */
240     int pageIncrement = 10;
241
242     /**
243      * The adjusting status of the <code>Scrollbar</code>.
244      * True if the value is in the process of changing as a result of
245      * actions being taken by the user.
246      *
247      * @see #getValueIsAdjusting
248      * @see #setValueIsAdjusting
249      * @since 1.4
250      */
251     transient boolean isAdjusting;
252
253     transient AdjustmentListener adjustmentListener;
254
255     private static final String base = "scrollbar";
256     private static int nameCounter = 0;
257
258     /*
259      * JDK 1.1 serialVersionUID
260      */
261     private static final long serialVersionUID = 8451667562882310543L;
262
263     /**
264      * Initialize JNI field and method IDs.
265      */
266     private static native void initIDs();
267
268     static {
269         /* ensure that the necessary native libraries are loaded */
270         Toolkit.loadLibraries();
271         if (!GraphicsEnvironment.isHeadless()) {
272             initIDs();
273         }
274     }
275
276     /**
277      * Constructs a new vertical scroll bar.
278      * The default properties of the scroll bar are listed in
279      * the following table:
280      * <p> </p>
281      * <table border=1 summary="Scrollbar default properties">
282      * <tr>
283      * <th>Property</th>
284      * <th>Description</th>
285      * <th>Default Value</th>
286      * </tr>
287      * <tr>
288      * <td>orientation</td>
289      * <td>indicates whether the scroll bar is vertical
290      * <br>or horizontal</td>
291      * <td><code>Scrollbar.VERTICAL</code></td>
292      * </tr>
293      * <tr>
294      * <td>value</td>
295      * <td>value which controls the location
296      * <br>of the scroll bar's bubble</td>
297      * <td>0</td>
298      * </tr>
299      * <tr>
300      * <td>visible amount</td>
301      * <td>visible amount of the scroll bar's range,
302      * <br>typically represented by the size of the
303      * <br>scroll bar's bubble</td>
304      * <td>10</td>
305      * </tr>
306      * <tr>
307      * <td>minimum</td>
308      * <td>minimum value of the scroll bar</td>
309      * <td>0</td>
310      * </tr>
311      * <tr>
312      * <td>maximum</td>
313      * <td>maximum value of the scroll bar</td>
314      * <td>100</td>
315      * </tr>
316      * <tr>
317      * <td>unit increment</td>
318      * <td>amount the value changes when the
319      * <br>Line Up or Line Down key is pressed,
320      * <br>or when the end arrows of the scrollbar
321      * <br>are clicked </td>
322      * <td>1</td>
323      * </tr>
324      * <tr>
325      * <td>block increment</td>
326      * <td>amount the value changes when the
327      * <br>Page Up or Page Down key is pressed,
328      * <br>or when the scrollbar track is clicked
329      * <br>on either side of the bubble </td>
330      * <td>10</td>
331      * </tr>
332      * </table>
333      *
334      * @exception HeadlessException if GraphicsEnvironment.isHeadless()
335      * returns true.
336      * @see java.awt.GraphicsEnvironment#isHeadless
337      */
338     public Scrollbar() throws HeadlessException {
339     this(VERTICAL, 0, 10, 0, 100);
340     }
341
342     /**
343      * Constructs a new scroll bar with the specified orientation.
344      * <p>
345      * The <code>orientation</code> argument must take one of the two
346      * values <code>Scrollbar.HORIZONTAL</code>,
347      * or <code>Scrollbar.VERTICAL</code>,
348      * indicating a horizontal or vertical scroll bar, respectively.
349      *
350      * @param orientation indicates the orientation of the scroll bar
351      * @exception IllegalArgumentException when an illegal value for
352      * the <code>orientation</code> argument is supplied
353      * @exception HeadlessException if GraphicsEnvironment.isHeadless()
354      * returns true.
355      * @see java.awt.GraphicsEnvironment#isHeadless
356      */
357     public Scrollbar(int orientation) throws HeadlessException {
358         this(orientation, 0, 10, 0, 100);
359     }
360
361     /**
362      * Constructs a new scroll bar with the specified orientation,
363      * initial value, visible amount, and minimum and maximum values.
364      * <p>
365      * The <code>orientation</code> argument must take one of the two
366      * values <code>Scrollbar.HORIZONTAL</code>,
367      * or <code>Scrollbar.VERTICAL</code>,
368      * indicating a horizontal or vertical scroll bar, respectively.
369      * <p>
370      * The parameters supplied to this constructor are subject to the
371      * constraints described in {@link #setValues(int, int, int, int)}.
372      *
373      * @param orientation indicates the orientation of the scroll bar.
374      * @param value the initial value of the scroll bar
375      * @param visible the visible amount of the scroll bar, typically
376      * represented by the size of the bubble
377      * @param minimum the minimum value of the scroll bar
378      * @param maximum the maximum value of the scroll bar
379      * @exception IllegalArgumentException when an illegal value for
380      * the <code>orientation</code> argument is supplied
381      * @exception HeadlessException if GraphicsEnvironment.isHeadless()
382      * returns true.
383      * @see #setValues
384      * @see java.awt.GraphicsEnvironment#isHeadless
385      */
386     public Scrollbar(int orientation, int value, int visible, int minimum,
387         int maximum) throws HeadlessException {
388         GraphicsEnvironment.checkHeadless();
389     switch (orientation) {
390       case HORIZONTAL:
391       case VERTICAL:
392         this.orientation = orientation;
393         break;
394       default:
395         throw new IllegalArgumentException ("illegal scrollbar orientation");
396     }
397     setValues(value, visible, minimum, maximum);
398     }
399
400     /**
401      * Constructs a name for this component. Called by <code>getName</code>
402      * when the name is <code>null</code>.
403      */
404     String constructComponentName() {
405         synchronized (getClass()) {
406         return base + nameCounter++;
407     }
408     }
409
410     /**
411      * Creates the <code>Scrollbar</code>'s peer. The peer allows you to modify
412      * the appearance of the <code>Scrollbar</code> without changing any of its
413      * functionality.
414      */
415     public void addNotify() {
416         synchronized (getTreeLock()) {
417         if (peer == null)
418             peer = getToolkit().createScrollbar(this);
419         super.addNotify();
420     }
421     }
422
423     /**
424      * Returns the orientation of this scroll bar.
425      *
426      * @return the orientation of this scroll bar, either
427      * <code>Scrollbar.HORIZONTAL</code> or
428      * <code>Scrollbar.VERTICAL</code>
429      * @see java.awt.Scrollbar#setOrientation
430      */
431     public int getOrientation() {
432     return orientation;
433     }
434
435     /**
436      * Sets the orientation for this scroll bar.
437      *
438      * @param orientation the orientation of this scroll bar, either
439      * <code>Scrollbar.HORIZONTAL</code> or
440      * <code>Scrollbar.VERTICAL</code>
441      * @see java.awt.Scrollbar#getOrientation
442      * @exception IllegalArgumentException if the value supplied
443      * for <code>orientation</code> is not a
444      * legal value
445      * @since JDK1.1
446      */
447     public void setOrientation(int orientation) {
448         synchronized (getTreeLock()) {
449         if (orientation == this.orientation) {
450             return;
451         }
452         switch (orientation) {
453             case HORIZONTAL:
454             case VERTICAL:
455             this.orientation = orientation;
456             break;
457             default:
458             throw new IllegalArgumentException ("illegal scrollbar orientation");
459         }
460         /* Create a new peer with the specified orientation. */
461         if (peer != null) {
462         removeNotify();
463         addNotify();
464         invalidate();
465         }
466     }
467         if (accessibleContext != null) {
468             accessibleContext.firePropertyChange(
469                     AccessibleContext.ACCESSIBLE_STATE_PROPERTY,
470                     ((orientation == VERTICAL)
471                      ? AccessibleState.HORIZONTAL : AccessibleState.VERTICAL),
472                     ((orientation == VERTICAL)
473                      ? AccessibleState.VERTICAL : AccessibleState.HORIZONTAL));
474         }
475     }
476
477     /**
478      * Gets the current value of this scroll bar.
479      *
480      * @return the current value of this scroll bar
481      * @see java.awt.Scrollbar#getMinimum
482      * @see java.awt.Scrollbar#getMaximum
483      */
484     public int getValue() {
485     return value;
486     }
487
488     /**
489      * Sets the value of this scroll bar to the specified value.
490      * <p>
491      * If the value supplied is less than the current <code>minimum</code>
492      * or greater than the current <code>maximum - visibleAmount</code>,
493      * then either <code>minimum</code> or <code>maximum - visibleAmount</code>
494      * is substituted, as appropriate.
495      * <p>
496      * Normally, a program should change a scroll bar's
497      * value only by calling <code>setValues</code>.
498      * The <code>setValues</code> method simultaneously
499      * and synchronously sets the minimum, maximum, visible amount,
500      * and value properties of a scroll bar, so that they are
501      * mutually consistent.
502      * <p>
503      * Calling this method does not fire an
504      * <code>AdjustmentEvent</code>.
505      *
506      * @param newValue the new value of the scroll bar
507      * @see java.awt.Scrollbar#setValues
508      * @see java.awt.Scrollbar#getValue
509      * @see java.awt.Scrollbar#getMinimum
510      * @see java.awt.Scrollbar#getMaximum
511      */
512     public void setValue(int newValue) {
513         // Use setValues so that a consistent policy relating
514 // minimum, maximum, visible amount, and value is enforced.
515 setValues(newValue, visibleAmount, minimum, maximum);
516     }
517
518     /**
519      * Gets the minimum value of this scroll bar.
520      *
521      * @return the minimum value of this scroll bar
522      * @see java.awt.Scrollbar#getValue
523      * @see java.awt.Scrollbar#getMaximum
524      */
525     public int getMinimum() {
526     return minimum;
527     }
528
529     /**
530      * Sets the minimum value of this scroll bar.
531      * <p>
532      * When <code>setMinimum</code> is called, the minimum value
533      * is changed, and other values (including the maximum, the
534      * visible amount, and the current scroll bar value)
535      * are changed to be consistent with the new minimum.
536      * <p>
537      * Normally, a program should change a scroll bar's minimum
538      * value only by calling <code>setValues</code>.
539      * The <code>setValues</code> method simultaneously
540      * and synchronously sets the minimum, maximum, visible amount,
541      * and value properties of a scroll bar, so that they are
542      * mutually consistent.
543      * <p>
544      * Note that setting the minimum value to <code>Integer.MAX_VALUE</code>
545      * will result in the new minimum value being set to
546      * <code>Integer.MAX_VALUE - 1</code>.
547      *
548      * @param newMinimum the new minimum value for this scroll bar
549      * @see java.awt.Scrollbar#setValues
550      * @see java.awt.Scrollbar#setMaximum
551      * @since JDK1.1
552      */
553     public void setMinimum(int newMinimum) {
554         // No checks are necessary in this method since minimum is
555 // the first variable checked in the setValues function.
556
557         // Use setValues so that a consistent policy relating
558 // minimum, maximum, visible amount, and value is enforced.
559 setValues(value, visibleAmount, newMinimum, maximum);
560     }
561
562     /**
563      * Gets the maximum value of this scroll bar.
564      *
565      * @return the maximum value of this scroll bar
566      * @see java.awt.Scrollbar#getValue
567      * @see java.awt.Scrollbar#getMinimum
568      */
569     public int getMaximum() {
570     return maximum;
571     }
572
573     /**
574      * Sets the maximum value of this scroll bar.
575      * <p>
576      * When <code>setMaximum</code> is called, the maximum value
577      * is changed, and other values (including the minimum, the
578      * visible amount, and the current scroll bar value)
579      * are changed to be consistent with the new maximum.
580      * <p>
581      * Normally, a program should change a scroll bar's maximum
582      * value only by calling <code>setValues</code>.
583      * The <code>setValues</code> method simultaneously
584      * and synchronously sets the minimum, maximum, visible amount,
585      * and value properties of a scroll bar, so that they are
586      * mutually consistent.
587      * <p>
588      * Note that setting the maximum value to <code>Integer.MIN_VALUE</code>
589      * will result in the new maximum value being set to
590      * <code>Integer.MIN_VALUE + 1</code>.
591      *
592      * @param newMaximum the new maximum value
593      * for this scroll bar
594      * @see java.awt.Scrollbar#setValues
595      * @see java.awt.Scrollbar#setMinimum
596      * @since JDK1.1
597      */
598     public void setMaximum(int newMaximum) {
599         // minimum is checked first in setValues, so we need to
600 // enforce minimum and maximum checks here.
601 if (newMaximum == Integer.MIN_VALUE) {
602             newMaximum = Integer.MIN_VALUE + 1;
603         }
604
605         if (minimum >= newMaximum) {
606             minimum = newMaximum - 1;
607         }
608
609         // Use setValues so that a consistent policy relating
610 // minimum, maximum, visible amount, and value is enforced.
611 setValues(value, visibleAmount, minimum, newMaximum);
612     }
613
614     /**
615      * Gets the visible amount of this scroll bar.
616      * <p>
617      * When a scroll bar is used to select a range of values,
618      * the visible amount is used to represent the range of values
619      * that are currently visible. The size of the scroll bar's
620      * bubble (also called a thumb or scroll box), usually gives a
621      * visual representation of the relationship of the visible
622      * amount to the range of the scroll bar.
623      * <p>
624      * The scroll bar's bubble may not be displayed when it is not
625      * moveable (e.g. when it takes up the entire length of the
626      * scroll bar's track, or when the scroll bar is disabled).
627      * Whether the bubble is displayed or not will not affect
628      * the value returned by <code>getVisibleAmount</code>.
629      *
630      * @return the visible amount of this scroll bar
631      * @see java.awt.Scrollbar#setVisibleAmount
632      * @since JDK1.1
633      */
634     public int getVisibleAmount() {
635     return getVisible();
636     }
637
638     /**
639      * @deprecated As of JDK version 1.1,
640      * replaced by <code>getVisibleAmount()</code>.
641      */
642     @Deprecated
643     public int getVisible() {
644     return visibleAmount;
645     }
646
647     /**
648      * Sets the visible amount of this scroll bar.
649      * <p>
650      * When a scroll bar is used to select a range of values,
651      * the visible amount is used to represent the range of values
652      * that are currently visible. The size of the scroll bar's
653      * bubble (also called a thumb or scroll box), usually gives a
654      * visual representation of the relationship of the visible
655      * amount to the range of the scroll bar.
656      * <p>
657      * The scroll bar's bubble may not be displayed when it is not
658      * moveable (e.g. when it takes up the entire length of the
659      * scroll bar's track, or when the scroll bar is disabled).
660      * Whether the bubble is displayed or not will not affect
661      * the value returned by <code>getVisibleAmount</code>.
662      * <p>
663      * If the visible amount supplied is less than <code>one</code>
664      * or greater than the current <code>maximum - minimum</code>,
665      * then either <code>one</code> or <code>maximum - minimum</code>
666      * is substituted, as appropriate.
667      * <p>
668      * Normally, a program should change a scroll bar's
669      * value only by calling <code>setValues</code>.
670      * The <code>setValues</code> method simultaneously
671      * and synchronously sets the minimum, maximum, visible amount,
672      * and value properties of a scroll bar, so that they are
673      * mutually consistent.
674      *
675      * @param newAmount the new visible amount
676      * @see java.awt.Scrollbar#getVisibleAmount
677      * @see java.awt.Scrollbar#setValues
678      * @since JDK1.1
679      */
680     public void setVisibleAmount(int newAmount) {
681         // Use setValues so that a consistent policy relating
682 // minimum, maximum, visible amount, and value is enforced.
683 setValues(value, newAmount, minimum, maximum);
684     }
685
686     /**
687      * Sets the unit increment for this scroll bar.
688      * <p>
689      * The unit increment is the value that is added or subtracted
690      * when the user activates the unit increment area of the
691      * scroll bar, generally through a mouse or keyboard gesture
692      * that the scroll bar receives as an adjustment event.
693      * The unit increment must be greater than zero.
694      * Attepts to set the unit increment to a value lower than 1
695      * will result in a value of 1 being set.
696      *
697      * @param v the amount by which to increment or decrement
698      * the scroll bar's value
699      * @see java.awt.Scrollbar#getUnitIncrement
700      * @since JDK1.1
701      */
702     public void setUnitIncrement(int v) {
703     setLineIncrement(v);
704     }
705
706     /**
707      * @deprecated As of JDK version 1.1,
708      * replaced by <code>setUnitIncrement(int)</code>.
709      */
710     @Deprecated
711     public synchronized void setLineIncrement(int v) {
712         int tmp = (v < 1) ? 1 : v;
713
714         if (lineIncrement == tmp) {
715             return;
716         }
717         lineIncrement = tmp;
718
719         ScrollbarPeer peer = (ScrollbarPeer)this.peer;
720         if (peer != null) {
721             peer.setLineIncrement(lineIncrement);
722         }
723     }
724
725     /**
726      * Gets the unit increment for this scrollbar.
727      * <p>
728      * The unit increment is the value that is added or subtracted
729      * when the user activates the unit increment area of the
730      * scroll bar, generally through a mouse or keyboard gesture
731      * that the scroll bar receives as an adjustment event.
732      * The unit increment must be greater than zero.
733      *
734      * @return the unit increment of this scroll bar
735      * @see java.awt.Scrollbar#setUnitIncrement
736      * @since JDK1.1
737      */
738     public int getUnitIncrement() {
739     return getLineIncrement();
740     }
741
742     /**
743      * @deprecated As of JDK version 1.1,
744      * replaced by <code>getUnitIncrement()</code>.
745      */
746     @Deprecated
747     public int getLineIncrement() {
748     return lineIncrement;
749     }
750
751     /**
752      * Sets the block increment for this scroll bar.
753      * <p>
754      * The block increment is the value that is added or subtracted
755      * when the user activates the block increment area of the
756      * scroll bar, generally through a mouse or keyboard gesture
757      * that the scroll bar receives as an adjustment event.
758      * The block increment must be greater than zero.
759      * Attepts to set the block increment to a value lower than 1
760      * will result in a value of 1 being set.
761      *
762      * @param v the amount by which to increment or decrement
763      * the scroll bar's value
764      * @see java.awt.Scrollbar#getBlockIncrement
765      * @since JDK1.1
766      */
767     public void setBlockIncrement(int v) {
768     setPageIncrement(v);
769     }
770
771     /**
772      * @deprecated As of JDK version 1.1,
773      * replaced by <code>setBlockIncrement()</code>.
774      */
775     @Deprecated
776     public synchronized void setPageIncrement(int v) {
777         int tmp = (v < 1) ? 1 : v;
778
779         if (pageIncrement == tmp) {
780             return;
781         }
782         pageIncrement = tmp;
783
784         ScrollbarPeer peer = (ScrollbarPeer)this.peer;
785         if (peer != null) {
786             peer.setPageIncrement(pageIncrement);
787         }
788     }
789
790     /**
791      * Gets the block increment of this scroll bar.
792      * <p>
793      * The block increment is the value that is added or subtracted
794      * when the user activates the block increment area of the
795      * scroll bar, generally through a mouse or keyboard gesture
796      * that the scroll bar receives as an adjustment event.
797      * The block increment must be greater than zero.
798      *
799      * @return the block increment of this scroll bar
800      * @see java.awt.Scrollbar#setBlockIncrement
801      * @since JDK1.1
802      */
803     public int getBlockIncrement() {
804     return getPageIncrement();
805     }
806
807     /**
808      * @deprecated As of JDK version 1.1,
809      * replaced by <code>getBlockIncrement()</code>.
810      */
811     @Deprecated
812     public int getPageIncrement() {
813     return pageIncrement;
814     }
815
816     /**
817      * Sets the values of four properties for this scroll bar:
818      * <code>value</code>, <code>visibleAmount</code>,
819      * <code>minimum</code>, and <code>maximum</code>.
820      * If the values supplied for these properties are inconsistent
821      * or incorrect, they will be changed to ensure consistency.
822      * <p>
823      * This method simultaneously and synchronously sets the values
824      * of four scroll bar properties, assuring that the values of
825      * these properties are mutually consistent. It enforces the
826      * following constraints:
827      * <code>maximum</code> must be greater than <code>minimum</code>,
828      * <code>maximum - minimum</code> must not be greater
829      * than <code>Integer.MAX_VALUE</code>,
830      * <code>visibleAmount</code> must be greater than zero.
831      * <code>visibleAmount</code> must not be greater than
832      * <code>maximum - minimum</code>,
833      * <code>value</code> must not be less than <code>minimum</code>,
834      * and <code>value</code> must not be greater than
835      * <code>maximum - visibleAmount</code>
836      * <p>
837      * Calling this method does not fire an
838      * <code>AdjustmentEvent</code>.
839      *
840      * @param value is the position in the current window
841      * @param visible is the visible amount of the scroll bar
842      * @param minimum is the minimum value of the scroll bar
843      * @param maximum is the maximum value of the scroll bar
844      * @see #setMinimum
845      * @see #setMaximum
846      * @see #setVisibleAmount
847      * @see #setValue
848      */
849     public void setValues(int value, int visible, int minimum, int maximum) {
850         int oldValue;
851         synchronized (this) {
852             if (minimum == Integer.MAX_VALUE) {
853                 minimum = Integer.MAX_VALUE - 1;
854             }
855             if (maximum <= minimum) {
856                 maximum = minimum + 1;
857             }
858
859             long maxMinusMin = (long) maximum - (long) minimum;
860             if (maxMinusMin > Integer.MAX_VALUE) {
861                 maxMinusMin = Integer.MAX_VALUE;
862                 maximum = minimum + (int) maxMinusMin;
863             }
864             if (visible > (int) maxMinusMin) {
865                 visible = (int) maxMinusMin;
866             }
867             if (visible < 1) {
868                 visible = 1;
869             }
870
871             if (value < minimum) {
872                 value = minimum;
873             }
874             if (value > maximum - visible) {
875                 value = maximum - visible;
876             }
877
878             oldValue = this.value;
879             this.value = value;
880             this.visibleAmount = visible;
881             this.minimum = minimum;
882             this.maximum = maximum;
883             ScrollbarPeer peer = (ScrollbarPeer)this.peer;
884             if (peer != null) {
885                 peer.setValues(value, visibleAmount, minimum, maximum);
886             }
887         }
888
889         if ((oldValue != value) && (accessibleContext != null)) {
890             accessibleContext.firePropertyChange(
891                     AccessibleContext.ACCESSIBLE_VALUE_PROPERTY,
892                     new Integer (oldValue),
893                     new Integer (value));
894         }
895     }
896
897     /**
898      * Returns true if the value is in the process of changing as a
899      * result of actions being taken by the user.
900      *
901      * @return the value of the <code>valueIsAdjusting</code> property
902      * @see #setValueIsAdjusting
903      * @since 1.4
904      */
905     public boolean getValueIsAdjusting() {
906         return isAdjusting;
907     }
908
909     /**
910      * Sets the <code>valueIsAdjusting</code> property.
911      *
912      * @param b new adjustment-in-progress status
913      * @see #getValueIsAdjusting
914      * @since 1.4
915      */
916     public void setValueIsAdjusting(boolean b) {
917     boolean oldValue;
918
919     synchronized (this) {
920         oldValue = isAdjusting;
921         isAdjusting = b;
922     }
923
924     if ((oldValue != b) && (accessibleContext != null)) {
925             accessibleContext.firePropertyChange(
926                     AccessibleContext.ACCESSIBLE_STATE_PROPERTY,
927                     ((oldValue) ? AccessibleState.BUSY : null),
928                     ((b) ? AccessibleState.BUSY : null));
929     }
930     }
931
932
933
934     /**
935      * Adds the specified adjustment listener to receive instances of
936      * <code>AdjustmentEvent</code> from this scroll bar.
937      * If l is <code>null</code>, no exception is thrown and no
938      * action is performed.
939      *
940      * @param l the adjustment listener
941      * @see #removeAdjustmentListener
942      * @see #getAdjustmentListeners
943      * @see java.awt.event.AdjustmentEvent
944      * @see java.awt.event.AdjustmentListener
945      * @since JDK1.1
946      */
947     public synchronized void addAdjustmentListener(AdjustmentListener l) {
948     if (l == null) {
949         return;
950     }
951     adjustmentListener = AWTEventMulticaster.add(adjustmentListener, l);
952         newEventsOnly = true;
953     }
954
955     /**
956      * Removes the specified adjustment listener so that it no longer
957      * receives instances of <code>AdjustmentEvent</code> from this scroll bar.
958      * If l is <code>null</code>, no exception is thrown and no action
959      * is performed.
960      *
961      * @param l the adjustment listener
962      * @see #addAdjustmentListener
963      * @see #getAdjustmentListeners
964      * @see java.awt.event.AdjustmentEvent
965      * @see java.awt.event.AdjustmentListener
966      * @since JDK1.1
967      */
968     public synchronized void removeAdjustmentListener(AdjustmentListener l) {
969     if (l == null) {
970         return;
971     }
972     adjustmentListener = AWTEventMulticaster.remove(adjustmentListener, l);
973     }
974
975     /**
976      * Returns an array of all the adjustment listeners
977      * registered on this scrollbar.
978      *
979      * @return all of this scrollbar's <code>AdjustmentListener</code>s
980      * or an empty array if no adjustment
981      * listeners are currently registered
982      * @see #addAdjustmentListener
983      * @see #removeAdjustmentListener
984      * @see java.awt.event.AdjustmentEvent
985      * @see java.awt.event.AdjustmentListener
986      * @since 1.4
987      */
988     public synchronized AdjustmentListener[] getAdjustmentListeners() {
989         return (AdjustmentListener[])(getListeners(AdjustmentListener.class));
990     }
991
992     /**
993      * Returns an array of all the objects currently registered
994      * as <code><em>Foo</em>Listener</code>s
995      * upon this <code>Scrollbar</code>.
996      * <code><em>Foo</em>Listener</code>s are registered using the
997      * <code>add<em>Foo</em>Listener</code> method.
998      * <p>
999      * You can specify the <code>listenerType</code> argument
1000     * with a class literal, such as
1001     * <code><em>Foo</em>Listener.class</code>.
1002     * For example, you can query a
1003     * <code>Scrollbar</code> <code>c</code>
1004     * for its mouse listeners with the following code:
1005     *
1006     * <pre>MouseListener[] mls = (MouseListener[])(c.getListeners(MouseListener.class));</pre>
1007     *
1008     * If no such listeners exist, this method returns an empty array.
1009     *
1010     * @param listenerType the type of listeners requested; this parameter
1011     * should specify an interface that descends from
1012     * <code>java.util.EventListener</code>
1013     * @return an array of all objects registered as
1014     * <code><em>Foo</em>Listener</code>s on this component,
1015     * or an empty array if no such listeners have been added
1016     * @exception ClassCastException if <code>listenerType</code>
1017     * doesn't specify a class or interface that implements
1018     * <code>java.util.EventListener</code>
1019     *
1020     * @since 1.3
1021     */
1022    public <T extends EventListener > T[] getListeners(Class <T> listenerType) {
1023    EventListener l = null;
1024    if (listenerType == AdjustmentListener.class) {
1025        l = adjustmentListener;
1026    } else {
1027        return super.getListeners(listenerType);
1028    }
1029    return AWTEventMulticaster.getListeners(l, listenerType);
1030    }
1031
1032    // REMIND: remove when filtering is done at lower level
1033 boolean eventEnabled(AWTEvent e) {
1034        if (e.id == AdjustmentEvent.ADJUSTMENT_VALUE_CHANGED) {
1035            if ((eventMask & AWTEvent.ADJUSTMENT_EVENT_MASK) != 0 ||
1036                adjustmentListener != null) {
1037                return true;
1038            }
1039            return false;
1040        }
1041        return super.eventEnabled(e);
1042    }
1043
1044    /**
1045     * Processes events on this scroll bar. If the event is an
1046     * instance of <code>AdjustmentEvent</code>, it invokes the
1047     * <code>processAdjustmentEvent</code> method.
1048     * Otherwise, it invokes its superclass's
1049     * <code>processEvent</code> method.
1050     * <p>Note that if the event parameter is <code>null</code>
1051     * the behavior is unspecified and may result in an
1052     * exception.
1053     *
1054     * @param e the event
1055     * @see java.awt.event.AdjustmentEvent
1056     * @see java.awt.Scrollbar#processAdjustmentEvent
1057     * @since JDK1.1
1058     */
1059    protected void processEvent(AWTEvent e) {
1060        if (e instanceof AdjustmentEvent) {
1061            processAdjustmentEvent((AdjustmentEvent)e);
1062            return;
1063        }
1064    super.processEvent(e);
1065    }
1066
1067    /**
1068     * Processes adjustment events occurring on this
1069     * scrollbar by dispatching them to any registered
1070     * <code>AdjustmentListener</code> objects.
1071     * <p>
1072     * This method is not called unless adjustment events are
1073     * enabled for this component. Adjustment events are enabled
1074     * when one of the following occurs:
1075     * <p><ul>
1076     * <li>An <code>AdjustmentListener</code> object is registered
1077     * via <code>addAdjustmentListener</code>.
1078     * <li>Adjustment events are enabled via <code>enableEvents</code>.
1079     * </ul><p>
1080     * <p>Note that if the event parameter is <code>null</code>
1081     * the behavior is unspecified and may result in an
1082     * exception.
1083     *
1084     * @param e the adjustment event
1085     * @see java.awt.event.AdjustmentEvent
1086     * @see java.awt.event.AdjustmentListener
1087     * @see java.awt.Scrollbar#addAdjustmentListener
1088     * @see java.awt.Component#enableEvents
1089     * @since JDK1.1
1090     */
1091    protected void processAdjustmentEvent(AdjustmentEvent e) {
1092        AdjustmentListener listener = adjustmentListener;
1093        if (listener != null) {
1094            listener.adjustmentValueChanged(e);
1095        }
1096    }
1097
1098    /**
1099     * Returns a string representing the state of this <code>Scrollbar</code>.
1100     * This method is intended to be used only for debugging purposes, and the
1101     * content and format of the returned string may vary between
1102     * implementations. The returned string may be empty but may not be
1103     * <code>null</code>.
1104     *
1105     * @return the parameter string of this scroll bar
1106     */
1107    protected String paramString() {
1108    return super.paramString() +
1109        ",val=" + value +
1110        ",vis=" + visibleAmount +
1111        ",min=" + minimum +
1112        ",max=" + maximum +
1113        ((orientation == VERTICAL) ? ",vert" : ",horz") +
1114        ",isAdjusting=" + isAdjusting;
1115    }
1116
1117
1118    /* Serialization support.
1119     */
1120
1121    /**
1122     * The scroll bar's serialized Data Version.
1123     *
1124     * @serial
1125     */
1126    private int scrollbarSerializedDataVersion = 1;
1127
1128    /**
1129     * Writes default serializable fields to stream. Writes
1130     * a list of serializable <code>AdjustmentListeners</code>
1131     * as optional data. The non-serializable listeners are
1132     * detected and no attempt is made to serialize them.
1133     *
1134     * @param s the <code>ObjectOutputStream</code> to write
1135     * @serialData <code>null</code> terminated sequence of 0
1136     * or more pairs; the pair consists of a <code>String</code>
1137     * and an <code>Object</code>; the <code>String</code> indicates
1138     * the type of object and is one of the following:
1139     * <code>adjustmentListenerK</code> indicating an
1140     * <code>AdjustmentListener</code> object
1141     *
1142     * @see AWTEventMulticaster#save(ObjectOutputStream, String, EventListener)
1143     * @see java.awt.Component#adjustmentListenerK
1144     * @see #readObject(ObjectInputStream)
1145     */
1146    private void writeObject(ObjectOutputStream s)
1147      throws IOException
1148    {
1149      s.defaultWriteObject();
1150
1151      AWTEventMulticaster.save(s, adjustmentListenerK, adjustmentListener);
1152      s.writeObject(null);
1153    }
1154
1155    /**
1156     * Reads the <code>ObjectInputStream</code> and if
1157     * it isn't <code>null</code> adds a listener to
1158     * receive adjustment events fired by the
1159     * <code>Scrollbar</code>.
1160     * Unrecognized keys or values will be ignored.
1161     *
1162     * @param s the <code>ObjectInputStream</code> to read
1163     * @exception HeadlessException if
1164     * <code>GraphicsEnvironment.isHeadless</code> returns
1165     * <code>true</code>
1166     * @see java.awt.GraphicsEnvironment#isHeadless
1167     * @see #writeObject(ObjectOutputStream)
1168     */
1169    private void readObject(ObjectInputStream s)
1170      throws ClassNotFoundException , IOException , HeadlessException
1171    {
1172      GraphicsEnvironment.checkHeadless();
1173      s.defaultReadObject();
1174
1175      Object keyOrNull;
1176      while(null != (keyOrNull = s.readObject())) {
1177    String key = ((String )keyOrNull).intern();
1178
1179    if (adjustmentListenerK == key)
1180      addAdjustmentListener((AdjustmentListener)(s.readObject()));
1181
1182    else // skip value for unrecognized key
1183 s.readObject();
1184      }
1185    }
1186
1187
1188/////////////////
1189// Accessibility support
1190////////////////
1191
1192    /**
1193     * Gets the <code>AccessibleContext</code> associated with this
1194     * <code>Scrollbar</code>. For scrollbars, the
1195     * <code>AccessibleContext</code> takes the form of an
1196     * <code>AccessibleAWTScrollBar</code>. A new
1197     * <code>AccessibleAWTScrollBar</code> instance is created if necessary.
1198     *
1199     * @return an <code>AccessibleAWTScrollBar</code> that serves as the
1200     * <code>AccessibleContext</code> of this <code>ScrollBar</code>
1201     */
1202    public AccessibleContext getAccessibleContext() {
1203        if (accessibleContext == null) {
1204            accessibleContext = new AccessibleAWTScrollBar();
1205        }
1206        return accessibleContext;
1207    }
1208
1209    /**
1210     * This class implements accessibility support for the
1211     * <code>Scrollbar</code> class. It provides an implementation of
1212     * the Java Accessibility API appropriate to scrollbar
1213     * user-interface elements.
1214     */
1215    protected class AccessibleAWTScrollBar extends AccessibleAWTComponent
1216        implements AccessibleValue
1217    {
1218        /*
1219         * JDK 1.3 serialVersionUID
1220         */
1221        private static final long serialVersionUID = -344337268523697807L;
1222
1223        /**
1224         * Get the state set of this object.
1225         *
1226         * @return an instance of <code>AccessibleState</code>
1227         * containing the current state of the object
1228         * @see AccessibleState
1229         */
1230        public AccessibleStateSet getAccessibleStateSet() {
1231            AccessibleStateSet states = super.getAccessibleStateSet();
1232        if (getValueIsAdjusting()) {
1233                states.add(AccessibleState.BUSY);
1234        }
1235            if (getOrientation() == VERTICAL) {
1236                states.add(AccessibleState.VERTICAL);
1237            } else {
1238                states.add(AccessibleState.HORIZONTAL);
1239            }
1240            return states;
1241        }
1242
1243        /**
1244         * Get the role of this object.
1245         *
1246         * @return an instance of <code>AccessibleRole</code>
1247         * describing the role of the object
1248         */
1249        public AccessibleRole getAccessibleRole() {
1250            return AccessibleRole.SCROLL_BAR;
1251        }
1252
1253        /**
1254     * Get the <code>AccessibleValue</code> associated with this
1255     * object. In the implementation of the Java Accessibility
1256     * API for this class, return this object, which is
1257     * responsible for implementing the
1258     * <code>AccessibleValue</code> interface on behalf of itself.
1259     *
1260     * @return this object
1261         */
1262        public AccessibleValue getAccessibleValue() {
1263            return this;
1264        }
1265
1266        /**
1267         * Get the accessible value of this object.
1268         *
1269         * @return The current value of this object.
1270         */
1271        public Number getCurrentAccessibleValue() {
1272            return new Integer (getValue());
1273        }
1274
1275        /**
1276         * Set the value of this object as a Number.
1277         *
1278         * @return True if the value was set.
1279         */
1280        public boolean setCurrentAccessibleValue(Number n) {
1281            if (n instanceof Integer ) {
1282                setValue(n.intValue());
1283                return true;
1284            } else {
1285                return false;
1286            }
1287        }
1288
1289        /**
1290         * Get the minimum accessible value of this object.
1291         *
1292         * @return The minimum value of this object.
1293         */
1294        public Number getMinimumAccessibleValue() {
1295            return new Integer (getMinimum());
1296        }
1297
1298        /**
1299         * Get the maximum accessible value of this object.
1300         *
1301         * @return The maximum value of this object.
1302         */
1303        public Number getMaximumAccessibleValue() {
1304            return new Integer (getMaximum());
1305        }
1306
1307    } // AccessibleAWTScrollBar
1308
1309}
1310
1311

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags