javax.swing
Class JSpinner

java.lang.Object
  extended byjava.awt.Component
      extended byjava.awt.Container
          extended byjavax.swing.JComponent
              extended byjavax.swing.JSpinner
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable

public class JSpinner
extends JComponent

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.

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 XMLEncoder.

Since:
1.4
Author:
Hans Muller
See Also:
SpinnerModel, AbstractSpinnerModel, SpinnerListModel, SpinnerNumberModel, SpinnerDateModel, JFormattedTextField, Serialized Form

Nested Class Summary
static class JSpinner.DateEditor
          An editor for a JSpinner whose model is a SpinnerDateModel.
private static class JSpinner.DateEditorFormatter
          This subclass of javax.swing.DateFormatter maps the minimum/maximum properties to te start/end properties of a SpinnerDateModel.
static class JSpinner.DefaultEditor
          A simple base class for more specialized editors that displays a read-only view of the model's current value with a JFormattedTextField.
private static class JSpinner.DisabledAction
          An Action implementation that is always disabled.
static class JSpinner.ListEditor
          An editor for a JSpinner whose model is a SpinnerListModel.
private  class JSpinner.ModelListener
          We pass Change events along to the listeners with the the slider (instead of the model itself) as the event source.
static class JSpinner.NumberEditor
          An editor for a JSpinner whose model is a SpinnerNumberModel.
private static class JSpinner.NumberEditorFormatter
          This subclass of javax.swing.NumberFormatter maps the minimum/maximum properties to a SpinnerNumberModel and initializes the valueClass of the NumberFormatter to match the type of the initial models value.
 
Nested classes inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent, JComponent.ActionStandin, JComponent.IntVector, JComponent.KeyboardState
 
Nested classes inherited from class java.awt.Container
Container.AccessibleAWTContainer
 
Nested classes inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BltBufferStrategy, Component.FlipBufferStrategy
 
Field Summary
private  ChangeEvent changeEvent
           
private static Action DISABLED_ACTION
           
private  JComponent editor
           
private  boolean editorExplicitlySet
           
private  SpinnerModel model
           
private  ChangeListener modelListener
           
private static String uiClassID
           
 
Fields inherited from class javax.swing.JComponent
_bounds, accessibleContext, listenerList, paintingChild, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
 
Fields inherited from class java.awt.Container
 
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
 
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
 
Constructor Summary
JSpinner()
          Constructs a spinner with an Integer SpinnerNumberModel with initial value 0 and no minimum or maximum limits.
JSpinner(SpinnerModel model)
          Constructs a complete spinner with pair of next/previous buttons and an editor for the SpinnerModel.
 
Method Summary
 void addChangeListener(ChangeListener listener)
          Adds a listener to the list that is notified each time a change to the model occurs.
 void commitEdit()
          Commits the currently edited value to the SpinnerModel.
protected  JComponent createEditor(SpinnerModel model)
          This method is called by the constructors to create the JComponent that displays the current value of the sequence.
protected  void fireStateChanged()
          Sends a ChangeEvent, whose source is this JSpinner, to each ChangeListener.
 ChangeListener[] getChangeListeners()
          Returns an array of all the ChangeListeners added to this JSpinner with addChangeListener().
 JComponent getEditor()
          Returns the component that displays and potentially changes the model's value.
 SpinnerModel getModel()
          Returns the SpinnerModel that defines this spinners sequence of values.
 Object getNextValue()
          Returns the object in the sequence that comes after the object returned by getValue().
 Object getPreviousValue()
          Returns the object in the sequence that comes before the object returned by getValue().
 SpinnerUI getUI()
          Returns the look and feel (L&F) object that renders this component.
 String getUIClassID()
          Returns the suffix used to construct the name of the look and feel (L&F) class used to render this component.
 Object getValue()
          Returns the current value of the model, typically this value is displayed by the editor.
private  void readObject(ObjectInputStream s)
          We use the ObjectInputStream "registerValidation" callback to update the UI for the entire tree of components after they've all been read in.
 void removeChangeListener(ChangeListener listener)
          Removes a ChangeListener from this spinner.
 void setEditor(JComponent editor)
          Changes the JComponent that displays the current value of the SpinnerModel.
 void setModel(SpinnerModel model)
          Changes the model that represents the value of this spinner.
 void setUI(SpinnerUI ui)
          Sets the look and feel (L&F) object that renders this component.
 void setValue(Object value)
          Changes current value of the model, typically this value is displayed by the editor.
 void updateUI()
          Resets the UI property with the value from the current look and feel.
private  void writeObject(ObjectOutputStream s)
          Before writing a JComponent to an ObjectOutputStream we temporarily uninstall its UI.
 
Methods inherited from class javax.swing.JComponent
_paintImmediately, addAncestorListener, addNotify, addPropertyChangeListener, addPropertyChangeListener, addVetoableChangeListener, alwaysOnTop, checkIfChildObscuredBySibling, componentInputMapChanged, computeVisibleRect, computeVisibleRect, compWriteObjectNotify, contains, createToolTip, disable, enable, enableSerialization, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getAccessibleContext, getActionForKeyStroke, getActionMap, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBorder, getBounds, getClientProperty, getComponentGraphics, getConditionForKeyStroke, getCreatedDoubleBuffer, getDebugGraphicsOptions, getDefaultLocale, getGraphics, getHeight, getInputMap, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getManagingFocusBackwardTraversalKeys, getManagingFocusForwardTraversalKeys, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPreferredSize, getPropertyChangeListeners, getPropertyChangeListeners, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getWriteObjCounter, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isMaximumSizeSet, isMinimumSizeSet, isOpaque, isOptimizedDrawingEnabled, isPaintingOrigin, isPaintingTile, isPreferredSizeSet, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, paramString, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyBindings, processKeyBindingsForAllComponents, processKeyEvent, processMouseMotionEvent, putClientProperty, rectangleIsObscured, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removePropertyChangeListener, removePropertyChangeListener, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setCreatedDoubleBuffer, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFont, setForeground, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPaintingChild, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, setWriteObjCounter, shouldDebugGraphics, superProcessMouseMotionEvent, unregisterKeyboardAction, update
 
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setFocusCycleRoot, setFocusTraversalKeys, setFocusTraversalPolicy, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
 
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getFontMetrics, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMouseWheelListeners, getName, getParent, getPeer, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

