FYI: [gui] Add SpinnerListModel and documentation from GNUClasspath

[Mark Wielaard <mark at klomp dot org>]

Hi,

This adds SpinnerListModel and some documentation from GNU Classpath.

2004-09-23  Mark Wielaard  <mark@klomp.org>

	* Makefile.am: Add javax/swing/SpinnerListModel.java.
	* Makefile.in: Regenerated.

2004-09-23  Andrew John Hughes  <gnu_andrew@member.fsf.org>

       * javax/swing/SpinnerListModel.java, javax/swing/SpinnerModel.java
       Implemented SpinnerListModel.  Added documentation to
       SpinnerModel.

Committed to the gui branch.

Mark

Index: Makefile.am
===================================================================
RCS file: /cvs/gcc/gcc/libjava/Makefile.am,v
retrieving revision 1.361.2.45
diff -u -r1.361.2.45 Makefile.am
--- Makefile.am	21 Sep 2004 05:30:45 -0000	1.361.2.45
+++ Makefile.am	23 Sep 2004 18:21:23 -0000
@@ -1467,6 +1467,7 @@
 javax/swing/ListSelectionModel.java \
 javax/swing/LookAndFeel.java \
 javax/swing/Scrollable.java \
+javax/swing/SpinnerListModel.java \
 javax/swing/SpinnerModel.java \
 javax/swing/SpinnerNumberModel.java \
 javax/swing/Spring.java \
