7.9 Spinner Models

The javax.swing package includes several pre-built models for many common data types suited to spinners. Figure 7-15 shows the hierarchy of these models.

Figure 7-15. SpinnerModel class diagram

7.9.1 The SpinnerModel Interface

The SpinnerModel interface includes methods required to successfully store and retrieve spinner data. It includes a read/write value and next and previous properties, and it forces implementing models (such as AbstractSpinnerModel) to support a ChangeListener.

7.9.1.1 Properties

Not surprisingly, the properties for SpinnerModel are centered on the value being shown in the spinner. Notice in Table 7-17 that the model stores only the current value and the next/previous values. The actual list (or other object) behind these values is not part of the model.

Table 7-17. SpinnerModel properties
Property	Data type	get	set
nextValue	Object	·
previousValue	Object	·
value	Object	·	·

7.9.1.2 Events

Any changes to the selected value should be reported through ChangeEvent objects.

public void addChangeListener(ChangeListener l)
public void removeChangeListener(ChangeListener l): Add or remove a specific listener for ChangeEvent notifications from the component.

7.9.2 The AbstractSpinnerModel Class

The AbstractSpinnerModel class implements the event parts of the SpinnerModel. Implementations of addChangeListener( ), removeChangeListener( ), and getChange-Listeners( ) are all present. Two expected methods, fireStateChange( ) and get-Listeners( ), have been added. All the other models subclass AbstractSpinnerModel, as shown in Figure 7-15.

7.9.3 The SpinnerDateModel

If you're retrieving dates from users, a date spinner can make the input process much simpler. You can supply minimum and maximum dates along with an increment value (to increment by day, week, month, year, etc.).

7.9.3.1 Properties

Table 7-18 shows the properties for SpinnerDateModel. Apart from the properties inherited from AbstractSpinnerModel, start and end properties have been added to make it possible to work within a bounded range of dates. Either of these properties can be set to null to indicate that you do not want a minimum or maximum. The calendarField property determines the increment/decrement step size and uses constants defined in the java.util.Calendar class. The valid step sizes are shown in Table 7-19. The date property is a convenience property that allows you to retrieve the current value of the spinner as a Date object.

Table 7-18. SpinnerDateModel properties
Property	Data type	get	set	Default value
calendarField	int	·	·	Calendar.DAY_OF_MONTH
date	java.util.Date	·		Current date
end	Comparable	·	·	`null` (no end)
nextValue^o	Object	·
previousValue^o	Object	·
start	Comparable	·	·	`null` (no start)
value^o	Object	·	·
^ooverridden

Table 7-19. Calendar constants for SpinnerDateModel
Calendar.AM_PM	Calendar.MILLISECOND
Calendar.DAY_OF_MONTH	Calendar.MINUTE
Calendar.DAY_OF_WEEK	Calendar.MONTH
Calendar.DAY_OF_WEEK_IN_MONTH	Calendar.SECOND
Calendar.DAY_OF_YEAR	Calendar.WEEK_OF_MONTH
Calendar.ERA	Calendar.WEEK_OF_YEAR
Calendar.HOUR	Calendar.YEAR
Calendar.HOUR_OF_DAY

7.9.3.2 Constructors

public SpinnerDateModel( ): This constructor creates a date model with no start or end point that uses the current date for the current value. The spin increment/decrement value is one day.
public SpinnerDateModel(Date value, Comparable start, Comparable end, int calendarField): This constructor builds a model with the specified current value, start, and end points, and an increment of calendarField. Note that start and end can be null to indicate that no minimum or maximum dates are applicable.

7.9.4 The SpinnerListModel Class

This model allows you to spin through the (String representation of) items in a List (or an array which gets turned into a List). When you hit the start or the end, trying to go past them results in a null next or previous value that effectively stops the spinner from spinning; in other words, you can't go past the bounds of the array.

The Javadoc makes a point worth repeating here: the model stores only a reference to the list of items, not a copy. If the list changes, it's up to the programmer to deal with the consequences. The benefit, of course, is that the items shown by the spinner stay in near-perfect sync with the list. We say near-perfect because if you're sitting on the item that changed, it won't show up until you spin away and spin back.

