This document describes the new Swing component, JSpinner.
One of the most commonly requested new Swing components is a spinner - a single line input field that lets the user select an number or an object value from an ordered set. Spinners typically provide a pair of tiny arrow buttons for stepping through the possible values, the up/down arrow keys also cycle through the values. The user may also be allowed to type a (legal) value directly into the spinner. Although combo boxes provide similar functionality, spinners are sometimes preferred because they don't require a drop down list that can obscure important data.
The bugtraq report that corresponds to this change is: 4290529.
A Short Catalog of Spinners
Spinners are common in modern GUIs. Here are some examples from some popular look and feels and from OpenWindows:
|
|
|
|
|
Windows |
CDE/Motif |
JLF |
Mac Aqua |
OpenWindows |
All of the spinners deliver very simple behavior: clicking on the arrow buttons changes the fields value and, when the spinner has the focus, the keyboard up and down arrow keys do the same. In some applications the spinners up or down arrow button is disabled when the upper or lower limit of the spinner has been reached, in other cases the spinner just resets its value to the opposite extreme.
JSpinner
, SpinnerModel
, SpinnerListModel
The JSpinner
class is a simple Swing container that manages three children: two arrow buttons and a single component, called the editor that displays the spinner's value. The value displayed by the spinner is encapsulated by model of a sequence of objects called a SpinnerModel
.
public interface SpinnerModel {
Object getValue();
void setValue(Object);
Object getNextValue();
Object getPreviousValue();
void addChangeListener(ChangeListener x);
void removeChangeListener(ChangeListener x);}
The SpinnerModel
interface is similar to ListModel
- they both represent a sequence a values - however there are some important differences:
- The model doesn't support random access to sequence elements. Only three sequence values are accessible at a time: current, next and previous.
- The number of sequence elements isn't necessarily bounded so there's no sequence length returning
size
method.
- The model's value property is read/write, unlike the elements of a
ListModels
sequence, which are read-only. This difference reflects the different roles of JList
and JSpinner
. The former was designed to simplify selecting one or more items from a list and the latter for entering a single value directly.
The relationship between the JSpinner
and its model is simple. The editor component monitors the model with a ChangeListener
and always displays the object returned by SpinnerModel.getValue()
. The up and down arrow buttons update the value by calling setValue(getNextValue())
or setValue(getPreviousValue())
respectively. The getNextValue
and getPreviousValue
methods return null
when the end or the beginning of the sequence has been reached, so the arrow button actions have to check for null
before updating the models value. If the editor is a writable field of some kind, it's responsible for honoring the constraints defined by the model or handling the IllegalArgumentException
thrown by setValue
for invalid values.
The SpinnerListModel
provides support for two common mutable sequence types: java.util.List
, and an array of objects. For example to create a JSpinner
that lets the user choose a day of the week in the default locale one could write:
String[] days = new DateFormatSymbols().getWeekdays();
SpinnerModel model = new SpinnerListModel(days);
JSpinner spinner = new JSpinner(model);
In addition to initializing the model
property of the spinner, these constructors create an editor component that displays the SpinnerModel
's value
and can be used to change it. The protected JSpinner.createEditor
method is used for this and, by default, it creates a JFormattedTextField
that has been configured to display the model.
To find or initialize a spinners current value one can either use the models value
property or use the convenience JSpinner
value
property which just delegates to the model. For example, using the spinner configured in the example above, the following two statements are equivalent:
String selectedDay = spinner.getModel().getValue().toString();
String selectedDay = spinner.getValue().toString();
Setting the spinner's value is similar. Attempts to set the SpinnerModel
value to an object that the model doesn't support cause an IllegalArgumentException
to be thrown.
Dates and numbers are two of the most common applications for a spinner component. To simplify spinning these types, two additional SpinnerModel
implementation classes are provided: SpinnerDateModel
and SpinnerNumberModel
.
SpinnerDateModel
One of the most common uses of a spinner is to compactly present an editable date. Here's a simple example of creating a JSpinner
that allows the user to enter a (fully localized) date:
SpinnerDateModel model = new SpinnerDateModel();
JSpinner spinner = new JSpinner(model);
Date value = model.getDate();
In this example, the JSpinner
constructor has created a JFormattedTextField
editor that's configured for editing dates and it has added a ChangeListener
to the SpinnerDateModel
to keep the editor
and the model in sync.
Here's the SpinnerDateModel
API. We've added three new read/write properties: start
, end
, and stepSize
and a read-only date
property that returns the models value cast to a Date
.
public class SpinnerDateModel extends AbstractSpinnerModel {
public SpinnerDateModel(Date value, Comparable start, Comparable end, int stepSize)
public SpinnerDateModel()
public void setStart(Comparable start)
public Comparable getStart()
public void setEnd(Comparable end)
public Comparable getEnd()
public Object getNextValue()
public Object getPreviousValue()
public Date getDate()
public Object getValue()
public void setValue(Object value)}
The startDate
and endDate
properties can be null
to indicate that there is no lower or upper limit. The no-arguments SpinnerDateModel
constructor initializes both the start and end date to null
, the initial value of the model is the current date.
The value of the stepSize
property must be one of the java.util.Calendar
constants that specify a field within a Calendar
. The getNextValue
and getPreviousValue
methods change the date forward or backwards by this amount. For example, if stepSize
is Calendar.DAY_OF_WEEK
, then nextValue
produces a Date
that's 24 hours after the current value
, and previousValue
produces a Date
that's 24 hours earlier.
The legal values for stepSize
are:
Calendar.ERA
Calendar.YEAR
Calendar.MONTH
Calendar.WEEK_OF_YEAR
Calendar.WEEK_OF_MONTH
Calendar.DAY_OF_MONTH
Calendar.DAY_OF_YEAR
Calendar.DAY_OF_WEEK
Calendar.DAY_OF_WEEK_IN_MONTH
Calendar.AM_PM
Calendar.HOUR
Calendar.HOUR_OF_DAY
Calendar.MINUTE
Calendar.SECOND
Calendar.MILLISECOND
The default SpinnerDateModel
editor
adjusts the stepSize
property based on the text cursor position. For example if the cursor moves into the editor's month subfield then the incrementSize
would be changed to Calendar.DAY_OF_MONTH
.
SpinnerNumberModel
Spinners are often used to present editable integers and real numbers that represent everything from temperature to stock prices. The SpinnerNumberModel
provides basic support for all of the basic Java Number
types, from Byte
to Double
.
To create a spinner that allows the user to pick a real multiple of 1/8 between 0.0 and 1000.0, with an initial value of 500.0, one could write:
SpinnerNumberModel model = new SpinnerNumberModel(500.0, 0.0, 1000.0, 0.625);
JSpinner spinner = new JSpinner(model);
double value = model.getNumber().doubleValue();
In this example, the JSpinner
constructor has created a JFormattedTextField
editor that's configured for editing real numbers and it has added a ChangeListener
to the SpinnerNumberModel
to keep the editor
and the model in sync.
Here's a summary of the SpinnerNumberModel
API. We've added three new read/write properties: minimum
, maximum
, and stepSize
and a read-only number
property that returns the models value
cast to a Number
.
public class SpinnerNumberModel extends AbstractSpinnerModel {
public SpinnerNumberModel(Number value, Comparable minimum, Comparable maximum, Number stepSize)
public SpinnerNumberModel(int value, int minimum, int maximum, int stepSize)
public SpinnerNumberModel(double value, double minimum, double maximum, double stepSize)
public SpinnerNumberModel()
public void setMinimum(Comparable minimum)
public Comparable getMinimum()
public void setMaximum(Comparable maximum)
public Comparable getMaximum()
public void setStepSize(Number stepSize)
public Number getStepSize()
public Object getNextValue()
public Object getPreviousValue()
public Number getNumber()
public Object getValue()
public void setValue(Object value)}
As with the SpinnerDateModel
, the minimum
and maximum
properties can be null
to indicate that there is no lower or upper limit. The stepSize
property just specifies how much to add or subtract from the value
to compute the nextValue
or the previousValue
.
Summary of the Spinner APIs
Support for spinners added six classes and one interface (SpinnerModel
) to the javax.swing
package:
Additionally, SpinnerUI
has been added to the javax.swing.plaf
package and BasicSpinnerUI
to the javax.swing.plaf.basic
package:
posted on 2005-02-05 20:22
jacky 阅读(346)
评论(0) 编辑 收藏