I committed this patch to fill in some API documentation:
2006-02-09 David Gilbert <[EMAIL PROTECTED]>
* javax/swing/SpinnerDateModel.java: Updated API docs all over,
* javax/swing/SpinnerNumberModel.java: Likewise.
Regards,
Dave
Index: javax/swing/SpinnerDateModel.java
===================================================================
RCS file: /sources/classpath/classpath/javax/swing/SpinnerDateModel.java,v
retrieving revision 1.5
diff -u -r1.5 SpinnerDateModel.java
--- javax/swing/SpinnerDateModel.java 9 Feb 2006 22:35:51 -0000 1.5
+++ javax/swing/SpinnerDateModel.java 9 Feb 2006 22:42:46 -0000
@@ -1,5 +1,5 @@
/* SpinnerDateModel.java --
- Copyright (C) 2002, 2004 Free Software Foundation, Inc.
+ Copyright (C) 2002, 2004, 2006 Free Software Foundation, Inc.
This file is part of GNU Classpath.
@@ -42,21 +42,37 @@
import java.util.Calendar;
import java.util.Date;
+import javax.swing.event.ChangeEvent;
+
/**
- * SpinnerDateModel
- *
- * Implements a SpinnerModel for dates, rotating a calendar field such as
- * month, year, day, week, hour, minute.
+ * A date model used by the [EMAIL PROTECTED] JSpinner} component. This
implements a
+ * spinner model for dates, rotating a calendar field such as month, year,
+ * day, week, hour, minute.
*
* @author Sven de Marothy
- * @version 0.1 (first implementation)
+ * @since 1.4
*/
public class SpinnerDateModel extends AbstractSpinnerModel
implements Serializable
{
+ /** The current date. */
private Calendar date;
+
+ /**
+ * The start or earliest permitted date (<code>null</code> for no
+ * minimum).
+ */
private Comparable start;
+
+ /**
+ * The end or latest permitted date (<code>null</code> for no
+ * maximum).
+ */
private Comparable end;
+
+ /**
+ * The calendar field used to calculate the previous or next date.
+ */
private int calendarField;
/**
@@ -66,8 +82,9 @@
private static final long serialVersionUID = -4802518107105940612L;
/**
- * Constructs a SpinnerDateModel using the current date,
- * no start or end limit, and Calendar.DAY_OF_MONTH as the calendar field.
+ * Constructs a <code>SpinnerDateModel</code> using the current date,
+ * no start or end limit, and [EMAIL PROTECTED] Calendar#DAY_OF_MONTH} as
the calendar
+ * field.
*/
public SpinnerDateModel()
{
@@ -101,7 +118,10 @@
}
/**
- * Returns the value of the Calendar field to spin.
+ * Returns the [EMAIL PROTECTED] Calendar} field used to calculate the
previous and
+ * next dates in the sequence.
+ *
+ * @return The date field code.
*/
public int getCalendarField()
{
@@ -109,8 +129,9 @@
}
/**
- * Returns the current date in the sequence.
- * @return a <code>Date</code> object.
+ * Returns the current date.
+ *
+ * @return The current date.
*/
public Date getDate()
{
@@ -118,8 +139,9 @@
}
/**
- * Returns the starting limit of the SpinnerModel.
- * @return a Date object, or <code>null</code> if there is no limit.
+ * Returns the start date, or <code>null</code> if there is no minimum date.
+ *
+ * @return The start date.
*/
public Comparable getStart()
{
@@ -127,8 +149,9 @@
}
/**
- * Returns the end limit of the SpinnerModel.
- * @return a Date object, or <code>null</code> if there is no limit.
+ * Returns the end date, or <code>null</code> if there is no maximum date.
+ *
+ * @return The end date.
*/
public Comparable getEnd()
{
@@ -136,9 +159,10 @@
}
/**
- * Returns the current date in the sequence,
- * this method returns the same as <code>getDate()</code>.
- * @return a <code>Date</code> object.
+ * Returns the current date in the sequence (this method returns the same as
+ * [EMAIL PROTECTED] #getDate()}.
+ *
+ * @return The current date.
*/
public Object getValue()
{
@@ -147,8 +171,10 @@
/**
* Returns the next date in the sequence, or <code>null</code> if the
- * next date is equal to or past the end limit.
- * @return a Date object, or <code>null</code>.
+ * next date is after the end date. The current date is not changed.
+ *
+ * @return The next date, or <code>null</code> if the current value is
+ * the latest date represented by the model.
*/
public Object getNextValue()
{
@@ -164,8 +190,11 @@
/**
* Returns the previous date in the sequence, or <code>null</code> if the
- * next date is equal to or past the end limit.
- * @return a Date object, or <code>null</code>.
+ * previous date is prior to the start date. The current date is not
+ * changed.
+ *
+ * @return The previous date, or <code>null</code> if the current value is
+ * the earliest date represented by the model.
*/
public Object getPreviousValue()
{
@@ -180,9 +209,14 @@
}
/**
- * Sets the date field to change. It must be a valid Calendar field,
- * excluding Calendar.ZONE_OFFSET and Calendar.DST_OFFSET.
- * @param calendarField - the calendar field to set.
+ * Sets the date field to change when calculating the next and previous
+ * values. It must be a valid [EMAIL PROTECTED] Calendar} field, excluding
+ * [EMAIL PROTECTED] Calendar#ZONE_OFFSET} and [EMAIL PROTECTED]
Calendar#DST_OFFSET}.
+ *
+ * @param calendarField the calendar field to set.
+ *
+ * @throws IllegalArgumentException if <code>calendarField</code> is not
+ * a valid code.
*/
public void setCalendarField(int calendarField)
{
@@ -199,10 +233,14 @@
}
/**
- * Sets the starting date limit for the sequence.
- *
- * @param start - a Date object of the limit date,
- * or <code>null</code> for no limit.
+ * Sets the start date and, if the new date is different to the old date,
+ * sends a [EMAIL PROTECTED] ChangeEvent} to all registered listeners. A
+ * <code>null</code> date is interpreted as "no start date". No check
+ * is made to ensure that the new start date is on or before the current
+ * date - the caller is responsible for ensuring that this relationship
+ * holds.
+ *
+ * @param start the new start date (<code>null</code> permitted).
*/
public void setStart(Comparable start)
{
@@ -214,10 +252,13 @@
}
/**
- * Sets the end date limit for the sequence.
- *
- * @param end - a Date object of the limit date,
- * or <code>null</code> for no limit.
+ * Sets the end date and, if the new date is different to the old date,
+ * sends a [EMAIL PROTECTED] ChangeEvent} to all registered listeners. A
+ * <code>null</code> date is interpreted as "no end date". No check
+ * is made to ensure that the new end date is on or after the current date -
+ * the caller is responsible for ensuring that this relationship holds.
+ *
+ * @param end the new end date (<code>null</code> permitted).
*/
public void setEnd(Comparable end)
{
@@ -229,9 +270,14 @@
}
/**
- * Sets the current date in the sequence.
+ * Sets the current date and, if the new value is different to the old
+ * value, sends a [EMAIL PROTECTED] ChangeEvent} to all registered listeners.
*
- * @param value - a Date object.
+ * @param value the new date (<code>null</code> not permitted, must be an
+ * instance of <code>Date</code>).
+ *
+ * @throws IllegalArgumentException if <code>value</code> is not an instance
+ * of <code>Date</code>.
*/
public void setValue(Object value)
{
Index: javax/swing/SpinnerNumberModel.java
===================================================================
RCS file: /sources/classpath/classpath/javax/swing/SpinnerNumberModel.java,v
retrieving revision 1.9
diff -u -r1.9 SpinnerNumberModel.java
--- javax/swing/SpinnerNumberModel.java 9 Feb 2006 22:35:51 -0000 1.9
+++ javax/swing/SpinnerNumberModel.java 9 Feb 2006 22:42:46 -0000
@@ -1,5 +1,5 @@
/* SpinnerNumberModel.java --
- Copyright (C) 2002, 2004 Free Software Foundation, Inc.
+ Copyright (C) 2002, 2004, 2006 Free Software Foundation, Inc.
This file is part of GNU Classpath.
@@ -39,11 +39,13 @@
import java.io.Serializable;
+import javax.swing.event.ChangeEvent;
+
/**
- * SpinnerNumberModel
+ * A model used by the [EMAIL PROTECTED] JSpinner} component.
*
* @author Ka-Hing Cheung
- * @version 1.0
+ * @since 1.4
*/
public class SpinnerNumberModel extends AbstractSpinnerModel
implements Serializable
@@ -53,16 +55,16 @@
*/
private static final long serialVersionUID = 7279176385485777821L;
- /** DOCUMENT ME! */
+ /** The current value. */
private Number value;
- /** DOCUMENT ME! */
+ /** The minimum value (or <code>null</code>). */
private Comparable minimum;
- /** DOCUMENT ME! */
+ /** The maximum value (or <code>null</code>). */
private Comparable maximum;
- /** DOCUMENT ME! */
+ /** The step size. */
private Number stepSize;
/**
@@ -75,14 +77,14 @@
}
/**
- * Creates a <code>SpinnerNumberModel</code> with double precision
+ * Creates a <code>SpinnerNumberModel</code> with double precision.
*
* @param value the initial value
* @param minimum the minimum value
* @param maximum the maximum value
* @param stepSize the step size
- * @throws IllegalArgumentException if minimum <= value <= maximum
does not
- * hold
+ * @throws IllegalArgumentException if minimum <= value <= maximum
does
+ * not hold.
*/
public SpinnerNumberModel(double value, double minimum, double maximum,
double stepSize)
@@ -92,14 +94,14 @@
}
/**
- * Creates a <code>SpinnerNumberModel</code> with integer precision
+ * Creates a <code>SpinnerNumberModel</code> with integer precision.
*
* @param value the initial value
* @param minimum the minimum value
* @param maximum the maximum value
* @param stepSize the step size
- * @throws IllegalArgumentException if minimum <= value <= maximum
does not
- * hold
+ * @throws IllegalArgumentException if minimum <= value <= maximum
does
+ * not hold.
*/
public SpinnerNumberModel(int value, int minimum, int maximum, int stepSize)
{
@@ -108,16 +110,19 @@
}
/**
- * Creates a <code>SpinnerNumberModel</code> with <code>Number</code>s and
- * <code>Comparable</code>s.
+ * Creates a <code>SpinnerNumberModel</code> with the given attributes.
*
- * @param value the initial value
- * @param minimum the minimum value, if null there's no minimum
- * @param maximum the maximum value, if null there's no maximum
- * @param stepSize the step size
+ * @param value the initial value.
+ * @param minimum the minimum value (<code>null</code> permitted).
+ * @param maximum the maximum value (<code>null</code> permitted).
+ * @param stepSize the step size.
*
* @throws IllegalArgumentException if minimum <= value <= maximum
* does not hold
+ * @throws IllegalArgumentException if <code>value</code> is
+ * <code>null</code>.
+ * @throws IllegalArgumentException if <code>stepSize</code> is
+ * <code>null</code>.
*/
public SpinnerNumberModel(Number value, Comparable minimum,
Comparable maximum, Number stepSize)
@@ -144,12 +149,14 @@
}
/**
- * Sets the new value and fire a change event
+ * Sets the current value and, if the new value is different to the old
+ * value, sends a [EMAIL PROTECTED] ChangeEvent} to all registered listeners.
*
- * @param value the new value
+ * @param value the new value (<code>null</code> not permitted, must be an
+ * instance of <code>Number</code>).
*
- * @throws IllegalArgumentException if minimum <= value <= maximum
- * does not hold
+ * @throws IllegalArgumentException if <code>value</code> is not an instance
+ * of <code>Number</code>.
*/
public void setValue(Object value)
{
@@ -164,9 +171,9 @@
}
/**
- * Gets the current value
+ * Returns the current value.
*
- * @return the current value
+ * @return The current value.
*/
public Object getValue()
{
@@ -174,10 +181,12 @@
}
/**
- * Gets the next value without changing the current value, or null if the
- * current value is maximum.
+ * Returns the next value, or <code>null</code> if adding the step size to
+ * the current value results in a value greater than the maximum value.
+ * The current value is not changed.
*
- * @return the next value
+ * @return The next value, or <code>null</code> if the current value is the
+ * maximum value represented by this model.
*/
public Object getNextValue()
{
@@ -200,10 +209,12 @@
}
/**
- * Gets the previous value without changing the current value, or null if
- * the current value is minimum.
+ * Returns the previous value, or <code>null</code> if subtracting the
+ * step size from the current value results in a value less than the minimum
+ * value. The current value is not changed.
*
- * @return the previous value
+ * @return The previous value, or <code>null</code> if the current value
+ * is the minimum value represented by this model.
*/
public Object getPreviousValue()
{
@@ -226,20 +237,35 @@
}
/**
- * DOCUMENT ME!
+ * Returns the current value.
*
- * @return DOCUMENT ME!
+ * @return The current value.
*/
public Number getNumber()
{
return value;
}
+ /**
+ * Returns the minimum value, or <code>null</code> if there is no minimum.
+ *
+ * @return The minimum value.
+ */
public Comparable getMinimum()
{
return minimum;
}
+ /**
+ * Sets the minimum value and, if the new value is different to the old
+ * value, sends a [EMAIL PROTECTED] ChangeEvent} to all registered
listeners. A
+ * <code>null</code> value is interpreted as "no minimum value". No check
+ * is made to ensure that the new minimum is less than or equal to the
+ * current value, the caller is responsible for ensuring that this
+ * relationship holds.
+ *
+ * @param newMinimum the new minimum value (<code>null</code> permitted).
+ */
public void setMinimum(Comparable newMinimum)
{
if (minimum != null ? !minimum.equals(newMinimum) : newMinimum != null)
@@ -249,11 +275,26 @@
}
}
+ /**
+ * Returns the maximum value, or <code>null</code> if there is no maximum.
+ *
+ * @return The maximum value.
+ */
public Comparable getMaximum()
{
return maximum;
}
+ /**
+ * Sets the maximum value and, if the new value is different to the old
+ * value, sends a [EMAIL PROTECTED] ChangeEvent} to all registered
listeners. A
+ * <code>null</code> value is interpreted as "no maximum value". No check
+ * is made to ensure that the new maximum is greater than or equal to the
+ * current value, the caller is responsible for ensuring that this
+ * relationship holds.
+ *
+ * @param newMaximum the new maximum (<code>null</code> permitted).
+ */
public void setMaximum(Comparable newMaximum)
{
if (maximum != null ? !maximum.equals(newMaximum) : newMaximum != null)
@@ -263,11 +304,25 @@
}
}
+ /**
+ * Returns the step size.
+ *
+ * @return The step size.
+ */
public Number getStepSize()
{
return stepSize;
}
+ /**
+ * Sets the step size and, if the new step size is different to the old
+ * step size, sends a [EMAIL PROTECTED] ChangeEvent} to all registered
listeners.
+ *
+ * @param newStepSize the new step size (<code>null</code> not permitted).
+ *
+ * @throws IllegalArgumentException if <code>newStepSize</code> is
+ * <code>null</code>.
+ */
public void setStepSize(Number newStepSize)
{
if (newStepSize == null)