7.9.4.1 Properties

The only new property added to SpinnerListModel is, not surprisingly, the list itself. See Table 7-20.

Table 7-20. SpinnerListModel properties
Property	Data type	get	set	Default value
list	java.util.List	·	·	List with one entry: `"empty"`
nextValue^o	Object	·
previousValue^o	Object	·
value^o	Object	·	·
^ooverridden

7.9.4.2 Constructors

Three constructors exist for creating new SpinnerListModel objects:

public SpinnerListModel( ): This constructor creates a spinner with an effectively empty list. (The list is built by calling the Object array version of the constructor with a one-element String array containing the word empty.)
public SpinnerListModel(List values)
public SpinnerListModel(Object[] values): These constructors build SpinnerListModel objects associated with the specified values. Note that only a reference to values is kept in the model, so you can update the content somewhat dynamically. In the case of the Object array version, the list returned from the list property is a private inner class from the java.util.Arrays class that does not override the default add( ) behavior (which simply throws an UnsupportedOperationException). To be honest, you really should rethink using a JSpinner on dynamic lists or at least make your own model that pays proper attention to changing contents.

7.9.5 The SpinnerNumberModel Class

The number model allows you to spin numbers (both integers and decimals). The range can be bounded, or you can selectively leave off the minimum, maximum, or both. While you normally use Number objects to fill the model, special case constructors exist for the very common int and double types. For those types, you specify the starting position, the minimum and maximum, and the step size. (Note that for doubles, the step size is also a double, so you can increment by 0.1, 0.05, 2.5, etc.)

7.9.5.1 Properties

Table 7-21 shows the properties for the number model. Beyond the standard properties, minimum and maximum properties are added to provide a range for the spinner. As with the SpinnerDateModel, either of these values can be null to indicate that no limit exists. The stepSize property allows you to specify the increment/decrement value for the spinner. The number property is a convenience property that allows you to retrieve the current value as a Number object.

Table 7-21. SpinnerNumberModel properties
Property	Data type	get	set	Default value
maximum	Comparable	·	·	`null` (no max)
minimum	Comparable	·	·	`null` (no min)
nextValue^o	Object	·
number	Number	·		Integer(0)
previousValue^o	Object	·
stepSize	Number	·	·	Integer(1)
value^o	Object	·	·	Integer(0)
^ooverridden

7.9.5.2 Constructors

public SpinnerNumberModel( ): Construct a SpinnerNumberModel with no minimum or maximum value, a stepSize equal to one, and an initial value of 0.
public SpinnerNumberModel(int value, int minimum, int maximum, int stepSize)
public SpinnerNumberModel(double value, double minimum, double maximum, double stepSize)
public SpinnerNumberModel(Number value, Comparable minimum, Comparable maximum, Number stepSize): Build number models with a starting point of value, the specified minimum and maximum points, and the given stepSize. The int and double constructors are for convenience only. If you need an open minimum or maximum, you'll have to use the Number/Comparable version.

7.9.6 A Custom Model: Rollover Lists

As an example of how simple it can be to extend the functionality of these spinner models, here's a RolloverListModel that you can use. Like the SpinnerListModel, it takes a list, but rather than return null if you try to go past the end (or the beginning, for that matter), it "rolls over" to the beginning (or the end). Here's the source code for this model:

// RolloverSpinnerListModel.java // import javax.swing.*; import java.util.List; public class RolloverSpinnerListModel extends SpinnerListModel {   public RolloverSpinnerListModel(Object[] items) { super(items); }   public RolloverSpinnerListModel(List items) { super(items); }   public Object getNextValue( ) {     Object nv = super.getNextValue( );     if (nv != null) {       return nv;     }     return getList( ).get(0);   }   public Object getPreviousValue( ) {     Object pv = super.getPreviousValue( );     if (pv != null) {       return pv;     }     List l = getList( );     return l.get(l.size( ) - 1);   } }

This model is used for the last spinner shown in Figure 7-13. In that example, we use the weekdays array for both a standard list model and this rollover list model. You'll have to play with the spinner to get the effect static screen shots just don't do it justice.