SpinnerModel


1   /*
2    * @(#)SpinnerModel.java    1.6 03/12/19
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package javax.swing;
9   
10  import java.awt.event.*;
11  import javax.swing.event.*;
12  
13  
14  /**
15   * A model for a potentially unbounded sequence of object values.  This model
16   * is similar to <code>ListModel</code> however there are some important differences:
17   * <ul>
18   * <li> The number of sequence elements isn't neccessarily bounded.
19   * <li> The model doesn't support indexed random access to sequence elements.
20   *      Only three sequence values are accessible at a time: current, next and
21   *      previous.
22   * <li> The current sequence element, can be set.
23   * </ul>
24   * <p>
25   * A <code>SpinnerModel</code> has three properties, only the first is read/write.
26   * <dl>
27   *   <dt><code>value</code>
28   *   <dd>The current element of the sequence.  
29   * 
30   *   <dt><code>nextValue</code>
31   *   <dd>The following element or null if <code>value</code> is the 
32   *     last element of the sequence.
33   * 
34   *   <dt><code>previousValue</code>
35   *   <dd>The preceeding element or null if <code>value</code> is the 
36   *     first element of the sequence.
37   * </dl>
38   * When the the <code>value</code> property changes, 
39   * <code>ChangeListeners</code> are notified.  <code>SpinnerModel</code> may
40   * choose to notify the <code>ChangeListeners</code> under other circumstances.
41   * 
42   * @see JSpinner
43   * @see AbstractSpinnerModel
44   * @see SpinnerListModel
45   * @see SpinnerNumberModel
46   * @see SpinnerDateModel
47   * 
48   * @version 1.6 12/19/03
49   * @author Hans Muller
50   * @since 1.4
51   */
52  public interface SpinnerModel 
53  {
54      /**
55       * The <i>current element</i> of the sequence.  This element is usually
56       * displayed by the <code>editor</code> part of a <code>JSpinner</code>.
57       * 
58       * @return the current spinner value.
59       * @see #setValue
60       */
61      Object   getValue();
62  
63  
64      /**
65       * Changes current value of the model, typically this value is displayed 
66       * by the <code>editor</code> part of a  <code>JSpinner</code>.  
67       * If the <code>SpinnerModel</code> implementation doesn't support 
68       * the specified value then an <code>IllegalArgumentException</code> 
69       * is thrown.  For example a <code>SpinnerModel</code> for numbers might 
70       * only support values that are integer multiples of ten. In
71       * that case, <code>model.setValue(new Number(11))</code>
72       * would throw an exception.
73       * 
74       * @throws IllegalArgumentException if <code>value</code> isn't allowed
75       * @see #getValue
76       */
77      void setValue(Object   value);
78  
79  
80      /**
81       * Return the object in the sequence that comes after the object returned 
82       * by <code>getValue()</code>. If the end of the sequence has been reached 
83       * then return null.  Calling this method does not effect <code>value</code>.
84       * 
85       * @return the next legal value or null if one doesn't exist
86       * @see #getValue
87       * @see #getPreviousValue
88       */
89      Object   getNextValue();
90  
91  
92      /**
93       * Return the object in the sequence that comes before the object returned 
94       * by <code>getValue()</code>.  If the end of the sequence has been reached then 
95       * return null. Calling this method does not effect <code>value</code>.
96       * 
97       * @return the previous legal value or null if one doesn't exist
98       * @see #getValue
99       * @see #getNextValue
100      */
101     Object   getPreviousValue();
102 
103 
104     /**
105      * Adds a <code>ChangeListener</code> to the model's listener list.  The 
106      * <code>ChangeListeners</code> must be notified when models <code>value</code> 
107      * changes.
108      *
109      * @param l the ChangeListener to add
110      * @see #removeChangeListener
111      */
112     void addChangeListener(ChangeListener l);
113 
114 
115     /**
116      * Removes a <code>ChangeListener</code> from the model's listener list.
117      *
118      * @param l the ChangeListener to remove
119      * @see #addChangeListener
120      */
121     void removeChangeListener(ChangeListener l);
122 }
123
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags