FileDocCategorySizeDatePackage
JSpinner.javaAPI DocJava SE 5 API63711Fri Aug 26 14:57:56 BST 2005javax.swing

JSpinner

public class JSpinner extends JComponent implements Accessible
A single line input field that lets the user select a number or an object value from an ordered sequence. Spinners typically provide a pair of tiny arrow buttons for stepping through the elements of the sequence. The keyboard up/down arrow keys also cycle through the elements. 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.

A JSpinner's sequence value is defined by its SpinnerModel. The model can be specified as a constructor argument and changed with the model property. SpinnerModel classes for some common types are provided: SpinnerListModel, SpinnerNumberModel, and SpinnerDateModel.

A JSpinner has a single child component that's responsible for displaying and potentially changing the current element or value of the model, which is called the editor. The editor is created by the JSpinner's constructor and can be changed with the editor property. The JSpinner's editor stays in sync with the model by listening for ChangeEvents. If the user has changed the value displayed by the editor it is possible for the model's value to differ from that of the editor. To make sure the model has the same value as the editor use the commitEdit method, eg:

try {
spinner.commitEdit();
}
catch (ParseException pe) {{
// Edited value is invalid, spinner.getValue() will return
// the last valid value, you could revert the spinner to show that:
JComponent editor = spinner.getEditor()
if (editor instanceof DefaultEditor) {
((DefaultEditor)editor).getTextField().setValue(spinner.getValue();
}
// reset the value to some known value:
spinner.setValue(fallbackValue);
// or treat the last valid value as the current, in which
// case you don't need to do anything.
}
return spinner.getValue();

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see {@link java.beans.XMLEncoder}.

beaninfo
attribute: isContainer false description: A single line input field that lets the user select a number or an object value from an ordered set.
see
SpinnerModel
see
AbstractSpinnerModel
see
SpinnerListModel
see
SpinnerNumberModel
see
SpinnerDateModel
see
JFormattedTextField
version
1.38 05/12/04
author
Hans Muller
author
Lynn Monsanto (accessibility)
since
1.4

Fields Summary
private static final String
uiClassID
private static final Action
DISABLED_ACTION
private transient SpinnerModel
model
private JComponent
editor
private ChangeListener
modelListener
private transient ChangeEvent
changeEvent
private boolean
editorExplicitlySet
Constructors Summary
public JSpinner(SpinnerModel model)
Constructs a complete spinner with pair of next/previous buttons and an editor for the SpinnerModel.



                         
       
	this.model = model;
	this.editor = createEditor(model);
	setOpaque(true);
        updateUI();
    
public JSpinner()
Constructs a spinner with an Integer SpinnerNumberModel with initial value 0 and no minimum or maximum limits.

	this(new SpinnerNumberModel());
    
Methods Summary
public voidaddChangeListener(javax.swing.event.ChangeListener listener)
Adds a listener to the list that is notified each time a change to the model occurs. The source of ChangeEvents delivered to ChangeListeners will be this JSpinner. Note also that replacing the model will not affect listeners added directly to JSpinner. Applications can add listeners to the model directly. In that case is that the source of the event would be the SpinnerModel.

param
listener the ChangeListener to add
see
#removeChangeListener
see
#getModel

        if (modelListener == null) {
            modelListener = new ModelListener();
            getModel().addChangeListener(modelListener);
        }
        listenerList.add(ChangeListener.class, listener);
    
public voidcommitEdit()
Commits the currently edited value to the SpinnerModel.

If the editor is an instance of DefaultEditor, the call if forwarded to the editor, otherwise this does nothing.

throws
ParseException if the currently edited value couldn't be commited.

        JComponent editor = getEditor();
        if (editor instanceof DefaultEditor) {
            ((DefaultEditor)editor).commitEdit();
        }
    
protected javax.swing.JComponentcreateEditor(javax.swing.SpinnerModel model)
This method is called by the constructors to create the JComponent that displays the current value of the sequence. The editor may also allow the user to enter an element of the sequence directly. An editor must listen for ChangeEvents on the model and keep the value it displays in sync with the value of the model.

Subclasses may override this method to add support for new SpinnerModel classes. Alternatively one can just replace the editor created here with the setEditor method. The default mapping from model type to editor is:

  • SpinnerNumberModel => JSpinner.NumberEditor
  • SpinnerDateModel => JSpinner.DateEditor
  • SpinnerListModel => JSpinner.ListEditor
  • all others => JSpinner.DefaultEditor

return
a component that displays the current value of the sequence
param
model the value of getModel
see
#getModel
see
#setEditor

	if (model instanceof SpinnerDateModel) {
	    return new DateEditor(this);
	}
	else if (model instanceof SpinnerListModel) {
	    return new ListEditor(this);
	}
	else if (model instanceof SpinnerNumberModel) {
	    return new NumberEditor(this);
	}
	else {
	    return new DefaultEditor(this);
	}
    
protected voidfireStateChanged()
Sends a ChangeEvent, whose source is this JSpinner, to each ChangeListener. When a ChangeListener has been added to the spinner, this method method is called each time a ChangeEvent is received from the model.

see
#addChangeListener
see
#removeChangeListener
see
EventListenerList

        Object[] listeners = listenerList.getListenerList();
        for (int i = listeners.length - 2; i >= 0; i -= 2) {
            if (listeners[i] == ChangeListener.class) {
                if (changeEvent == null) {
                    changeEvent = new ChangeEvent(this);
                }
                ((ChangeListener)listeners[i+1]).stateChanged(changeEvent);
            }
        }
    
public javax.accessibility.AccessibleContextgetAccessibleContext()
Gets the AccessibleContext for the JSpinner

return
the AccessibleContext for the JSpinner
since
1.5

        if (accessibleContext == null) {
            accessibleContext = new AccessibleJSpinner();
        }
        return accessibleContext;
    
public javax.swing.event.ChangeListener[]getChangeListeners()
Returns an array of all the ChangeListeners added to this JSpinner with addChangeListener().

return
all of the ChangeListeners added or an empty array if no listeners have been added
since
1.4

        return (ChangeListener[])listenerList.getListeners(
                ChangeListener.class);
    
public javax.swing.JComponentgetEditor()
Returns the component that displays and potentially changes the model's value.

return
the component that displays and potentially changes the model's value
see
#setEditor
see
#createEditor

	return editor;
    
public javax.swing.SpinnerModelgetModel()
Returns the SpinnerModel that defines this spinners sequence of values.

return
the value of the model property
see
#setModel

	return model;
    
public java.lang.ObjectgetNextValue()
Returns the object in the sequence that comes after the object returned by getValue(). If the end of the sequence has been reached then return null. Calling this method does not effect value.

This method simply delegates to the model. It is equivalent to:

getModel().getNextValue()

return
the next legal value or null if one doesn't exist
see
#getValue
see
#getPreviousValue
see
SpinnerModel#getNextValue

	return getModel().getNextValue();
    
public java.lang.ObjectgetPreviousValue()
Returns the object in the sequence that comes before the object returned by getValue(). If the end of the sequence has been reached then return null. Calling this method does not effect value.

This method simply delegates to the model. It is equivalent to:

getModel().getPreviousValue()

return
the previous legal value or null if one doesn't exist
see
#getValue
see
#getNextValue
see
SpinnerModel#getPreviousValue

	return getModel().getPreviousValue();
    
public javax.swing.plaf.SpinnerUIgetUI()
Returns the look and feel (L&F) object that renders this component.

return
the SpinnerUI object that renders this component

        return (SpinnerUI)ui;
    
public java.lang.StringgetUIClassID()
Returns the suffix used to construct the name of the look and feel (L&F) class used to render this component.

return
the string "SpinnerUI"
see
JComponent#getUIClassID
see
UIDefaults#getUI

        return uiClassID;
    
public java.lang.ObjectgetValue()
Returns the current value of the model, typically this value is displayed by the editor. If the user has changed the value displayed by the editor it is possible for the model's value to differ from that of the editor, refer to the class level javadoc for examples of how to deal with this.

This method simply delegates to the model. It is equivalent to:

getModel().getValue()

see
#setValue
see
SpinnerModel#getValue

	return getModel().getValue();
    
private voidreadObject(java.io.ObjectInputStream s)

        s.defaultReadObject();

        Map additionalValues = (Map)s.readObject();

        model = (SpinnerModel)additionalValues.get("model");
    
public voidremoveChangeListener(javax.swing.event.ChangeListener listener)
Removes a ChangeListener from this spinner.

param
listener the ChangeListener to remove
see
#fireStateChanged
see
#addChangeListener

        listenerList.remove(ChangeListener.class, listener);
    
public voidsetEditor(javax.swing.JComponent editor)
Changes the JComponent that displays the current value of the SpinnerModel. It is the responsibility of this method to disconnect the old editor from the model and to connect the new editor. This may mean removing the old editors ChangeListener from the model or the spinner itself and adding one for the new editor.

param
editor the new editor
see
#getEditor
see
#createEditor
see
#getModel
throws
IllegalArgumentException if editor is null
beaninfo
bound: true attribute: visualUpdate true description: JComponent that displays the current value of the model

	if (editor == null) {
	    throw new IllegalArgumentException("null editor");
	}
	if (!editor.equals(this.editor)) {
	    JComponent oldEditor = this.editor;
	    this.editor = editor;
	    if (oldEditor instanceof DefaultEditor) {
		((DefaultEditor)oldEditor).dismiss(this);
	    }
	    editorExplicitlySet = true;
	    firePropertyChange("editor", oldEditor, editor);
	    revalidate();
	    repaint();
	}
    
public voidsetModel(javax.swing.SpinnerModel model)
Changes the model that represents the value of this spinner. If the editor property has not been explicitly set, the editor property is (implicitly) set after the "model" PropertyChangeEvent has been fired. The editor property is set to the value returned by createEditor, as in:
setEditor(createEditor(model));

param
model the new SpinnerModel
see
#getModel
see
#getEditor
see
#setEditor
throws
IllegalArgumentException if model is null
beaninfo
bound: true attribute: visualUpdate true description: Model that represents the value of this spinner.

	if (model == null) {
	    throw new IllegalArgumentException("null model");
	}
	if (!model.equals(this.model)) {
	    SpinnerModel oldModel = this.model;
	    this.model = model;
	    if (modelListener != null) {
		this.model.addChangeListener(modelListener);
	    }
	    firePropertyChange("model", oldModel, model);
	    if (!editorExplicitlySet) {
		setEditor(createEditor(model)); // sets editorExplicitlySet true
		editorExplicitlySet = false;
	    }
	    repaint();
	    revalidate();
	}
    
public voidsetUI(javax.swing.plaf.SpinnerUI ui)
Sets the look and feel (L&F) object that renders this component.

param
ui the SpinnerUI L&F object
see
UIDefaults#getUI

        super.setUI(ui);
    
public voidsetValue(java.lang.Object value)
Changes current value of the model, typically this value is displayed by the editor. If the SpinnerModel implementation doesn't support the specified value then an IllegalArgumentException is thrown.

This method simply delegates to the model. It is equivalent to:

getModel().setValue(value)

throws
IllegalArgumentException if value isn't allowed
see
#getValue
see
SpinnerModel#setValue

	getModel().setValue(value);
    
public voidupdateUI()
Resets the UI property with the value from the current look and feel.

see
UIManager#getUI

        setUI((SpinnerUI)UIManager.getUI(this));
        invalidate();
    
private voidwriteObject(java.io.ObjectOutputStream s)

        s.defaultWriteObject();
        HashMap additionalValues = new HashMap(1);
        SpinnerModel model = getModel();

        if (model instanceof Serializable) {
            additionalValues.put("model", model);
        }
        s.writeObject(additionalValues);

        if (getUIClassID().equals(uiClassID)) {
            byte count = JComponent.getWriteObjCounter(this);
            JComponent.setWriteObjCounter(this, --count);
            if (count == 0 && ui != null) {
                ui.installUI(this);
            }
        }