SAbstractAdjustable


1   /*
2    * $Id: SAbstractAdjustable.java,v 1.12 2005/04/08 15:05:18 blueshift Exp $
3    * Copyright 2000,2005 wingS development team.
4    *
5    * This file is part of wingS (http://www.j-wings.org).
6    *
7    * wingS is free software; you can redistribute it and/or modify
8    * it under the terms of the GNU Lesser General Public License
9    * as published by the Free Software Foundation; either version 2.1
10   * of the License, or (at your option) any later version.
11   *
12   * Please see COPYING for the complete licence.
13   */
14  package org.wings;
15  
16  import javax.swing.*;
17  import javax.swing.event.ChangeEvent  ;
18  import javax.swing.event.ChangeListener  ;
19  import java.awt.*;
20  import java.awt.event.AdjustmentEvent  ;
21  import java.awt.event.AdjustmentListener  ;
22  import java.io.Serializable  ;
23  
24  /**
25   * @author <a HREF="mailto:haaf@mercatis.de">Armin Haaf</a>
26   * @version $Revision: 1.12 $
27   */
28  public abstract class SAbstractAdjustable
29          extends SComponent
30          implements Adjustable, LowLevelEventListener {
31      public static final int UNIT = 0;
32  
33      public static final int BLOCK = 1;
34  
35      public static final int MARGIN = 2;
36  
37      /**
38       * All changes from the model are treated as though the user moved
39       * the scrollbar knob.
40       */
41      private final ChangeListener   fwdAdjustmentEvents = new ModelListener();
42  
43      /**
44       * The model that represents the scrollbar's minimum, maximum, extent
45       * (aka "visibleAmount") and current value.
46       *
47       * @see #setModel
48       */
49      protected SBoundedRangeModel model;
50  
51      /**
52       * @see #setUnitIncrement
53       */
54      protected int unitIncrement;
55  
56      /**
57       * @see #setBlockIncrement
58       */
59      protected int blockIncrement;
60  
61      /**
62       * @see #setBlockIncrement
63       */
64      protected int orientation;
65  
66      /**
67       * Creates a scrollbar with the specified orientation,
68       * value, extent, mimimum, and maximum.
69       * The "extent" is the size of the viewable area. It is also known
70       * as the "visible amount".
71       * <p/>
72       * Note: Use <code>setBlockIncrement</code> to set the block
73       * increment to a size slightly smaller than the view's extent.
74       * That way, when the user jumps the knob to an adjacent position,
75       * one or two lines of the original contents remain in view.
76       *
77       * @throws IllegalArgumentException if orientation is not one of VERTICAL, HORIZONTAL
78       * @see #setOrientation
79       * @see #setValue
80       * @see #setVisibleAmount
81       * @see #setMinimum
82       * @see #setMaximum
83       */
84      public SAbstractAdjustable(int value, int extent, int min, int max) {
85          this(new SDefaultBoundedRangeModel(value, extent, min, max));
86      }
87  
88  
89      public SAbstractAdjustable(SBoundedRangeModel model) {
90          this.model = model;
91          this.model.addChangeListener(fwdAdjustmentEvents);
92          this.unitIncrement = 1;
93          this.blockIncrement = (model.getExtent() == 0) ? 1 : model.getExtent();
94      }
95  
96      /**
97       * Creates a scrollbar with the specified orientation
98       * and the following initial values:
99       * <pre>
100      * minimum = 0
101      * maximum = 100
102      * value = 0
103      * extent = 10
104      * </pre>
105      */
106     public SAbstractAdjustable() {
107         this(0, 10, 0, 100);
108     }
109 
110     /**
111      * Returns data model that handles the scrollbar's four
112      * fundamental properties: minimum, maximum, value, extent.
113      *
114      * @see #setModel
115      */
116     public final SBoundedRangeModel getModel() {
117         return model;
118     }
119 
120 
121     /**
122      * Sets the model that handles the scrollbar's four
123      * fundamental properties: minimum, maximum, value, extent.
124      *
125      * @beaninfo bound: true
126      * expert: true
127      * description: The scrollbar's BoundedRangeModel.
128      * @see #getModel
129      */
130     public void setModel(SBoundedRangeModel newModel) {
131         reloadIfChange(this.model, newModel);
132         if (model != null) {
133             model.removeChangeListener(fwdAdjustmentEvents);
134         }
135         model = newModel;
136         if (model != null) {
137             model.addChangeListener(fwdAdjustmentEvents);
138         }
139     }
140 
141 
142     /**
143      * Returns the amount to change the scrollbar's value by,
144      * given a unit up/down request.  A ScrollBarUI implementation
145      * typically calls this method when the user clicks on a scrollbar
146      * up/down arrow and uses the result to update the scrollbar's
147      * value.   Subclasses my override this method to compute
148      * a value, e.g. the change required to scroll up or down one
149      * (variable height) line text or one row in a table.
150      * <p/>
151      * The JScrollPane component creates scrollbars (by default)
152      * that override this method and delegate to the viewports
153      * Scrollable view, if it has one.  The Scrollable interface
154      * provides a more specialized version of this method.
155      *
156      * @param direction is -1 or 1 for up/down respectively
157      * @return the value of the unitIncrement property
158      * @see #setUnitIncrement
159      * @see #setValue
160      */
161     public int getUnitIncrement(int direction) {
162         return unitIncrement;
163     }
164 
165 
166     /**
167      * Sets the unitIncrement property.
168      *
169      * @beaninfo preferred: true
170      * bound: true
171      * description: The scrollbar's unit increment.
172      * @see #getUnitIncrement
173      */
174     public void setUnitIncrement(int unitIncrement) {
175         reloadIfChange(this.unitIncrement, unitIncrement);
176         this.unitIncrement = unitIncrement;
177     }
178 
179     /**
180      * Returns the amount to change the scrollbar's value by,
181      * given a block (usually "page") up/down request.  A ScrollBarUI
182      * implementation typically calls this method when the user clicks
183      * above or below the scrollbar "knob" to change the value
184      * up or down by large amount.  Subclasses my override this
185      * method to compute a value, e.g. the change required to scroll
186      * up or down one paragraph in a text document.
187      * <p/>
188      * The JScrollPane component creates scrollbars (by default)
189      * that override this method and delegate to the viewports
190      * Scrollable view, if it has one.  The Scrollable interface
191      * provides a more specialized version of this method.
192      *
193      * @param direction is -1 or 1 for up/down respectively
194      * @return the value of the blockIncrement property
195      * @see #setBlockIncrement
196      * @see #setValue
197      */
198     public int getBlockIncrement(int direction) {
199         return blockIncrement;
200     }
201 
202 
203     /**
204      * Sets the blockIncrement property.
205      *
206      * @beaninfo preferred: true
207      * bound: true
208      * description: The scrollbar's block increment.
209      * @see #getBlockIncrement()
210      */
211     public void setBlockIncrement(int blockIncrement) {
212         reloadIfChange(this.blockIncrement, blockIncrement);
213         this.blockIncrement = blockIncrement;
214     }
215 
216 
217     /**
218      * For backwards compatibility with java.awt.Scrollbar.
219      *
220      * @see Adjustable#getUnitIncrement
221      * @see #getUnitIncrement(int)
222      */
223     public final int getUnitIncrement() {
224         return unitIncrement;
225     }
226 
227 
228     /**
229      * For backwards compatibility with java.awt.Scrollbar.
230      *
231      * @see Adjustable#getBlockIncrement
232      * @see #getBlockIncrement(int)
233      */
234     public final int getBlockIncrement() {
235         return blockIncrement;
236     }
237 
238 
239     /**
240      * Returns the scrollbar's value.
241      *
242      * @return the model's value property
243      * @see #setValue
244      */
245     public final int getValue() {
246         return getModel().getValue();
247     }
248 
249 
250     /**
251      * Sets the scrollbar's value.  This method just forwards the value
252      * to the model.
253      *
254      * @beaninfo preferred: true
255      * bound: true
256      * description: The scrollbar's current value.
257      * @see #getValue
258      * @see BoundedRangeModel#setValue
259      */
260     public void setValue(int value) {
261         getModel().setValue(value);
262     }
263 
264     public final int getExtent() {
265         return getModel().getExtent();
266     }
267 
268 
269     public void setExtent(int value) {
270         getModel().setExtent(value);
271     }
272 
273 
274     /**
275      * Returns the scrollbar's extent, aka its "visibleAmount".  In many
276      * scrollbar look and feel implementations the size of the
277      * scrollbar "knob" or "thumb" is proportional to the extent.
278      *
279      * @return the value of the model's extent property
280      * @see #setVisibleAmount
281      */
282     public final int getVisibleAmount() {
283         return getModel().getExtent();
284     }
285 
286 
287     /**
288      * Set the model's extent property.
289      *
290      * @beaninfo preferred: true
291      * description: The amount of the view that is currently visible.
292      * @see #getVisibleAmount
293      * @see BoundedRangeModel#setExtent
294      */
295     public void setVisibleAmount(int extent) {
296         getModel().setExtent(extent);
297     }
298 
299 
300     /**
301      * Returns the minimum value supported by the scrollbar
302      * (usually zero).
303      *
304      * @return the value of the model's minimum property
305      * @see #setMinimum
306      */
307     public final int getMinimum() {
308         return getModel().getMinimum();
309     }
310 
311 
312     /**
313      * Sets the model's minimum property.
314      *
315      * @beaninfo preferred: true
316      * description: The scrollbar's minimum value.
317      * @see #getMinimum
318      * @see BoundedRangeModel#setMinimum
319      */
320     public void setMinimum(int minimum) {
321         getModel().setMinimum(minimum);
322     }
323 
324 
325     /**
326      * The maximum value of the scrollbar is maximum - extent.
327      *
328      * @return the value of the model's maximum property
329      * @see #setMaximum
330      */
331     public final int getMaximum() {
332         return getModel().getMaximum();
333     }
334 
335 
336     /**
337      * Sets the model's maximum property.  Note that the scrollbar's value
338      * can only be set to maximum - extent.
339      *
340      * @beaninfo preferred: true
341      * description: The scrollbar's maximum value.
342      * @see #getMaximum
343      * @see BoundedRangeModel#setMaximum
344      */
345     public void setMaximum(int maximum) {
346         getModel().setMaximum(maximum);
347     }
348 
349     /**
350      * Returns the adjustable's orientation (horizontal or vertical).
351      *
352      * @return VERTICAL or HORIZONTAL
353      * @see #setOrientation
354      * @see java.awt.Adjustable#getOrientation
355      */
356     public final int getOrientation() {
357         return orientation;
358     }
359 
360     /**
361      * Set the scrollbar's orientation to either VERTICAL or
362      * HORIZONTAL.
363      *
364      * @throws IllegalArgumentException if orientation is not one of VERTICAL, HORIZONTAL
365      * @see #getOrientation
366      */
367     public void setOrientation(int orientation) {
368         switch (orientation) {
369             case SConstants.VERTICAL:
370             case SConstants.HORIZONTAL:
371                 this.orientation = orientation;
372                 break;
373             default:
374                 throw new IllegalArgumentException  ("orientation must be one of: VERTICAL, HORIZONTAL");
375         }
376     }
377 
378 
379     /**
380      * True if the scrollbar knob is being dragged.
381      *
382      * @return the value of the model's valueIsAdjusting property
383      * @see #setValueIsAdjusting
384      */
385     public final boolean getValueIsAdjusting() {
386         return getModel().getValueIsAdjusting();
387     }
388 
389 
390     /**
391      * Sets the model's valueIsAdjusting property.  Scrollbar look and
392      * feel implementations should set this property to true when
393      * a knob drag begins, and to false when the drag ends.  The
394      * scrollbar model will not generate ChangeEvents while
395      * valueIsAdjusting is true.
396      *
397      * @beaninfo expert: true
398      * bound: true
399      * description: True if the scrollbar thumb is being dragged.
400      * @see #getValueIsAdjusting
401      * @see BoundedRangeModel#setValueIsAdjusting
402      */
403     public void setValueIsAdjusting(boolean b) {
404         getModel().setValueIsAdjusting(b);
405     }
406 
407 
408     /**
409      * Sets the four BoundedRangeModel properties after forcing
410      * the arguments to obey the usual constraints:
411      * <pre>
412      * minimum <= value <= value+extent <= maximum
413      * </pre>
414      * <p/>
415      *
416      * @see BoundedRangeModel#setRangeProperties
417      * @see #setValue
418      * @see #setVisibleAmount
419      * @see #setMinimum
420      * @see #setMaximum
421      */
422     public void setValues(int newValue, int newExtent, int newMin, int newMax) {
423         BoundedRangeModel m = getModel();
424         m.setRangeProperties(newValue, newExtent, newMin, newMax, m.getValueIsAdjusting());
425     }
426 
427     public void processLowLevelEvent(String   action, String  [] values) {
428         processKeyEvents(values);
429 
430         getModel().setDelayEvents(true);
431         for (int i = 0; i < values.length; i++) {
432             try {
433                 setValue(Integer.parseInt(values[i]));
434             } catch (NumberFormatException   ex) {
435                 // ignore
436             }
437         }
438 
439         SForm.addArmedComponent(this);
440         getModel().setDelayEvents(false);
441     }
442 
443     public void fireIntermediateEvents() {
444         getModel().fireDelayedIntermediateEvents();
445     }
446 
447     public void fireFinalEvents() {
448         super.fireFinalEvents();
449         getModel().fireDelayedFinalEvents();
450     }
451 
452     /**
453      * Adds an AdjustmentListener.  Adjustment listeners are notified
454      * each time the scrollbar's model changes.  Adjustment events are
455      * provided for backwards compatability with java.awt.Scrollbar.
456      * <p/>
457      * Note that the AdjustmentEvents type property will always have a
458      * placeholder value of AdjustmentEvent.TRACK because all changes
459      * to a BoundedRangeModels value are considered equivalent.  To change
460      * the value of a BoundedRangeModel one just sets its value property,
461      * i.e. model.setValue(123).  No information about the origin of the
462      * change, e.g. it's a block decrement, is provided.  We don't try
463      * fabricate the origin of the change here.
464      *
465      * @param l the AdjustmentLister to add
466      * @see #removeAdjustmentListener
467      * @see BoundedRangeModel#addChangeListener
468      */
469     public void addAdjustmentListener(AdjustmentListener   l) {
470         addEventListener(AdjustmentListener  .class, l);
471     }
472 
473 
474     /**
475      * Removes an AdjustmentEvent listener.
476      *
477      * @param l the AdjustmentLister to remove
478      * @see #addAdjustmentListener
479      */
480     public void removeAdjustmentListener(AdjustmentListener   l) {
481         removeEventListener(AdjustmentListener  .class, l);
482     }
483 
484 
485     /*
486      * Notify listeners that the scrollbar's model has changed.
487      *
488      * @see #addAdjustmentListener
489      * @see EventListenerList
490      */
491     protected void fireAdjustmentValueChanged(int id, int type, int value) {
492         AdjustmentEvent   e = null;
493 
494         Object  [] listeners = getListenerList();
495         for (int i = listeners.length - 2; i >= 0; i -= 2) {
496             if (listeners[i] == AdjustmentListener  .class) {
497                 if (e == null) {
498                     e = new AdjustmentEvent  (this, id, type, value);
499                 }
500                 ((AdjustmentListener  ) listeners[i + 1]).adjustmentValueChanged(e);
501             }
502         }
503     }
504 
505     /**
506      * This class listens to ChangeEvents on the model and forwards
507      * AdjustmentEvents for the sake of backwards compatibility.
508      * Unfortunately there's no way to determine the proper
509      * type of the AdjustmentEvent as all updates to the model's
510      * value are considered equivalent.
511      */
512     private class ModelListener implements ChangeListener  , Serializable   {
513         public void stateChanged(ChangeEvent   e) {
514             int id = AdjustmentEvent.ADJUSTMENT_VALUE_CHANGED;
515             int type = AdjustmentEvent.TRACK;
516             fireAdjustmentValueChanged(id, type, getValue());
517             reload();
518         }
519     }
520 
521     /** @see LowLevelEventListener#isEpochCheckEnabled() */
522     private boolean epochCheckEnabled = true;
523 
524     /** @see LowLevelEventListener#isEpochCheckEnabled() */
525     public boolean isEpochCheckEnabled() {
526         return epochCheckEnabled;
527     }
528 
529     /** @see LowLevelEventListener#isEpochCheckEnabled() */
530     public void setEpochCheckEnabled(boolean epochCheckEnabled) {
531         this.epochCheckEnabled = epochCheckEnabled;
532     }
533 
534 }
535
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags