1 /*
   2  * Copyright (c) 2000, 2013, 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.awt.event.*;
  29 import javax.swing.event.*;
  30 
  31 
  32 /**
  33  * A model for a potentially unbounded sequence of object values.  This model
  34  * is similar to {@code ListModel} however there are some important differences:
  35  * <ul>
  36  * <li> The number of sequence elements isn't necessarily bounded.
  37  * <li> The model doesn't support indexed random access to sequence elements.
  38  *      Only three sequence values are accessible at a time: current, next and
  39  *      previous.
  40  * <li> The current sequence element, can be set.
  41  * </ul>
  42  * <p>
  43  * A {@code SpinnerModel} has three properties, only the first is read/write.
  44  * <dl>
  45  *   <dt>{@code value}
  46  *   <dd>The current element of the sequence.
  47  *
  48  *   <dt>{@code nextValue}
  49  *   <dd>The following element or null if {@code value} is the
  50  *     last element of the sequence.
  51  *
  52  *   <dt>{@code previousValue}
  53  *   <dd>The preceding element or null if {@code value} is the
  54  *     first element of the sequence.
  55  * </dl>
  56  * When the {@code value} property changes,
  57  * {@code ChangeListeners} are notified.  {@code SpinnerModel} may
  58  * choose to notify the {@code ChangeListeners} under other circumstances.
  59  *
  60  * @see JSpinner
  61  * @see AbstractSpinnerModel
  62  * @see SpinnerListModel
  63  * @see SpinnerNumberModel
  64  * @see SpinnerDateModel
  65  *
  66  * @author Hans Muller
  67  * @since 1.4
  68  */
  69 public interface SpinnerModel
  70 {
  71     /**
  72      * The <i>current element</i> of the sequence.  This element is usually
  73      * displayed by the {@code editor} part of a {@code JSpinner}.
  74      *
  75      * @return the current spinner value.
  76      * @see #setValue
  77      */
  78     Object getValue();
  79 
  80 
  81     /**
  82      * Changes current value of the model, typically this value is displayed
  83      * by the {@code editor} part of a  {@code JSpinner}.
  84      * If the {@code SpinnerModel} implementation doesn't support
  85      * the specified value then an {@code IllegalArgumentException}
  86      * is thrown.  For example a {@code SpinnerModel} for numbers might
  87      * only support values that are integer multiples of ten. In
  88      * that case, {@code model.setValue(new Number(11))}
  89      * would throw an exception.
  90      *
  91      * @param value  new value for the spinner
  92      * @throws IllegalArgumentException if {@code value} isn't allowed
  93      * @see #getValue
  94      */
  95     void setValue(Object value);
  96 
  97 
  98     /**
  99      * Return the object in the sequence that comes after the object returned
 100      * by {@code getValue()}. If the end of the sequence has been reached
 101      * then return null.  Calling this method does not effect {@code value}.
 102      *
 103      * @return the next legal value or null if one doesn't exist
 104      * @see #getValue
 105      * @see #getPreviousValue
 106      */
 107     Object getNextValue();
 108 
 109 
 110     /**
 111      * Return the object in the sequence that comes before the object returned
 112      * by {@code getValue()}.  If the end of the sequence has been reached then
 113      * return null. Calling this method does not effect {@code value}.
 114      *
 115      * @return the previous legal value or null if one doesn't exist
 116      * @see #getValue
 117      * @see #getNextValue
 118      */
 119     Object getPreviousValue();
 120 
 121 
 122     /**
 123      * Adds a {@code ChangeListener} to the model's listener list.  The
 124      * {@code ChangeListeners} must be notified when models {@code value}
 125      * changes.
 126      *
 127      * @param l the ChangeListener to add
 128      * @see #removeChangeListener
 129      */
 130     void addChangeListener(ChangeListener l);
 131 
 132 
 133     /**
 134      * Removes a {@code ChangeListener} from the model's listener list.
 135      *
 136      * @param l the ChangeListener to remove
 137      * @see #addChangeListener
 138      */
 139     void removeChangeListener(ChangeListener l);
 140 }