ScrollPaneAdjustable


1   /*
2    * @(#)ScrollPaneAdjustable.java    1.9 03/12/19
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.event.AdjustmentEvent  ;
10  import java.awt.event.AdjustmentListener  ;
11  import java.awt.peer.ScrollPanePeer;
12  import java.io.Serializable  ;
13  
14  
15  /**
16   * This class represents the state of a horizontal or vertical
17   * scrollbar of a <code>ScrollPane</code>.  Objects of this class are
18   * returned by <code>ScrollPane</code> methods.
19   *
20   * @version     1.9 12/19/03
21   * @since   1.4
22   */
23  public class ScrollPaneAdjustable implements Adjustable  , Serializable   {
24  
25      /**
26       * The <code>ScrollPane</code> this object is a scrollbar of.
27       * @serial
28       */
29      private ScrollPane   sp;
30  
31      /**
32       * Orientation of this scrollbar.
33       * 
34       * @serial
35       * @see #getOrientation
36       * @see java.awt.Adjustable#HORIZONTAL
37       * @see java.awt.Adjustable#VERTICAL
38       */
39      private int orientation;
40  
41      /**
42       * The value of this scrollbar.
43       * <code>value</code> should be greater than <code>minimum</code>
44       * and less than <code>maximum</code>
45       * 
46       * @serial
47       * @see #getValue
48       * @see #setValue
49       */
50      private int value;
51  
52      /**
53       * The minimum value of this scrollbar.
54       * This value can only be set by the <code>ScrollPane</code>.
55       * <p>
56       * <strong>ATTN:</strong> In current implementation
57       * <code>minimum</code> is always <code>0</code>.  This field can
58       * only be altered via <code>setSpan</code> method and
59       * <code>ScrollPane</code> always calls that method with
60       * <code>0</code> for the minimum.  <code>getMinimum</code> method
61       * always returns <code>0</code> without checking this field.
62       * 
63       * @serial
64       * @see #getMinimum
65       * @see #setSpan(int, int, int)
66       */
67      private int minimum;
68  
69      /**
70       * The maximum value of this scrollbar.
71       * This value can only be set by the <code>ScrollPane</code>.
72       * 
73       * @serial
74       * @see #getMaximum
75       * @see #setSpan(int, int, int)
76       */
77      private int maximum;
78  
79      /**
80       * The size of the visible portion of this scrollbar.
81       * This value can only be set by the <code>ScrollPane</code>.
82       * 
83       * @serial
84       * @see #getVisibleAmount
85       * @see #setSpan(int, int, int)
86       */
87      private int visibleAmount;
88  
89      /**
90       * The adjusting status of the <code>Scrollbar</code>.
91       * True if the value is in the process of changing as a result of
92       * actions being taken by the user.
93       *
94       * @see #getValueIsAdjusting
95       * @see #setValueIsAdjusting
96       * @since 1.4
97       */
98      private transient boolean isAdjusting;
99  
100     /**
101      * The amount by which the scrollbar value will change when going
102      * up or down by a line.
103      * This value should be a non negative integer.
104      *
105      * @serial
106      * @see #getUnitIncrement
107      * @see #setUnitIncrement
108      */
109     private int unitIncrement  = 1;
110 
111     /**
112      * The amount by which the scrollbar value will change when going
113      * up or down by a page.
114      * This value should be a non negative integer.
115      *
116      * @serial
117      * @see #getBlockIncrement
118      * @see #setBlockIncrement
119      */
120     private int blockIncrement = 1;
121 
122     private AdjustmentListener   adjustmentListener;
123 
124     /**
125      * Error message for <code>AWTError</code> reported when one of
126      * the public but unsupported methods is called.
127      */
128     private static final String   SCROLLPANE_ONLY =
129         "Can be set by scrollpane only";
130 
131 
132     /**
133      * Initialize JNI field and method ids.
134      */
135     private static native void initIDs();
136 
137     static {
138         Toolkit.loadLibraries();
139         if (!GraphicsEnvironment.isHeadless()) {
140             initIDs();
141         }
142     }
143 
144     /**
145      * JDK 1.1 serialVersionUID.
146      */
147     private static final long serialVersionUID = -3359745691033257079L;
148 
149 
150     /**
151      * Constructs a new object to represent specified scrollabar
152      * of the specified <code>ScrollPane</code>.
153      * Only ScrollPane creates instances of this class.
154      * @param sp           <code>ScrollPane</code>
155      * @param l            <code>AdjustmentListener</code> to add upon creation.
156      * @param orientation  specifies which scrollbar this object represents,
157      *                     can be either  <code>Adjustable.HORIZONTAL</code>
158      *                     or <code>Adjustable.VERTICAL</code>.
159      */
160     ScrollPaneAdjustable(ScrollPane   sp, AdjustmentListener   l, int orientation) {
161         this.sp = sp;
162         this.orientation = orientation;
163     addAdjustmentListener(l);
164     }
165 
166     /**
167      * This is called by the scrollpane itself to update the
168      * <code>minimum</code>, <code>maximum</code> and
169      * <code>visible</code> values.  The scrollpane is the only one
170      * that should be changing these since it is the source of these
171      * values.
172      */
173     void setSpan(int min, int max, int visible) {
174     // adjust the values to be reasonable
175     minimum = min;
176     maximum = Math.max(max, minimum + 1);
177     visibleAmount = Math.min(visible, maximum - minimum);
178     visibleAmount = Math.max(visibleAmount, 1);
179         blockIncrement = Math.max((int)(visible * .90), 1);
180     setValue(value);
181     }
182 
183     /**
184      * Returns the orientation of this scrollbar.
185      * @return    the orientation of this scrollbar, either
186      *            <code>Adjustable.HORIZONTAL</code> or
187      *            <code>Adjustable.VERTICAL</code>
188      */
189     public int getOrientation() {
190         return orientation;
191     }
192 
193     /**
194      * This method should <strong>NOT</strong> be called by user code.
195      * This method is public for this class to properly implement
196      * <code>Adjustable</code> interface.
197      *
198      * @throws <code>AWTError</code>  Always throws an error when called.
199      */
200     public void setMinimum(int min) {
201     throw new AWTError  (SCROLLPANE_ONLY);
202     }
203 
204     public int getMinimum() {
205     // XXX: This relies on setSpan always being called with 0 for
206     // the minimum (which is currently true).
207         return 0;
208     }
209 
210     /**
211      * This method should <strong>NOT</strong> be called by user code.
212      * This method is public for this class to properly implement
213      * <code>Adjustable</code> interface.
214      *
215      * @throws <code>AWTError</code>  Always throws an error when called.
216      */
217     public void setMaximum(int max) {
218     throw new AWTError  (SCROLLPANE_ONLY);
219     }
220 
221     public int getMaximum() {
222         return maximum;
223     }
224 
225     public synchronized void setUnitIncrement(int u) {
226     if (u != unitIncrement) {
227         unitIncrement = u;
228         if (sp.peer != null) {
229         ScrollPanePeer peer = (ScrollPanePeer) sp.peer;
230         peer.setUnitIncrement(this, u);
231         }
232     }
233     }
234 
235     public int getUnitIncrement() {
236         return unitIncrement;
237     }
238 
239     public synchronized void setBlockIncrement(int b) {
240         blockIncrement = b;
241     }
242 
243     public int getBlockIncrement() {
244         return blockIncrement;
245     }
246 
247     /**
248      * This method should <strong>NOT</strong> be called by user code.
249      * This method is public for this class to properly implement
250      * <code>Adjustable</code> interface.
251      *
252      * @throws <code>AWTError</code>  Always throws an error when called.
253      */
254     public void setVisibleAmount(int v) {
255     throw new AWTError  (SCROLLPANE_ONLY);
256     }
257 
258     public int getVisibleAmount() {
259         return visibleAmount;
260     }
261 
262 
263     /**
264      * Sets the <code>valueIsAdjusting</code> property.
265      * 
266      * @param b new adjustment-in-progress status
267      * @see #getValueIsAdjusting
268      * @since 1.4
269      */
270     public void setValueIsAdjusting(boolean b) {
271     if (isAdjusting != b) {
272         isAdjusting = b;
273         AdjustmentEvent   e =
274         new AdjustmentEvent  (this,
275                 AdjustmentEvent.ADJUSTMENT_VALUE_CHANGED,
276             AdjustmentEvent.TRACK, value, b);
277         adjustmentListener.adjustmentValueChanged(e);
278     }
279     }
280 
281     /**
282      * Returns true if the value is in the process of changing as a
283      * result of actions being taken by the user.
284      *
285      * @return the value of the <code>valueIsAdjusting</code> property
286      * @see #setValueIsAdjusting
287      */
288     public boolean getValueIsAdjusting() {
289     return isAdjusting;
290     }
291 
292     /**
293      * Sets the value of this scrollbar to the specified value.
294      * <p>
295      * If the value supplied is less than the current minimum or
296      * greater than the current maximum, then one of those values is
297      * substituted, as appropriate.
298      *
299      * @param v the new value of the scrollbar
300      */
301     public void setValue(int v) {
302         setTypedValue(v, AdjustmentEvent.TRACK);
303     }
304 
305     /**
306      * Sets the value of this scrollbar to the specified value.
307      * <p>
308      * If the value supplied is less than the current minimum or
309      * greater than the current maximum, then one of those values is
310      * substituted, as appropriate. Also, creates and dispatches
311      * the AdjustementEvent with specified type and value.
312      *
313      * @param v the new value of the scrollbar
314      * @param type the type of the scrolling operation occured
315      */
316     private void setTypedValue(int v, int type) {
317         v = Math.max(v, minimum);
318         v = Math.min(v, maximum - visibleAmount);
319 
320         if (v != value) {
321             value = v;
322             // Synchronously notify the listeners so that they are
323             // guaranteed to be up-to-date with the Adjustable before
324             // it is mutated again.
325             AdjustmentEvent   e =
326                 new AdjustmentEvent  (this,
327                         AdjustmentEvent.ADJUSTMENT_VALUE_CHANGED,
328                         type, value, isAdjusting);
329             adjustmentListener.adjustmentValueChanged(e);
330         }
331     }
332 
333     public int getValue() {
334         return value;
335     }
336 
337     /**
338      * Adds the specified adjustment listener to receive adjustment
339      * events from this <code>ScrollPaneAdjustable</code>.
340      * If <code>l</code> is <code>null</code>, no exception is thrown
341      * and no action is performed.
342      *
343      * @param    l   the adjustment listener.
344      * @see      #removeAdjustmentListener
345      * @see      #getAdjustmentListeners
346      * @see      java.awt.event.AdjustmentListener
347      * @see      java.awt.event.AdjustmentEvent
348      */
349     public synchronized void addAdjustmentListener(AdjustmentListener   l) {
350     if (l == null) {
351         return;
352     }
353     adjustmentListener = AWTEventMulticaster.add(adjustmentListener, l);
354     }
355 
356     /**
357      * Removes the specified adjustment listener so that it no longer
358      * receives adjustment events from this <code>ScrollPaneAdjustable</code>.
359      * If <code>l</code> is <code>null</code>, no exception is thrown
360      * and no action is performed.
361      *
362      * @param         l     the adjustment listener.
363      * @see           #addAdjustmentListener
364      * @see           #getAdjustmentListeners
365      * @see           java.awt.event.AdjustmentListener
366      * @see           java.awt.event.AdjustmentEvent
367      * @since         JDK1.1
368      */
369     public synchronized void removeAdjustmentListener(AdjustmentListener   l){
370     if (l == null) {
371         return;
372     }
373     adjustmentListener = AWTEventMulticaster.remove(adjustmentListener, l);
374     }
375 
376     /**
377      * Returns an array of all the adjustment listeners
378      * registered on this <code>ScrollPaneAdjustable</code>.
379      *
380      * @return all of this <code>ScrollPaneAdjustable</code>'s
381      *         <code>AdjustmentListener</code>s
382      *         or an empty array if no adjustment
383      *         listeners are currently registered
384      *
385      * @see           #addAdjustmentListener
386      * @see           #removeAdjustmentListener
387      * @see           java.awt.event.AdjustmentListener
388      * @see           java.awt.event.AdjustmentEvent
389      * @since 1.4
390      */
391     public synchronized AdjustmentListener  [] getAdjustmentListeners() {
392         return (AdjustmentListener  [])(AWTEventMulticaster.getListeners(
393                                       adjustmentListener,
394                                       AdjustmentListener  .class));
395     }
396 
397     /**
398      * Returns a string representation of this scrollbar and its values.
399      * @return    a string representation of this scrollbar.
400      */
401     public String   toString() {
402     return getClass().getName() + "[" + paramString() + "]";
403     }
404 
405     /**
406      * Returns a string representing the state of this scrollbar.
407      * This method is intended to be used only for debugging purposes,
408      * and the content and format of the returned string may vary
409      * between implementations.  The returned string may be empty but
410      * may not be <code>null</code>.
411      *
412      * @return      the parameter string of this scrollbar.
413      */
414     public String   paramString() {
415         return ((orientation == Adjustable.VERTICAL ? "vertical,"
416                                             :"horizontal,")
417         + "[0.."+maximum+"]"
418         + ",val=" + value
419         + ",vis=" + visibleAmount
420         + ",unit=" + unitIncrement
421         + ",block=" + blockIncrement
422         + ",isAdjusting=" + isAdjusting);
423     }
424 }
425
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags