001 /* DefaultBoundedRangeModel.java -- Default implementation 002 of BoundedRangeModel. 003 Copyright (C) 2002, 2004, 2005, 2006, Free Software Foundation, Inc. 004 005 This file is part of GNU Classpath. 006 007 GNU Classpath is free software; you can redistribute it and/or modify 008 it under the terms of the GNU General Public License as published by 009 the Free Software Foundation; either version 2, or (at your option) 010 any later version. 011 012 GNU Classpath is distributed in the hope that it will be useful, but 013 WITHOUT ANY WARRANTY; without even the implied warranty of 014 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 015 General Public License for more details. 016 017 You should have received a copy of the GNU General Public License 018 along with GNU Classpath; see the file COPYING. If not, write to the 019 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 020 02110-1301 USA. 021 022 Linking this library statically or dynamically with other modules is 023 making a combined work based on this library. Thus, the terms and 024 conditions of the GNU General Public License cover the whole 025 combination. 026 027 As a special exception, the copyright holders of this library give you 028 permission to link this library with independent modules to produce an 029 executable, regardless of the license terms of these independent 030 modules, and to copy and distribute the resulting executable under 031 terms of your choice, provided that you also meet, for each linked 032 independent module, the terms and conditions of the license of that 033 module. An independent module is a module which is not derived from 034 or based on this library. If you modify this library, you may extend 035 this exception to your version of the library, but you are not 036 obligated to do so. If you do not wish to do so, delete this 037 exception statement from your version. */ 038 039 040 package javax.swing; 041 042 import java.io.IOException; 043 import java.io.ObjectInputStream; 044 import java.io.ObjectOutputStream; 045 import java.io.Serializable; 046 import java.util.EventListener; 047 048 import javax.swing.event.ChangeEvent; 049 import javax.swing.event.ChangeListener; 050 import 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 */ 058 public 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 <= value <= value + extent <= 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 }