001/* DefaultBoundedRangeModel.java -- Default implementation
002   of BoundedRangeModel.
003   Copyright (C) 2002, 2004, 2005, 2006,  Free Software Foundation, Inc.
004
005This file is part of GNU Classpath.
006
007GNU Classpath is free software; you can redistribute it and/or modify
008it under the terms of the GNU General Public License as published by
009the Free Software Foundation; either version 2, or (at your option)
010any later version.
011
012GNU Classpath is distributed in the hope that it will be useful, but
013WITHOUT ANY WARRANTY; without even the implied warranty of
014MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
015General Public License for more details.
016
017You should have received a copy of the GNU General Public License
018along with GNU Classpath; see the file COPYING.  If not, write to the
019Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
02002110-1301 USA.
021
022Linking this library statically or dynamically with other modules is
023making a combined work based on this library.  Thus, the terms and
024conditions of the GNU General Public License cover the whole
025combination.
026
027As a special exception, the copyright holders of this library give you
028permission to link this library with independent modules to produce an
029executable, regardless of the license terms of these independent
030modules, and to copy and distribute the resulting executable under
031terms of your choice, provided that you also meet, for each linked
032independent module, the terms and conditions of the license of that
033module.  An independent module is a module which is not derived from
034or based on this library.  If you modify this library, you may extend
035this exception to your version of the library, but you are not
036obligated to do so.  If you do not wish to do so, delete this
037exception statement from your version. */
038
039
040package javax.swing;
041
042import java.io.IOException;
043import java.io.ObjectInputStream;
044import java.io.ObjectOutputStream;
045import java.io.Serializable;
046import java.util.EventListener;
047
048import javax.swing.event.ChangeEvent;
049import javax.swing.event.ChangeListener;
050import javax.swing.event.EventListenerList;
051
052/**
053 * The default implementation of <code>BoundedRangeModel</code>.
054 *
055 * @author Andrew Selkirk (aselkirk@sympatico.ca)
056 * @author Sascha Brawer (brawer@dandelis.ch)
057 */
058public class DefaultBoundedRangeModel
059  implements BoundedRangeModel, Serializable
060{
061  /**
062   * The identifier of this class in object serialization. Verified
063   * using the serialver tool of Sun J2SE 1.4.1_01.
064   */
065  private static final long serialVersionUID = 5034068491295259790L;
066
067  /**
068   * An event that is sent to all registered {@link ChangeListener}s
069   * when the state of this range model has changed.
070   *
071   * <p>The event object is created on demand, the first time it
072   * is actually needed.</p>
073   *
074   * @see #fireStateChanged()
075   */
076  protected transient ChangeEvent changeEvent;
077
078  /**
079   * The list of the currently registered EventListeners.
080   */
081  protected EventListenerList listenerList = new EventListenerList();
082
083  /**
084   * The current value of the range model, which is always between
085   * {@link #minimum} and ({@link #maximum} - {@link #extent}). In a
086   * scroll bar visualization of a {@link BoundedRangeModel}, the
087   * <code>value</code> is displayed as the position of the thumb.
088   */
089  private int value;
090
091  /**
092   * The current extent of the range model, which is a number greater
093   * than or equal to zero. In a scroll bar visualization of a {@link
094   * BoundedRangeModel}, the <code>extent</code> is displayed as the
095   * size of the thumb.
096   */
097  private int extent;
098
099  /**
100   * The current minimum value of the range model, which is always
101   * less than or equal to {@link #maximum}.
102   */
103  private int minimum;
104
105  /**
106   * The current maximum value of the range model, which is always
107   * greater than or equal to {@link #minimum}.
108   */
109  private int maximum;
110
111  /**
112   * A property that indicates whether the value of this {@link
113   * BoundedRangeModel} is going to change in the immediate future.
114   */
115  private boolean isAdjusting;
116
117  /**
118   * Constructs a <code>DefaultBoundedRangeModel</code> with default
119   * values for the properties. The properties <code>value</code>,
120   * <code>extent</code> and <code>minimum</code> will be initialized
121   * to zero; <code>maximum</code> will be set to 100; the property
122   * <code>valueIsAdjusting</code> will be <code>false</code>.
123   */
124  public DefaultBoundedRangeModel()
125  {
126    // The fields value, extent, minimum have the default value 0, and
127    // isAdjusting is already false. These fields no not need to be
128    // set explicitly.
129    maximum = 100;
130  }
131
132  /**
133   * Constructs a <code>DefaultBoundedRangeModel</code> with the
134   * specified values for some properties.
135   *
136   * @param value the initial value of the range model, which must be
137   *     a number between <code>minimum</code> and <code>(maximum -
138   *     extent)</code>. In a scroll bar visualization of a {@link
139   *     BoundedRangeModel}, the <code>value</code> is displayed as the
140   *     position of the thumb.
141   * @param extent the initial extent of the range model, which is a
142   *     number greater than or equal to zero. In a scroll bar
143   *     visualization of a {@link BoundedRangeModel}, the
144   *     <code>extent</code> is displayed as the size of the thumb.
145   * @param minimum the initial minimal value of the range model.
146   * @param maximum the initial maximal value of the range model.
147   *
148   * @throws IllegalArgumentException if the following condition is
149   *     not satisfied: <code>minimum &lt;= value &lt;= value + extent &lt;=
150   *     maximum</code>.
151   */
152  public DefaultBoundedRangeModel(int value, int extent, int minimum,
153                                  int maximum)
154  {
155    if (!(minimum <= value && extent >= 0 && (value + extent) <= maximum))
156      throw new IllegalArgumentException();
157
158    this.value = value;
159    this.extent = extent;
160    this.minimum = minimum;
161    this.maximum = maximum;
162
163    // The isAdjusting field already has a false value by default.
164  }
165
166  /**
167   * Returns a string with all relevant properties of this range
168   * model.
169   *
170   * @return a string representing the object
171   */
172  public String toString()
173  {
174    return getClass().getName()
175      + "[value=" + value
176      + ", extent=" + extent
177      + ", min=" + minimum
178      + ", max=" + maximum
179      + ", adj=" + isAdjusting
180      + ']';
181  }
182
183  /**
184   * Returns the current value of this bounded range model.  In a
185   * scroll bar visualization of a {@link BoundedRangeModel}, the
186   * <code>value</code> is displayed as the position of the thumb.
187   *
188   * @return the value
189   */
190  public int getValue()
191  {
192    return value;
193  }
194
195  /**
196   * Changes the current value of this bounded range model. In a
197   * scroll bar visualization of a {@link BoundedRangeModel}, the
198   * <code>value</code> is displayed as the position of the thumb;
199   * changing the <code>value</code> of a scroll bar's model
200   * thus moves the thumb to a different position.
201   *
202   * @param value the value
203   */
204  public void setValue(int value)
205  {
206    value = Math.max(minimum, value);
207    if (value + extent > maximum)
208      value = maximum - extent;
209
210    if (value != this.value)
211      {
212        this.value = value;
213        fireStateChanged();
214      }
215  }
216
217  /**
218   * Returns the current extent of this bounded range model, which is
219   * a number greater than or equal to zero. In a scroll bar
220   * visualization of a {@link BoundedRangeModel}, the
221   * <code>extent</code> is displayed as the size of the thumb.
222   *
223   * @return the extent
224   */
225  public int getExtent()
226  {
227    return extent;
228  }
229
230  /**
231   * Changes the current extent of this bounded range model. In a
232   * scroll bar visualization of a {@link BoundedRangeModel}, the
233   * <code>extent</code> is displayed as the size of the thumb.
234   *
235   * @param extent the new extent of the range model, which is a
236   *     number greater than or equal to zero.
237   */
238  public void setExtent(int extent)
239  {
240    extent = Math.max(extent, 0);
241    if (value + extent > maximum)
242      extent = maximum - value;
243
244    if (extent != this.extent)
245      {
246        this.extent = extent;
247        fireStateChanged();
248      }
249  }
250
251  /**
252   * Returns the current minimal value of this bounded range model.
253   */
254  public int getMinimum()
255  {
256    return minimum;
257  }
258
259  /**
260   * Changes the current minimal value of this bounded range model.
261   *
262   * @param minimum the new minimal value.
263   */
264  public void setMinimum(int minimum)
265  {
266    int value, maximum;
267
268    maximum = Math.max(minimum, this.maximum);
269    value = Math.max(minimum, this.value);
270
271    setRangeProperties(value, extent, minimum, maximum, isAdjusting);
272  }
273
274  /**
275   * Returns the current maximal value of this bounded range model.
276   *
277   * @return the maximum
278   */
279  public int getMaximum()
280  {
281    return maximum;
282  }
283
284  /**
285   * Changes the current maximal value of this bounded range model.
286   *
287   * @param maximum the new maximal value.
288   */
289  public void setMaximum(int maximum)
290  {
291    int value, extent, minimum;
292
293    minimum = Math.min(this.minimum, maximum);
294    extent = Math.min(this.extent, maximum - minimum);
295    value = Math.min(this.value, maximum - extent);
296
297    setRangeProperties(value, extent, minimum, maximum, isAdjusting);
298  }
299
300  /**
301   * Returns whether or not the value of this bounded range model is
302   * going to change in the immediate future. Scroll bars set this
303   * property to <code>true</code> while the thumb is being dragged
304   * around; when the mouse is relased, they set the property to
305   * <code>false</code> and post a final {@link ChangeEvent}.
306   *
307   * @return <code>true</code> if the value will change soon again;
308   *     <code>false</code> if the value will probably not change soon.
309   */
310  public boolean getValueIsAdjusting()
311  {
312    return isAdjusting;
313  }
314
315  /**
316   * Specifies whether or not the value of this bounded range model is
317   * going to change in the immediate future. Scroll bars set this
318   * property to <code>true</code> while the thumb is being dragged
319   * around; when the mouse is relased, they set the property to
320   * <code>false</code>.
321   *
322   * @param isAdjusting <code>true</code> if the value will change
323   *     soon again; <code>false</code> if the value will probably not
324   *     change soon.
325   */
326  public void setValueIsAdjusting(boolean isAdjusting)
327  {
328    if (isAdjusting == this.isAdjusting)
329      return;
330
331    this.isAdjusting = isAdjusting;
332    fireStateChanged();
333  }
334
335  /**
336   * Sets all properties.
337   *
338   * @param value the new value of the range model.  In a scroll bar
339   *     visualization of a {@link BoundedRangeModel}, the
340   *     <code>value</code> is displayed as the position of the thumb.
341   * @param extent the new extent of the range model, which is a
342   *     number greater than or equal to zero. In a scroll bar
343   *     visualization of a {@link BoundedRangeModel}, the
344   *     <code>extent</code> is displayed as the size of the thumb.
345   * @param minimum the new minimal value of the range model.
346   * @param maximum the new maximal value of the range model.
347   * @param isAdjusting whether or not the value of this bounded range
348   *     model is going to change in the immediate future. Scroll bars set
349   *     this property to <code>true</code> while the thumb is being
350   *     dragged around; when the mouse is relased, they set the property
351   *     to <code>false</code>.
352   */
353  public void setRangeProperties(int value, int extent, int minimum,
354                                 int maximum, boolean isAdjusting)
355  {
356    minimum = Math.min(Math.min(minimum, maximum), value);
357    maximum = Math.max(value, maximum);
358    if (extent + value > maximum)
359      extent = maximum - value;
360    extent = Math.max(0, extent);
361
362    if ((value == this.value)
363        && (extent == this.extent)
364        && (minimum == this.minimum)
365        && (maximum == this.maximum)
366        && (isAdjusting == this.isAdjusting))
367      return;
368
369    this.value = value;
370    this.extent = extent;
371    this.minimum = minimum;
372    this.maximum = maximum;
373    this.isAdjusting = isAdjusting;
374                
375    fireStateChanged();
376  }
377
378  /**
379   * Subscribes a ChangeListener to state changes.
380   *
381   * @param listener the listener to be subscribed.
382   */
383  public void addChangeListener(ChangeListener listener)
384  {
385    listenerList.add(ChangeListener.class, listener);
386  }
387
388  /**
389   * Cancels the subscription of a ChangeListener.
390   *
391   * @param listener the listener to be unsubscribed.
392   */
393  public void removeChangeListener(ChangeListener listener)
394  {
395    listenerList.remove(ChangeListener.class, listener);
396  }
397
398  /**
399   * Sends a {@link ChangeEvent} to any registered {@link
400   * ChangeListener}s.
401   *
402   * @see #addChangeListener(ChangeListener)
403   * @see #removeChangeListener(ChangeListener)
404   */
405  protected void fireStateChanged()
406  {
407    ChangeListener[] listeners = getChangeListeners();
408    
409    if (changeEvent == null)
410      changeEvent = new ChangeEvent(this);
411
412    for (int i = listeners.length - 1; i >= 0; --i)
413      listeners[i].stateChanged(changeEvent);
414  }
415
416  /**
417   * Retrieves the current listeners of the specified class.
418   *
419   * @param listenerType the class of listeners; usually {@link
420   *     ChangeListener}<code>.class</code>.
421   *
422   * @return an array with the currently subscribed listeners, or
423   *     an empty array if there are currently no listeners.
424   *
425   * @since 1.3
426   */
427  public <T extends EventListener> T[] getListeners(Class<T> listenerType)
428  {
429    return listenerList.getListeners(listenerType);
430  }
431
432  /**
433   * Returns all <code>ChangeListeners</code> that are currently
434   * subscribed for changes to this
435   * <code>DefaultBoundedRangeModel</code>.
436   *
437   * @return an array with the currently subscribed listeners, or
438   *     an empty array if there are currently no listeners.
439   *
440   * @since 1.4
441   */
442  public ChangeListener[] getChangeListeners()
443  {
444    return (ChangeListener[]) getListeners(ChangeListener.class);
445  }
446  
447  /**
448   * Provides serialization support.
449   *
450   * @param stream  the output stream (<code>null</code> not permitted).
451   *
452   * @throws IOException  if there is an I/O error.
453   */
454  private void writeObject(ObjectOutputStream stream) 
455    throws IOException 
456  {
457    stream.defaultWriteObject();
458  }
459
460  /**
461   * Provides serialization support.
462   *
463   * @param stream  the input stream (<code>null</code> not permitted).
464   *
465   * @throws IOException  if there is an I/O error.
466   * @throws ClassNotFoundException  if there is a classpath problem.
467   */
468  private void readObject(ObjectInputStream stream)
469    throws ClassNotFoundException, IOException
470  {
471    stream.defaultReadObject();
472    listenerList = new EventListenerList();
473  }
474
475}