javax.swing
Class JSpinner

java.lang.Object
  java.awt.Component
      java.awt.Container
          javax.swing.JComponent
              javax.swing.JSpinner

All Implemented Interfaces:

java.awt.image.ImageObserver, java.io.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 JavaBeans^TM has been added to the java.beans package. Please see java.beans.XMLEncoder.

Since:

1.4

See Also:

SpinnerModel, AbstractSpinnerModel, SpinnerListModel, SpinnerNumberModel, SpinnerDateModel, JFormattedTextField

Nested Class Summary

static class	JSpinner.DateEditor An editor for a JSpinner whose model is 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.
static class	JSpinner.ListEditor An editor for a JSpinner whose model is a SpinnerListModel.
static class	JSpinner.NumberEditor An editor for a JSpinner whose model is a SpinnerNumberModel.

Field Summary

Fields inherited from class javax.swing.JComponent

listenerList, TOOL_TIP_TEXT_KEY, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW

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.
java.lang.Object	getNextValue() Returns the object in the sequence that comes after the object returned by getValue().
java.lang.Object	getPreviousValue() Returns the object in the sequence that comes before the object returned by getValue().
java.lang.Object	getValue() Returns the current value of the model, typically this value is displayed by the editor.
void	paint(java.awt.Graphics g) Invoked by Swing to draw components.
protected void	paintBorder(java.awt.Graphics g) Paints the component's border.
protected void	paintComponent(java.awt.Graphics g) Calls the UI delegate's paint method, if the UI delegate is non-null.
void	paintComponents(java.awt.Graphics g)
protected void	printBorder(java.awt.Graphics g) Prints the component's border.
protected void	printComponent(java.awt.Graphics g) This is invoked during a printing operation.
void	printComponents(java.awt.Graphics g)
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	setValue(java.lang.Object value) Changes current value of the model, typically this value is displayed by the editor.

Methods inherited from class javax.swing.JComponent

addAncestorListener, addNotify, addPropertyChangeListener, addPropertyChangeListener, addVetoableChangeListener, computeVisibleRect, contains, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBorder, getBounds, getClientProperty, getComponentGraphics, getConditionForKeyStroke, getDefaultLocale, getGraphics, getHeight, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getPreferredSize, getPropertyChangeListeners, getPropertyChangeListeners, getRegisteredKeyStrokes, getSize, getToolTipText, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, isDoubleBuffered, isMaximumSizeSet, isMinimumSizeSet, isOpaque, isOptimizedDrawingEnabled, isPaintingTile, isPreferredSizeSet, isRequestFocusEnabled, isValidateRoot, paintChildren, paintImmediately, paintImmediately, paramString, print, printAll, printChildren, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removePropertyChangeListener, removePropertyChangeListener, removeVetoableChangeListener, repaint, repaint, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setDefaultLocale, setDoubleBuffered, setEnabled, setFont, setForeground, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update

Methods inherited from class java.awt.Container

add, add, add, add, add, addContainerListener, addImpl, areFocusTraversalKeysSet, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicySet, list, list, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setFocusCycleRoot, setFocusTraversalKeys, setFocusTraversalPolicy, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree

Methods inherited from class java.awt.Component

addComponentListener, addFocusListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enableEvents, enableInputMethods, getBackground, getBounds, getColorModel, getComponentListeners, getCursor, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getFontMetrics, getForeground, getGraphicsConfiguration, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMouseWheelListeners, getName, getParent, getSize, getToolkit, getTreeLock, hasFocus, imageUpdate, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isShowing, isValid, isVisible, list, list, list, paintAll, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processInputMethodEvent, processMouseEvent, processMouseWheelEvent, removeComponentListener, removeFocusListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, repaint, repaint, repaint, setBounds, setBounds, setCursor, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, toString, transferFocus, transferFocusUpCycle

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

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

paint

public final void paint(java.awt.Graphics g)

Description copied from class: JComponent

Invoked by Swing to draw components. Applications should not invoke paint directly, but should instead use the repaint method to schedule the component for redrawing.

This method actually delegates the work of painting to three protected methods: paintComponent, paintBorder, and paintChildren. They're called in the order listed to ensure that children appear on top of component itself. Generally speaking, the component and its children should not paint in the insets area allocated to the border. Subclasses can just override this method, as always.

Overrides:

paint in class JComponent

Parameters:

g - the Graphics context in which to paint

See Also:

JComponent.paintBorder(java.awt.Graphics), JComponent.paintChildren(java.awt.Graphics), JComponent.getComponentGraphics(java.awt.Graphics), JComponent.repaint(long, int, int, int, int)

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:

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

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:

java.lang.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 java.lang.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(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:

java.lang.IllegalArgumentException - if value isn't allowed

See Also:

getValue(), SpinnerModel.setValue(java.lang.Object)

getNextValue

public java.lang.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 java.lang.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:

java.lang.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 java.text.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:

java.text.ParseException - if the currently edited value couldn't be commited.

paintComponent

protected final void paintComponent(java.awt.Graphics g)

Description copied from class: JComponent

Calls the UI delegate's paint method, if the UI delegate is non-null. We pass the delegate a copy of the Graphics object to protect the rest of the paint code from irrevocable changes (for example, Graphics.translate).

Overrides:

paintComponent in class JComponent

Parameters:

g - the Graphics object to protect

See Also:

JComponent.paint(java.awt.Graphics), ComponentUI

paintBorder

protected final void paintBorder(java.awt.Graphics g)

Description copied from class: JComponent

Paints the component's border.

Overrides:

paintBorder in class JComponent

Parameters:

g - the Graphics context in which to paint

See Also:

JComponent.paint(java.awt.Graphics), JComponent.setBorder(javax.swing.border.Border)

paintComponents

public final void paintComponents(java.awt.Graphics g)

printComponent

protected final void printComponent(java.awt.Graphics g)

Description copied from class: JComponent

This is invoked during a printing operation. This is implemented to invoke paintComponent on the component.

Overrides:

printComponent in class JComponent

Parameters:

g - the Graphics context in which to paint

See Also:

JComponent.print(java.awt.Graphics)

printBorder

protected final void printBorder(java.awt.Graphics g)

Description copied from class: JComponent

Prints the component's border. This is implemented to invoke paintBorder on the component.

Overrides:

printBorder in class JComponent

Parameters:

g - the Graphics context in which to paint

See Also:

JComponent.print(java.awt.Graphics)

printComponents

public final void printComponents(java.awt.Graphics g)