7.8 Spinners

You might be wondering just what a spinner is. It's a new 1.4 component similar to the JComboBox, but it shows only one item. It includes up and down arrows to "scroll" through its set of values. A JFormattedTextField is used to edit and render those values. Spinners are quite flexible. They work nicely with a set of choices (such as the months of the year) as well as with unbounded ranges such as a set of integers. Figure 7-13 shows several examples of spinners in different L&Fs. The Mac L&F is missing from this figure because the SDK 1.4 was not available on OS X at the time we went to press.

Figure 7-13. Various JSpinner instances in three L&Fs

The classes involved in spinners are shown in Figure 7-14.

Figure 7-14. JSpinner class diagram

7.8.1 Properties

JSpinner has several properties related to the values it displays (see Table 7-16). Most of the properties are easy to understand from their names alone. The currently selected value is available through the read/write value property.

Table 7-16. JSpinner properties

Property	Data type	get	is	set	Default value
changeListeners	ChangeListener[]	·			Empty array
editorb	JComponent	·		·	JPspinner.NumberEditor( )
modelb	SpinnerModel	·		·	SpinnerNumberModel( )
nextValue	Object	·
previousValue	Object	·
UI	SpinnerUI	·			L&F-dependent
UIClassID	String	·			"SpinnerUI"
value	Object	·		·
bbound

7.8.2 Events

public void addChangeListener(ChangeListener l)

public void removeChangeListener(ChangeListener l)

Add or remove a specific listener for ChangeEvent notifications from the component.

7.8.3 Constructors

public JSpinner( )

Create a spinner for numeric values that has no bounds, an initial value of 0, and an increment of 1. (This constructor uses an instance of the SpinnerNumberModel that we'll see later in this section.)

public JSpinner(SpinnerModel model)

Create a spinner with the specified model. An editor for the model is installed using the protected createEditor( ) method, which is discussed later in this chapter.

7.8.4 Editing Methods

The following methods may be of use to developers:

public void commitEdit( )

Commit the current value to the spinner model. With a JFormattedTextField as your editor, you can commit the value you typed by pressing the Enter key. The model then stores the value internally. If you type in an invalid value (bad date, not a number, etc.), the editor does not accept the change, and you have to continue editing. You can also cancel the edit using the Esc key.

Your model might also reject the value you tried to commit. For example, you might type in a perfectly valid date, but that date is outside the range of dates the model expects. In this case, JFormattedTextField does not complain, but the value is still unacceptable.

protected JComponent createEditor(SpinnerModel model)

Create an editor appropriate for the specified model. "Appropriate" currently means a JFormattedTextField with a format designed for dates, numbers, or String representations of elements in a list. If model is not an instance of one of the known models, a default editor (which uses a String representation of the value) is used. To install your own editor based on a model, you'll have to subclass JSpinner and override this method. (You could always call setEditor( ) for one of the editors.)

7.8.5 Simple Spinners

The code for the spinner examples in Figure 7-13 is shown below. Notice that we use various model constructors to build the different spinners. The spinner models are discussed in the next section.

// SpinnerTest.java
//
import javax.swing.*;
import javax.swing.event.*;
import java.awt.*;

public class SpinnerTest extends JFrame {

  public SpinnerTest( ) {
    super("JSpinner Test");
    setSize(300,180);
    setDefaultCloseOperation(EXIT_ON_CLOSE);

    Container c = getContentPane( );
    c.setLayout(new GridLayout(0,2));

    c.add(new JLabel(" Basic Spinner"));
    c.add(new JSpinner( ));

    c.add(new JLabel(" Date Spinner"));
    c.add(new JSpinner(new SpinnerDateModel( )));

    String weekdays[] = new String[] { "Sunday", "Monday", "Tuesday",
       "Wednesday", "Thursday", "Friday", "Saturday" };
    c.add(new JLabel(" List Spinner"));
    c.add(new JSpinner(new SpinnerListModel(weekdays)));

    c.add(new JLabel(" Number Spinner"));
    c.add(new JSpinner(new SpinnerNumberModel(0, 0, 100, 5)));

    c.add(new JLabel(" Rollover List Spinner"));
    c.add(new JSpinner(new RolloverSpinnerListModel(weekdays)));

    setVisible(true);
  }

  public static void main(String args[]) {
    new SpinnerTest( );
  }
}