Index: javax/swing/SpinnerListModel.java
===================================================================
RCS file: javax/swing/SpinnerListModel.java
diff -N javax/swing/SpinnerListModel.java
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ javax/swing/SpinnerListModel.java	23 Sep 2004 18:21:25 -0000
@@ -0,0 +1,296 @@
+/* SpinnerListModel.java -- A spinner model backed by a list or an array.
+   Copyright (C) 2004 Free Software Foundation, Inc.
+
+This file is part of GNU Classpath.
+
+GNU Classpath is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2, or (at your option)
+any later version.
+
+GNU Classpath is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with GNU Classpath; see the file COPYING.  If not, write to the
+Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
+02111-1307 USA.
+
+Linking this library statically or dynamically with other modules is
+making a combined work based on this library.  Thus, the terms and
+conditions of the GNU General Public License cover the whole
+combination.
+
+As a special exception, the copyright holders of this library give you
+permission to link this library with independent modules to produce an
+executable, regardless of the license terms of these independent
+modules, and to copy and distribute the resulting executable under
+terms of your choice, provided that you also meet, for each linked
+independent module, the terms and conditions of the license of that
+module.  An independent module is a module which is not derived from
+or based on this library.  If you modify this library, you may extend
+this exception to your version of the library, but you are not
+obligated to do so.  If you do not wish to do so, delete this
+exception statement from your version. */
+
+package javax.swing;
+
+import java.io.Serializable;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.List;
+
+/**
+ * An implementation of <code>SpinnerModel</code> which uses the values
+ * contained within a list or an array.  The backing list or array is
+ * only stored as a reference within the class.  As a result, changes
+ * made elsewhere to the members of the list or array are reflected by
+ * this model.
+ * <p>
+ *
+ * The model itself inherits a list of <code>ChangeListener</code>s from
+ * <code>AbstractSpinnerModel</code>.  As this code is unaware of changes
+ * made to the backing list or array, it is the responsibility of the
+ * application using the model to invoke <code>fireStateChanged()</code>,
+ * in order to notify any <code>ChangeListener</code>s, when the list or array
+ * changes.  The model handles notification when the reference itself
+ * is changed via <code>setList()</code> or when the current value is
+ * set directly using <code>setValue()</code>.
+ *
+ * @author Andrew John Hughes <address@hidden>
+ * @see SpinnerModel
+ * @see AbstractSpinnerModel
+ * @see JSpinner
+ * @since 1.4
+ */
+
+public class SpinnerListModel
+    extends AbstractSpinnerModel
+    implements Serializable
+{
+    /**
+     * FIXME: SpinnerListModel needs same serial version as JDK
+     */
+    // private static final long serialVersionUID = L;
+
+    /**
+     * The backing list for this model.
+     */
+    private List list;
+
+    /**
+     * The current index in the list.
+     */
+    private transient int index;
+
+    /**
+     * Constructs a default <code>SpinnerListModel</code>.  This
+     * is a model backed by a list containing only the single
+     * <code>String</code> element, "empty".
+     */
+    public SpinnerListModel()
+    {
+	List defaultList;
+
+	/* Create an empty list */
+	defaultList = new ArrayList();
+	/* Add the string "empty" */
+	defaultList.add("empty");
+	/* Set the list */
+	setList(defaultList);
+    }
+
+    /**
+     * Constructs a <code>SpinnerListModel</code> using the supplied list.
+     * The model maintains a reference to this list, and returns
+     * consecutive elements in response to calls to <code>getNextValue()</code>.
+     * The initial value is that at position 0, so an initial call
+     * to <code>getValue()</code> returns the same as <code>list.get(0)</code>.
+     *
+     * @param list The list to use for this model.
+     * @throws IllegalArgumentException if the list is null or contains no
+     *         elements.
+     * @see SpinnerListModel#getNextValue()
+     * @see SpinnerListModel#getValue()
+     */ 
+    public SpinnerListModel(List list)
+    {
+	/* Retain a reference to the valid list */
+        setList(list);
+    }
+
+    /**
+     * Constructs a <code>SpinnerListModel</code> using the supplied array.
+     * The model stores a reference to the wrapper list returned by
+     * <code>Arrays.asList()</code>.  The wrapper list reflects modifications
+     * in the underlying array, so these changes will also be reflected
+     * by the model.  The model produces consecutive elements from the array
+     * in response to calls to <code>getNextValue()</code>.  The initial
+     * value returned by <code>getValue()</code> is the same as
+     * <code>array[0]</code>.
+     *
+     * @param array The array to use for this model.
+     * @throws IllegalArgumentException if the array is null or contains
+     *         no elements.
+     * @see Arrays#asList(Object[])
+     * @see SpinnerListModel#getNextValue()
+     * @see SpinnerListModel#getValue()
+     */
+    public SpinnerListModel(Object[] array)
+    {
+	/* Check for a null or zero-sized array */
+	if (array == null || array.length == 0)
+	    {
+		throw new IllegalArgumentException("The supplied array was invalid.");
+	    }
+	/* 
+	   Retain a reference to a wrapper around the valid array 
+	   The array, in list form, will be tested again here, but we can't really
+	   avoid this -- a null value to Arrays.asList will throw a NullPointerException
+	*/ 
+	setList(Arrays.asList(array));
+    }
+
+    /**
+     * Returns the backing list for this model.
+     *
+     * @return The backing list.
+     */
+    public List getList()
+    {
+	return list;
+    }
+    
+    /**
+     * Returns the next value from the list, which is the same as the element
+     * stored at the current index + 1.  Null is returned if there are no more
+     * values to be returned (the end of the list has been reached).  An
+     * ambiguity can occur here, as null may also be returned as a valid list
+     * element.  This operation does not change the current value.
+     *
+     * @return The next value from the list or null.
+     */
+    public Object getNextValue()
+    {
+	/* Check for a next value */
+	if (index < (list.size() - 1))
+	    {
+		/* Return the element at the next index */
+		return list.get(index + 1);
+	    }
+	else
+	    {
+		/* Return null as this is the end of the list */
+		return null;
+	    }
+    }
+
+    /**
+     * Returns the previous value from the list, which is the same as the element
+     * stored at the current index - 1.  Null is returned if there are no more
+     * values to be returned (the start of the list has been reached).  An
+     * ambiguity can occur here, as null may also be returned as a valid list
+     * element.  This operation does not change the current value.
+     *
+     * @return The previous value from the list or null.
+     */
+    public Object getPreviousValue()
+    {
+	/* Check for a previous value. */
+	if (index > 0) 
+	    {
+		/* Return the element at the previous position */
+		return list.get(index - 1);
+	    }
+	else
+	    {
+		/* Return null as this is the start of the list */
+		return null;
+	    }
+    }
+
+    /**
+     * Returns the current value of the model.  Initially, this will
+     * be the element at position 0.  On later invocations, this will
+     * be the last element returned by <code>getNextValue()</code>
+     * or <code>getPreviousValue()</code>.
+     *
+     * @return The current value.
+     * @see SpinnerListModel#getPreviousValue()
+     * @see SpinnerListModel#getNextValue()
+     */
+    public Object getValue()
+    {
+	return list.get(index);
+    }
+
+    /**
+     * Changes the backing list for this model.  The model only stores
+     * a reference to the list, so any changes made to the list elsewhere
+     * will be reflected in the values returned by the model.  A
+     * <code>ChangeEvent</code> is fired if the list being used actually
+     * changes (i.e. the new list is not referentially equal (!=) to the
+     * old one).
+     *
+     * @param list The new list to use.
+     * @throws IllegalArgumentException if the list is null or contains
+     *         no elements.
+     * @see ChangeEvent
+     */
+    public void setList(List list)
+    {
+	/* Check for null or zero size list */
+	if (list == null || list.size() == 0)
+	    {
+		throw new IllegalArgumentException("The supplied list was invalid.");
+	    }
+	/* Check for a change of referenced list */
+	if (this.list != list)
+	    {
+		/* Store the new list */
+		this.list = list;
+		/* Notify listeners of a change */
+		fireStateChanged();
+	    }
+	/* We reset the other values in either case */
+	/* Set the index to 0 */
+	index = 0;
+    }
+
+    /**
+     * Sets the current value of the model to be the one supplied.
+     * The value must exist within the backing list in order for
+     * the change to take place.  Otherwise, an exception is thrown.
+     * The value used is the first occurrence of the value within
+     * the backing list.  Listeners are notified of this change.
+     * Following the change, <code>getNextValue()</code> and
+     * <code>getPreviousValue()</code> return the objects following
+     * and prior to the supplied value, respectively. 
+     *
+     * @param value The requested new value of the list.
+     * @throws IllegalArgumentException if the supplied value does
+     *         not exist in the backing list.
+     * @see SpinnerListModel#getPreviousValue()
+     * @see SpinnerListModel#getNextValue()
+     */
+    public void setValue(Object value)
+    {
+	int valueIndex;
+
+	/* Search for the value in the list */
+	valueIndex = list.indexOf(value);
+	/* Check for the value being found */
+	if (valueIndex == -1)
+	    {
+		throw new IllegalArgumentException("The supplied value does not "
+						   + "exist in this list");
+	    }
+	/* Make the indices match */
+	index = valueIndex;
+	/* Notify the listeners */
+	fireStateChanged();
+    }
+
+}
Index: javax/swing/SpinnerModel.java
===================================================================
RCS file: /cvs/gcc/gcc/libjava/javax/swing/SpinnerModel.java,v
retrieving revision 1.2
diff -u -r1.2 SpinnerModel.java
--- javax/swing/SpinnerModel.java	12 Oct 2003 13:20:49 -0000	1.2
+++ javax/swing/SpinnerModel.java	23 Sep 2004 18:21:25 -0000
@@ -45,10 +45,66 @@
  */
 public interface SpinnerModel
 {
-  void setValue (Object value);
-  public Object getValue ();
-  public Object getNextValue ();
-  public Object getPreviousValue ();
-  void addChangeListener (ChangeListener listener);
-  void removeChangeListener (ChangeListener listener);
+
+  /**
+   * Sets the current value of the model to that specified.
+   * Implementations can choose to refuse to accept the value
+   * and throw an exception instead.  For example, a date model
+   * may throw invalid dates, or a list model may throw out
+   * values which don't exist in the underlying list.  Models
+   * may also throw out unusual values, such as null.  The decision
+   * is left to the discretion of the implementator.  If the
+   * operation succeeds, the implementation should also notify
+   * any registered <code>ChangeListener</code>s.
+   *
+   * @param value The new value of the model.
+   * @throws IllegalArgumentException if the model does not accept
+   *         the given value.
+   */
+  void setValue(Object value);
+
+  /**
+   * Returns the current value of the model.
+   *
+   * @return The current value.
+   */
+  public Object getValue();
+
+  /**
+   * Returns the next value from the model.  If the model is bounded,
+   * this method may return null when the upper bound is met.
+   * The current value is not changed.
+   *
+   * @return The next value, or null if there are no more values
+   *         to retrieve.
+   */
+  public Object getNextValue();
+
+  /**
+   * Returns the previous value from the model.  If the model is
+   * bounded, this method may return null when the lower bound is
+   * met.  The current value is not changed.
+   *
+   * @return The previous value, or null if there are no more
+   *         values to retrieve.
+   */
+  public Object getPreviousValue();
+
+  /**
+   * Adds a <code>ChangeListener</code> to the list of registered
+   * listeners.  Each listener is notified when the current value
+   * is changed.
+   *
+   * @param listener The new listener to register.
+   */
+  void addChangeListener(ChangeListener listener);
+
+  /**
+   * Removes a given <code>ChangeListener</code> from the list
+   * of registered listeners.
+   *
+   * @param listener The listener to remove.
+   */
+  void removeChangeListener(ChangeListener listener);
+    
 }

Attachment: signature.asc
Description: This is a digitally signed message part