1 /*
2 * Copyright 2000-2002 Sun Microsystems, Inc. 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. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any 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</code> however there are some important differences:
35 * <ul>
36 * <li> The number of sequence elements isn't neccessarily 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</code> has three properties, only the first is read/write.
44 * <dl>
45 * <dt><code>value</code>
46 * <dd>The current element of the sequence.
47 *
48 * <dt><code>nextValue</code>
49 * <dd>The following element or null if <code>value</code> is the
50 * last element of the sequence.
51 *
52 * <dt><code>previousValue</code>
53 * <dd>The preceeding element or null if <code>value</code> is the
54 * first element of the sequence.
55 * </dl>
56 * When the the <code>value</code> property changes,
57 * <code>ChangeListeners</code> are notified. <code>SpinnerModel</code> may
58 * choose to notify the <code>ChangeListeners</code> 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</code> part of a <code>JSpinner</code>.
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</code> part of a <code>JSpinner</code>.
84 * If the <code>SpinnerModel</code> implementation doesn't support
85 * the specified value then an <code>IllegalArgumentException</code>
86 * is thrown. For example a <code>SpinnerModel</code> for numbers might
87 * only support values that are integer multiples of ten. In
88 * that case, <code>model.setValue(new Number(11))</code>
89 * would throw an exception.
90 *
91 * @throws IllegalArgumentException if <code>value</code> isn't allowed
92 * @see #getValue
93 */
94 void setValue(Object value);
95
96
97 /**
98 * Return the object in the sequence that comes after the object returned
99 * by <code>getValue()</code>. If the end of the sequence has been reached
100 * then return null. Calling this method does not effect <code>value</code>.
101 *
102 * @return the next legal value or null if one doesn't exist
103 * @see #getValue
104 * @see #getPreviousValue
105 */
106 Object getNextValue();
107
108
109 /**
110 * Return the object in the sequence that comes before the object returned
111 * by <code>getValue()</code>. If the end of the sequence has been reached then
112 * return null. Calling this method does not effect <code>value</code>.
113 *
114 * @return the previous legal value or null if one doesn't exist
115 * @see #getValue
116 * @see #getNextValue
117 */
118 Object getPreviousValue();
119
120
121 /**
122 * Adds a <code>ChangeListener</code> to the model's listener list. The
123 * <code>ChangeListeners</code> must be notified when models <code>value</code>
124 * changes.
125 *
126 * @param l the ChangeListener to add
127 * @see #removeChangeListener
128 */
129 void addChangeListener(ChangeListener l);
130
131
132 /**
133 * Removes a <code>ChangeListener</code> from the model's listener list.
134 *
135 * @param l the ChangeListener to remove
136 * @see #addChangeListener
137 */
138 void removeChangeListener(ChangeListener l);
139 }
Save This Page