uiClassID

private static final String uiClassID
See Also:
getUIClassID(), readObject(java.io.ObjectInputStream), Constant Field Values

DISABLED_ACTION

private static final Action DISABLED_ACTION

model

private transient SpinnerModel model

editor

private JComponent editor

modelListener

private ChangeListener modelListener

changeEvent

private transient ChangeEvent changeEvent

editorExplicitlySet

private boolean editorExplicitlySet
Constructor Detail

JSpinner

public JSpinner(SpinnerModel model)
Constructs a complete spinner with pair of next/previous buttons and an editor for the SpinnerModel.


JSpinner

public JSpinner()
Constructs a spinner with an Integer SpinnerNumberModel with initial value 0 and no minimum or maximum limits.

Method Detail

getUI

public SpinnerUI getUI()
Returns the look and feel (L&F) object that renders this component.

Returns:
the SpinnerUI object that renders this component

setUI

public void setUI(SpinnerUI ui)
Sets the look and feel (L&F) object that renders this component.

Parameters:
ui - the SpinnerUI L&F object
See Also:
UIDefaults.getUI(javax.swing.JComponent)

getUIClassID

public String getUIClassID()
Returns the suffix used to construct the name of the look and feel (L&F) class used to render this component.

Overrides:
getUIClassID in class JComponent
Returns:
the string "SpinnerUI"
See Also:
JComponent.getUIClassID(), UIDefaults.getUI(javax.swing.JComponent)

updateUI

public void updateUI()
Resets the UI property with the value from the current look and feel.

Overrides:
updateUI in class JComponent
See Also:
UIManager.getUI(javax.swing.JComponent)

createEditor

protected JComponent createEditor(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:

Parameters:
model - the value of getModel
Returns:
a component that displays the current value of the sequence
See Also:
getModel(), setEditor(javax.swing.JComponent)

setModel

public void setModel(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));
 

Parameters:
model - the new SpinnerModel
Throws:
IllegalArgumentException - if model is null
See Also:
getModel(), getEditor(), setEditor(javax.swing.JComponent)

getModel

public SpinnerModel getModel()
Returns the SpinnerModel that defines this spinners sequence of values.

Returns:
the value of the model property
See Also:
setModel(javax.swing.SpinnerModel)

getValue

public Object getValue()
Returns the current value of the model, typically this value is displayed by the editor.

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

 getModel().getValue()
 

See Also:
setValue(java.lang.Object), SpinnerModel.getValue()

setValue

public void setValue(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 Also:
getValue(), SpinnerModel.setValue(java.lang.Object)

getNextValue

public Object getNextValue()
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()
 

Returns:
the next legal value or null if one doesn't exist
See Also:
getValue(), getPreviousValue(), SpinnerModel.getNextValue()

addChangeListener

public void addChangeListener(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.

Parameters:
listener - the ChangeListener to add
See Also:
removeChangeListener(javax.swing.event.ChangeListener), getModel()

removeChangeListener

public void removeChangeListener(ChangeListener listener)
Removes a ChangeListener from this spinner.

Parameters:
listener - the ChangeListener to remove
See Also:
fireStateChanged(), addChangeListener(javax.swing.event.ChangeListener)

getChangeListeners

public ChangeListener[] getChangeListeners()
Returns an array of all the ChangeListeners added to this JSpinner with addChangeListener().

Returns:
all of the ChangeListeners added or an empty array if no listeners have been added
Since:
1.4

fireStateChanged

protected void fireStateChanged()
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 Also:
addChangeListener(javax.swing.event.ChangeListener), removeChangeListener(javax.swing.event.ChangeListener), EventListenerList

getPreviousValue

public Object getPreviousValue()
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()
 

Returns:
the previous legal value or null if one doesn't exist
See Also:
getValue(), getNextValue(), SpinnerModel.getPreviousValue()

setEditor

public void setEditor(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.

Parameters:
editor - the new editor
Throws:
IllegalArgumentException - if editor is null
See Also:
getEditor(), createEditor(javax.swing.SpinnerModel), getModel()

getEditor

public JComponent getEditor()
Returns the component that displays and potentially changes the model's value.

Returns:
the component that displays and potentially changes the model's value
See Also:
setEditor(javax.swing.JComponent), createEditor(javax.swing.SpinnerModel)

commitEdit

public void commitEdit()
                throws ParseException
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.

writeObject

private void writeObject(ObjectOutputStream s)
                  throws IOException
Description copied from class: JComponent
Before writing a JComponent to an ObjectOutputStream we temporarily uninstall its UI. This is tricky to do because we want to uninstall the UI before any of the JComponent's children (or its LayoutManager etc.) are written, and we don't want to restore the UI until the most derived JComponent subclass has been been stored.

Throws:
IOException

readObject

private void readObject(ObjectInputStream s)
                 throws IOException,
                        ClassNotFoundException
Description copied from class: JComponent
We use the ObjectInputStream "registerValidation" callback to update the UI for the entire tree of components after they've all been read in.

Throws:
IOException
ClassNotFoundException