001    /* SpinnerListModel.java -- A spinner model backed by a list or an array.
002       Copyright (C) 2004, 2005  Free Software Foundation, Inc.
003    
004    This file is part of GNU Classpath.
005    
006    GNU Classpath is free software; you can redistribute it and/or modify
007    it under the terms of the GNU General Public License as published by
008    the Free Software Foundation; either version 2, or (at your option)
009    any later version.
010    
011    GNU Classpath is distributed in the hope that it will be useful, but
012    WITHOUT ANY WARRANTY; without even the implied warranty of
013    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014    General Public License for more details.
015    
016    You should have received a copy of the GNU General Public License
017    along with GNU Classpath; see the file COPYING.  If not, write to the
018    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019    02110-1301 USA.
020    
021    Linking this library statically or dynamically with other modules is
022    making a combined work based on this library.  Thus, the terms and
023    conditions of the GNU General Public License cover the whole
024    combination.
025    
026    As a special exception, the copyright holders of this library give you
027    permission to link this library with independent modules to produce an
028    executable, regardless of the license terms of these independent
029    modules, and to copy and distribute the resulting executable under
030    terms of your choice, provided that you also meet, for each linked
031    independent module, the terms and conditions of the license of that
032    module.  An independent module is a module which is not derived from
033    or based on this library.  If you modify this library, you may extend
034    this exception to your version of the library, but you are not
035    obligated to do so.  If you do not wish to do so, delete this
036    exception statement from your version. */
037    
038    package javax.swing;
039    
040    import java.io.Serializable;
041    import java.util.ArrayList;
042    import java.util.Arrays;
043    import java.util.List;
044    
045    import javax.swing.event.ChangeEvent;
046    
047    /**
048     * An implementation of <code>SpinnerModel</code> which uses the values
049     * contained within a list or an array.  The backing list or array is
050     * only stored as a reference within the class.  As a result, changes
051     * made elsewhere to the members of the list or array are reflected by
052     * this model.
053     * <p>
054     *
055     * The model itself inherits a list of <code>ChangeListener</code>s from
056     * <code>AbstractSpinnerModel</code>.  As this code is unaware of changes
057     * made to the backing list or array, it is the responsibility of the
058     * application using the model to invoke <code>fireStateChanged()</code>,
059     * in order to notify any <code>ChangeListener</code>s, when the list or array
060     * changes.  The model handles notification when the reference itself
061     * is changed via <code>setList()</code> or when the current value is
062     * set directly using <code>setValue()</code>.
063     *
064     * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
065     * @see SpinnerModel
066     * @see AbstractSpinnerModel
067     * @see JSpinner
068     * @since 1.4
069     */
070    
071    public class SpinnerListModel extends AbstractSpinnerModel
072      implements Serializable
073    {
074      /**
075       * For compatability with Sun's JDK
076       */
077      private static final long serialVersionUID = 3358804052191994516L;
078    
079      /**
080       * The backing list for this model.
081       */
082      private List list;
083    
084      /**
085       * The current index in the list.
086       */
087      private transient int index;
088    
089      /**
090       * Constructs a default <code>SpinnerListModel</code>.  This
091       * is a model backed by a list containing only the single
092       * <code>String</code> element, "empty".
093       */
094      public SpinnerListModel()
095      {
096        List defaultList;
097    
098        // Create an empty list.
099        defaultList = new ArrayList();
100        // Add the string "empty".
101        defaultList.add("empty");
102        // Set the list.
103        setList(defaultList);
104      }
105    
106      /**
107       * Constructs a <code>SpinnerListModel</code> using the supplied list.
108       * The model maintains a reference to this list, and returns
109       * consecutive elements in response to calls to <code>getNextValue()</code>.
110       * The initial value is that at position 0, so an initial call
111       * to <code>getValue()</code> returns the same as <code>list.get(0)</code>.
112       *
113       * @param list The list to use for this model.
114       * 
115       * @throws IllegalArgumentException if the list is null or contains no
116       *         elements.
117       *
118       * @see SpinnerListModel#getNextValue()
119       * @see SpinnerListModel#getValue()
120       */ 
121      public SpinnerListModel(List<?> list)
122      {
123        // Retain a reference to the valid list.
124        setList(list);
125      }
126    
127      /**
128       * Constructs a <code>SpinnerListModel</code> using the supplied array.
129       * The model stores a reference to the wrapper list returned by
130       * <code>Arrays.asList()</code>.  The wrapper list reflects modifications
131       * in the underlying array, so these changes will also be reflected
132       * by the model.  The model produces consecutive elements from the array
133       * in response to calls to <code>getNextValue()</code>.  The initial
134       * value returned by <code>getValue()</code> is the same as
135       * <code>array[0]</code>.
136       *
137       * @param array The array to use for this model.
138       *
139       * @throws IllegalArgumentException if the array is null or contains
140       *         no elements.
141       *
142       * @see Arrays#asList(Object[])
143       * @see SpinnerListModel#getNextValue()
144       * @see SpinnerListModel#getValue()
145       */
146      public SpinnerListModel(Object[] array)
147      {
148        // Check for a null or zero-sized array.
149        if (array == null || array.length == 0)
150          {
151            throw new IllegalArgumentException("The supplied array was invalid.");
152          }
153    
154            // Retain a reference to a wrapper around the valid array. 
155            // The array, in list form, will be tested again here, but we can't really
156            // avoid this -- a null value to Arrays.asList will throw a
157        // NullPointerException.
158        setList(Arrays.asList(array));
159      }
160    
161      /**
162       * Returns the backing list for this model.
163       *
164       * @return The backing list.
165       */
166      public List<?> getList()
167      {
168        return list;
169      }
170        
171      /**
172       * Returns the next value from the list, which is the same as the element
173       * stored at the current index + 1.  Null is returned if there are no more
174       * values to be returned (the end of the list has been reached).  An
175       * ambiguity can occur here, as null may also be returned as a valid list
176       * element.  This operation does not change the current value.
177       *
178       * @return The next value from the list or null.
179       */
180      public Object getNextValue()
181      {
182        // Check for a next value.
183        if (index < (list.size() - 1))
184          // Return the element at the next index.
185          return list.get(index + 1);
186        else
187          // Return null as this is the end of the list.
188          return null;
189        }
190    
191      /**
192       * Returns the previous value from the list, which is the same as the element
193       * stored at the current index - 1.  Null is returned if there are no more
194       * values to be returned (the start of the list has been reached).  An
195       * ambiguity can occur here, as null may also be returned as a valid list
196       * element.  This operation does not change the current value.
197       *
198       * @return The previous value from the list or null.
199       */
200      public Object getPreviousValue()
201      {
202        // Check for a previous value.
203        if (index > 0) 
204          // Return the element at the previous position.
205          return list.get(index - 1);
206            else
207          // Return null as this is the start of the list.
208          return null;
209        }
210    
211      /**
212       * Returns the current value of the model.  Initially, this will
213       * be the element at position 0.  On later invocations, this will
214       * be the last element returned by <code>getNextValue()</code>
215       * or <code>getPreviousValue()</code>.
216       *
217       * @return The current value.
218       *
219       * @see SpinnerListModel#getPreviousValue()
220       * @see SpinnerListModel#getNextValue()
221       */
222      public Object getValue()
223      {
224        return list.get(index);
225      }
226    
227      /**
228       * Changes the backing list for this model.  The model only stores
229       * a reference to the list, so any changes made to the list elsewhere
230       * will be reflected in the values returned by the model.  A
231       * <code>ChangeEvent</code> is fired if the list being used actually
232       * changes (i.e. the new list is not referentially equal (!=) to the
233       * old one).
234       *
235       * @param list The new list to use.
236       *
237       * @throws IllegalArgumentException if the list is null or contains
238       *         no elements.
239       *
240       * @see ChangeEvent
241       */
242      public void setList(List<?> list)
243      {
244        // Check for null or zero size list.
245        if (list == null || list.size() == 0)
246          throw new IllegalArgumentException("The supplied list was invalid.");
247    
248        // Check for a change of referenced list.
249        if (this.list != list)
250          {
251            // Store the new list.
252            this.list = list;
253            // Notify listeners of a change.
254            fireStateChanged();
255          }
256        // We reset the other values in either case.
257        // Set the index to 0.
258        index = 0;
259      }
260    
261      /**
262       * Sets the current value of the model to be the one supplied.
263       * The value must exist within the backing list in order for
264       * the change to take place.  Otherwise, an exception is thrown.
265       * The value used is the first occurrence of the value within
266       * the backing list.  Listeners are notified of this change.
267       * Following the change, <code>getNextValue()</code> and
268       * <code>getPreviousValue()</code> return the objects following
269       * and prior to the supplied value, respectively. 
270       *
271       * @param value The requested new value of the list.
272       *
273       * @throws IllegalArgumentException if the supplied value does
274       *         not exist in the backing list.
275       *
276       * @see SpinnerListModel#getPreviousValue()
277       * @see SpinnerListModel#getNextValue()
278       */
279      public void setValue(Object value)
280      {
281        int valueIndex;
282    
283        // Search for the value in the list.
284        valueIndex = list.indexOf(value);
285        // Check for the value being found.
286        if (valueIndex == -1)
287          throw new IllegalArgumentException("The supplied value does not "
288                                             + "exist in this list");
289        // Make the indices match.
290        index = valueIndex;
291        // Notify the listeners.
292        fireStateChanged();
293      }
294    
295    }