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