001 /*
002 * Copyright 2000-2002 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.swing;
027
028 import java.awt.event.*;
029 import javax.swing.event.*;
030
031 /**
032 * A model for a potentially unbounded sequence of object values. This model
033 * is similar to <code>ListModel</code> however there are some important differences:
034 * <ul>
035 * <li> The number of sequence elements isn't neccessarily bounded.
036 * <li> The model doesn't support indexed random access to sequence elements.
037 * Only three sequence values are accessible at a time: current, next and
038 * previous.
039 * <li> The current sequence element, can be set.
040 * </ul>
041 * <p>
042 * A <code>SpinnerModel</code> has three properties, only the first is read/write.
043 * <dl>
044 * <dt><code>value</code>
045 * <dd>The current element of the sequence.
046 *
047 * <dt><code>nextValue</code>
048 * <dd>The following element or null if <code>value</code> is the
049 * last element of the sequence.
050 *
051 * <dt><code>previousValue</code>
052 * <dd>The preceeding element or null if <code>value</code> is the
053 * first element of the sequence.
054 * </dl>
055 * When the the <code>value</code> property changes,
056 * <code>ChangeListeners</code> are notified. <code>SpinnerModel</code> may
057 * choose to notify the <code>ChangeListeners</code> under other circumstances.
058 *
059 * @see JSpinner
060 * @see AbstractSpinnerModel
061 * @see SpinnerListModel
062 * @see SpinnerNumberModel
063 * @see SpinnerDateModel
064 *
065 * @version 1.13 05/05/07
066 * @author Hans Muller
067 * @since 1.4
068 */
069 public interface SpinnerModel {
070 /**
071 * The <i>current element</i> of the sequence. This element is usually
072 * displayed by the <code>editor</code> part of a <code>JSpinner</code>.
073 *
074 * @return the current spinner value.
075 * @see #setValue
076 */
077 Object getValue();
078
079 /**
080 * Changes current value of the model, typically this value is displayed
081 * by the <code>editor</code> part of a <code>JSpinner</code>.
082 * If the <code>SpinnerModel</code> implementation doesn't support
083 * the specified value then an <code>IllegalArgumentException</code>
084 * is thrown. For example a <code>SpinnerModel</code> for numbers might
085 * only support values that are integer multiples of ten. In
086 * that case, <code>model.setValue(new Number(11))</code>
087 * would throw an exception.
088 *
089 * @throws IllegalArgumentException if <code>value</code> isn't allowed
090 * @see #getValue
091 */
092 void setValue(Object value);
093
094 /**
095 * Return the object in the sequence that comes after the object returned
096 * by <code>getValue()</code>. If the end of the sequence has been reached
097 * then return null. Calling this method does not effect <code>value</code>.
098 *
099 * @return the next legal value or null if one doesn't exist
100 * @see #getValue
101 * @see #getPreviousValue
102 */
103 Object getNextValue();
104
105 /**
106 * Return the object in the sequence that comes before the object returned
107 * by <code>getValue()</code>. If the end of the sequence has been reached then
108 * return null. Calling this method does not effect <code>value</code>.
109 *
110 * @return the previous legal value or null if one doesn't exist
111 * @see #getValue
112 * @see #getNextValue
113 */
114 Object getPreviousValue();
115
116 /**
117 * Adds a <code>ChangeListener</code> to the model's listener list. The
118 * <code>ChangeListeners</code> must be notified when models <code>value</code>
119 * changes.
120 *
121 * @param l the ChangeListener to add
122 * @see #removeChangeListener
123 */
124 void addChangeListener(ChangeListener l);
125
126 /**
127 * Removes a <code>ChangeListener</code> from the model's listener list.
128 *
129 * @param l the ChangeListener to remove
130 * @see #addChangeListener
131 */
132 void removeChangeListener(ChangeListener l);
133 }
|