1 /* 2 * Copyright (c) 2000, 2014, Oracle and/or its affiliates. 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. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package javax.swing; 27 28 import java.util.*; 29 import java.io.Serializable; 30 31 32 /** 33 * A <code>SpinnerModel</code> for sequences of numbers. 34 * The upper and lower bounds of the sequence are defined 35 * by properties called <code>minimum</code> and 36 * <code>maximum</code>. The size of the increase or decrease 37 * computed by the <code>nextValue</code> and 38 * <code>previousValue</code> methods is defined by a property called 39 * <code>stepSize</code>. The <code>minimum</code> and 40 * <code>maximum</code> properties can be <code>null</code> 41 * to indicate that the sequence has no lower or upper limit. 42 * All of the properties in this class are defined in terms of two 43 * generic types: <code>Number</code> and 44 * <code>Comparable</code>, so that all Java numeric types 45 * may be accommodated. Internally, there's only support for 46 * values whose type is one of the primitive <code>Number</code> types: 47 * <code>Double</code>, <code>Float</code>, <code>Long</code>, 48 * <code>Integer</code>, <code>Short</code>, or <code>Byte</code>. 49 * <p> 50 * To create a <code>SpinnerNumberModel</code> for the integer 51 * range zero to one hundred, with 52 * fifty as the initial value, one could write: 53 * <pre> 54 * Integer value = new Integer(50); 55 * Integer min = new Integer(0); 56 * Integer max = new Integer(100); 57 * Integer step = new Integer(1); 58 * SpinnerNumberModel model = new SpinnerNumberModel(value, min, max, step); 59 * int fifty = model.getNumber().intValue(); 60 * </pre> 61 * <p> 62 * Spinners for integers and doubles are common, so special constructors 63 * for these cases are provided. For example to create the model in 64 * the previous example, one could also write: 65 * <pre> 66 * SpinnerNumberModel model = new SpinnerNumberModel(50, 0, 100, 1); 67 * </pre> 68 * <p> 69 * This model inherits a <code>ChangeListener</code>. 70 * The <code>ChangeListeners</code> are notified 71 * whenever the model's <code>value</code>, <code>stepSize</code>, 72 * <code>minimum</code>, or <code>maximum</code> properties changes. 73 * 74 * @see JSpinner 75 * @see SpinnerModel 76 * @see AbstractSpinnerModel 77 * @see SpinnerListModel 78 * @see SpinnerDateModel 79 * 80 * @author Hans Muller 81 * @since 1.4 82 */ 83 @SuppressWarnings("serial") // Superclass is not serializable across versions 84 public class SpinnerNumberModel extends AbstractSpinnerModel implements Serializable 85 { 86 private Number stepSize, value; 87 private Comparable minimum, maximum; 88 89 90 /** 91 * Constructs a <code>SpinnerModel</code> that represents 92 * a closed sequence of 93 * numbers from <code>minimum</code> to <code>maximum</code>. The 94 * <code>nextValue</code> and <code>previousValue</code> methods 95 * compute elements of the sequence by adding or subtracting 96 * <code>stepSize</code> respectively. All of the parameters 97 * must be mutually <code>Comparable</code>, <code>value</code> 98 * and <code>stepSize</code> must be instances of <code>Integer</code> 99 * <code>Long</code>, <code>Float</code>, or <code>Double</code>. 100 * <p> 101 * The <code>minimum</code> and <code>maximum</code> parameters 102 * can be <code>null</code> to indicate that the range doesn't 103 * have an upper or lower bound. 104 * If <code>value</code> or <code>stepSize</code> is <code>null</code>, 105 * or if both <code>minimum</code> and <code>maximum</code> 106 * are specified and <code>minimum > maximum</code> then an 107 * <code>IllegalArgumentException</code> is thrown. 108 * Similarly if <code>(minimum <= value <= maximum</code>) is false, 109 * an <code>IllegalArgumentException</code> is thrown. 110 * 111 * @param value the current (non <code>null</code>) value of the model 112 * @param minimum the first number in the sequence or <code>null</code> 113 * @param maximum the last number in the sequence or <code>null</code> 114 * @param stepSize the difference between elements of the sequence 115 * 116 * @throws IllegalArgumentException if stepSize or value is 117 * <code>null</code> or if the following expression is false: 118 * <code>minimum <= value <= maximum</code> 119 */ 120 public SpinnerNumberModel(Number value, Comparable minimum, Comparable maximum, Number stepSize) { 121 if ((value == null) || (stepSize == null)) { 122 throw new IllegalArgumentException("value and stepSize must be non-null"); 123 } 124 if (!(((minimum == null) || (minimum.compareTo(value) <= 0)) && 125 ((maximum == null) || (maximum.compareTo(value) >= 0)))) { 126 throw new IllegalArgumentException("(minimum <= value <= maximum) is false"); 127 } 128 this.value = value; 129 this.minimum = minimum; 130 this.maximum = maximum; 131 this.stepSize = stepSize; 132 } 133 134 135 /** 136 * Constructs a <code>SpinnerNumberModel</code> with the specified 137 * <code>value</code>, <code>minimum</code>/<code>maximum</code> bounds, 138 * and <code>stepSize</code>. 139 * 140 * @param value the current value of the model 141 * @param minimum the first number in the sequence 142 * @param maximum the last number in the sequence 143 * @param stepSize the difference between elements of the sequence 144 * @throws IllegalArgumentException if the following expression is false: 145 * <code>minimum <= value <= maximum</code> 146 */ 147 public SpinnerNumberModel(int value, int minimum, int maximum, int stepSize) { 148 this(Integer.valueOf(value), Integer.valueOf(minimum), Integer.valueOf(maximum), Integer.valueOf(stepSize)); 149 } 150 151 152 /** 153 * Constructs a <code>SpinnerNumberModel</code> with the specified 154 * <code>value</code>, <code>minimum</code>/<code>maximum</code> bounds, 155 * and <code>stepSize</code>. 156 * 157 * @param value the current value of the model 158 * @param minimum the first number in the sequence 159 * @param maximum the last number in the sequence 160 * @param stepSize the difference between elements of the sequence 161 * @throws IllegalArgumentException if the following expression is false: 162 * <code>minimum <= value <= maximum</code> 163 */ 164 public SpinnerNumberModel(double value, double minimum, double maximum, double stepSize) { 165 this(new Double(value), new Double(minimum), new Double(maximum), new Double(stepSize)); 166 } 167 168 169 /** 170 * Constructs a <code>SpinnerNumberModel</code> with no 171 * <code>minimum</code> or <code>maximum</code> value, 172 * <code>stepSize</code> equal to one, and an initial value of zero. 173 */ 174 public SpinnerNumberModel() { 175 this(Integer.valueOf(0), null, null, Integer.valueOf(1)); 176 } 177 178 179 /** 180 * Changes the lower bound for numbers in this sequence. 181 * If <code>minimum</code> is <code>null</code>, 182 * then there is no lower bound. No bounds checking is done here; 183 * the new <code>minimum</code> value may invalidate the 184 * <code>(minimum <= value <= maximum)</code> 185 * invariant enforced by the constructors. This is to simplify updating 186 * the model, naturally one should ensure that the invariant is true 187 * before calling the <code>getNextValue</code>, 188 * <code>getPreviousValue</code>, or <code>setValue</code> methods. 189 * <p> 190 * Typically this property is a <code>Number</code> of the same type 191 * as the <code>value</code> however it's possible to use any 192 * <code>Comparable</code> with a <code>compareTo</code> 193 * method for a <code>Number</code> with the same type as the value. 194 * For example if value was a <code>Long</code>, 195 * <code>minimum</code> might be a Date subclass defined like this: 196 * <pre> 197 * MyDate extends Date { // Date already implements Comparable 198 * public int compareTo(Long o) { 199 * long t = getTime(); 200 * return (t < o.longValue() ? -1 : (t == o.longValue() ? 0 : 1)); 201 * } 202 * } 203 * </pre> 204 * <p> 205 * This method fires a <code>ChangeEvent</code> 206 * if the <code>minimum</code> has changed. 207 * 208 * @param minimum a <code>Comparable</code> that has a 209 * <code>compareTo</code> method for <code>Number</code>s with 210 * the same type as <code>value</code> 211 * @see #getMinimum 212 * @see #setMaximum 213 * @see SpinnerModel#addChangeListener 214 */ 215 public void setMinimum(Comparable minimum) { 216 if ((minimum == null) ? (this.minimum != null) : !minimum.equals(this.minimum)) { 217 this.minimum = minimum; 218 fireStateChanged(); 219 } 220 } 221 222 223 /** 224 * Returns the first number in this sequence. 225 * 226 * @return the value of the <code>minimum</code> property 227 * @see #setMinimum 228 */ 229 public Comparable getMinimum() { 230 return minimum; 231 } 232 233 234 /** 235 * Changes the upper bound for numbers in this sequence. 236 * If <code>maximum</code> is <code>null</code>, then there 237 * is no upper bound. No bounds checking is done here; the new 238 * <code>maximum</code> value may invalidate the 239 * <code>(minimum <= value < maximum)</code> 240 * invariant enforced by the constructors. This is to simplify updating 241 * the model, naturally one should ensure that the invariant is true 242 * before calling the <code>next</code>, <code>previous</code>, 243 * or <code>setValue</code> methods. 244 * <p> 245 * Typically this property is a <code>Number</code> of the same type 246 * as the <code>value</code> however it's possible to use any 247 * <code>Comparable</code> with a <code>compareTo</code> 248 * method for a <code>Number</code> with the same type as the value. 249 * See <a href="#setMinimum(java.lang.Comparable)"> 250 * <code>setMinimum</code></a> for an example. 251 * <p> 252 * This method fires a <code>ChangeEvent</code> if the 253 * <code>maximum</code> has changed. 254 * 255 * @param maximum a <code>Comparable</code> that has a 256 * <code>compareTo</code> method for <code>Number</code>s with 257 * the same type as <code>value</code> 258 * @see #getMaximum 259 * @see #setMinimum 260 * @see SpinnerModel#addChangeListener 261 */ 262 public void setMaximum(Comparable maximum) { 263 if ((maximum == null) ? (this.maximum != null) : !maximum.equals(this.maximum)) { 264 this.maximum = maximum; 265 fireStateChanged(); 266 } 267 } 268 269 270 /** 271 * Returns the last number in the sequence. 272 * 273 * @return the value of the <code>maximum</code> property 274 * @see #setMaximum 275 */ 276 public Comparable getMaximum() { 277 return maximum; 278 } 279 280 281 /** 282 * Changes the size of the value change computed by the 283 * <code>getNextValue</code> and <code>getPreviousValue</code> 284 * methods. An <code>IllegalArgumentException</code> 285 * is thrown if <code>stepSize</code> is <code>null</code>. 286 * <p> 287 * This method fires a <code>ChangeEvent</code> if the 288 * <code>stepSize</code> has changed. 289 * 290 * @param stepSize the size of the value change computed by the 291 * <code>getNextValue</code> and <code>getPreviousValue</code> methods 292 * @see #getNextValue 293 * @see #getPreviousValue 294 * @see #getStepSize 295 * @see SpinnerModel#addChangeListener 296 */ 297 public void setStepSize(Number stepSize) { 298 if (stepSize == null) { 299 throw new IllegalArgumentException("null stepSize"); 300 } 301 if (!stepSize.equals(this.stepSize)) { 302 this.stepSize = stepSize; 303 fireStateChanged(); 304 } 305 } 306 307 308 /** 309 * Returns the size of the value change computed by the 310 * <code>getNextValue</code> 311 * and <code>getPreviousValue</code> methods. 312 * 313 * @return the value of the <code>stepSize</code> property 314 * @see #setStepSize 315 */ 316 public Number getStepSize() { 317 return stepSize; 318 } 319 320 321 private Number incrValue(int dir) 322 { 323 Number newValue; 324 if ((value instanceof Float) || (value instanceof Double)) { 325 double v = value.doubleValue() + (stepSize.doubleValue() * (double)dir); 326 if (value instanceof Double) { 327 newValue = new Double(v); 328 } 329 else { 330 newValue = new Float(v); 331 } 332 } 333 else { 334 long v = value.longValue() + (stepSize.longValue() * (long)dir); 335 336 if (value instanceof Long) { 337 newValue = Long.valueOf(v); 338 } 339 else if (value instanceof Integer) { 340 newValue = Integer.valueOf((int)v); 341 } 342 else if (value instanceof Short) { 343 newValue = Short.valueOf((short)v); 344 } 345 else { 346 newValue = Byte.valueOf((byte)v); 347 } 348 } 349 350 if ((maximum != null) && (maximum.compareTo(newValue) < 0)) { 351 return null; 352 } 353 if ((minimum != null) && (minimum.compareTo(newValue) > 0)) { 354 return null; 355 } 356 else { 357 return newValue; 358 } 359 } 360 361 362 /** 363 * Returns the next number in the sequence. 364 * 365 * @return <code>value + stepSize</code> or <code>null</code> if the sum 366 * exceeds <code>maximum</code>. 367 * 368 * @see SpinnerModel#getNextValue 369 * @see #getPreviousValue 370 * @see #setStepSize 371 */ 372 public Object getNextValue() { 373 return incrValue(+1); 374 } 375 376 377 /** 378 * Returns the previous number in the sequence. 379 * 380 * @return <code>value - stepSize</code>, or 381 * <code>null</code> if the sum is less 382 * than <code>minimum</code>. 383 * 384 * @see SpinnerModel#getPreviousValue 385 * @see #getNextValue 386 * @see #setStepSize 387 */ 388 public Object getPreviousValue() { 389 return incrValue(-1); 390 } 391 392 393 /** 394 * Returns the value of the current element of the sequence. 395 * 396 * @return the value property 397 * @see #setValue 398 */ 399 public Number getNumber() { 400 return value; 401 } 402 403 404 /** 405 * Returns the value of the current element of the sequence. 406 * 407 * @return the value property 408 * @see #setValue 409 * @see #getNumber 410 */ 411 public Object getValue() { 412 return value; 413 } 414 415 416 /** 417 * Sets the current value for this sequence. If <code>value</code> is 418 * <code>null</code>, or not a <code>Number</code>, an 419 * <code>IllegalArgumentException</code> is thrown. No 420 * bounds checking is done here; the new value may invalidate the 421 * <code>(minimum <= value <= maximum)</code> 422 * invariant enforced by the constructors. It's also possible to set 423 * the value to be something that wouldn't naturally occur in the sequence, 424 * i.e. a value that's not modulo the <code>stepSize</code>. 425 * This is to simplify updating the model, and to accommodate 426 * spinners that don't want to restrict values that have been 427 * directly entered by the user. Naturally, one should ensure that the 428 * <code>(minimum <= value <= maximum)</code> invariant is true 429 * before calling the <code>next</code>, <code>previous</code>, or 430 * <code>setValue</code> methods. 431 * <p> 432 * This method fires a <code>ChangeEvent</code> if the value has changed. 433 * 434 * @param value the current (non <code>null</code>) <code>Number</code> 435 * for this sequence 436 * @throws IllegalArgumentException if <code>value</code> is 437 * <code>null</code> or not a <code>Number</code> 438 * @see #getNumber 439 * @see #getValue 440 * @see SpinnerModel#addChangeListener 441 */ 442 public void setValue(Object value) { 443 if ((value == null) || !(value instanceof Number)) { 444 throw new IllegalArgumentException("illegal value"); 445 } 446 if (!value.equals(this.value)) { 447 this.value = (Number)value; 448 fireStateChanged(); 449 } 450 } 451 }