javax.swing
Class JFormattedTextField

java.lang.Object
  extended by java.awt.Component
      extended by java.awt.Container
          extended by javax.swing.JComponent
              extended by javax.swing.text.JTextComponent
                  extended by javax.swing.JTextField
                      extended by javax.swing.JFormattedTextField
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible, Scrollable, SwingConstants

public class JFormattedTextField
extends JTextField

A text field that makes use of a formatter to display and edit a specific type of data. The value that is displayed can be an arbitrary object. The formatter is responsible for displaying the value in a textual form and it may allow editing of the value. Formatters are usually obtained using an instance of JFormattedTextField.AbstractFormatterFactory. This factory is responsible for providing an instance of JFormattedTextField.AbstractFormatter that is able to handle the formatting of the value of the JFormattedTextField.

Since:
1.4
See Also:
Serialized Form

Nested Class Summary
static class JFormattedTextField.AbstractFormatter
          An abstract base implementation for a formatter that can be used by a JTextField.
static class JFormattedTextField.AbstractFormatterFactory
          Delivers instances of an JFormattedTextField.AbstractFormatter for a specific value type for a JFormattedTextField.
 
Nested classes/interfaces inherited from class javax.swing.JTextField
JTextField.AccessibleJTextField
 
Nested classes/interfaces inherited from class javax.swing.text.JTextComponent
JTextComponent.AccessibleJTextComponent, JTextComponent.KeyBinding
 
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
 
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
 
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BltBufferStrategy, Component.FlipBufferStrategy
 
Field Summary
static int COMMIT
          The possible focusLostBehavior options
static int COMMIT_OR_REVERT
           
static int PERSIST
           
static int REVERT
           
 
Fields inherited from class javax.swing.JTextField
notifyAction
 
Fields inherited from class javax.swing.text.JTextComponent
DEFAULT_KEYMAP, FOCUS_ACCELERATOR_KEY
 
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, 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 javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
 
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
 
Constructor Summary
JFormattedTextField()
          Creates a JFormattedTextField with no formatter factory.
JFormattedTextField(Format format)
          Creates a JFormattedTextField that can handle the specified Format.
JFormattedTextField(JFormattedTextField.AbstractFormatter formatter)
          Creates a JFormattedTextField with the specified formatter.
JFormattedTextField(JFormattedTextField.AbstractFormatterFactory factory)
          Creates a JFormattedTextField with the specified formatter factory.
JFormattedTextField(JFormattedTextField.AbstractFormatterFactory factory, Object value)
          Creates a JFormattedTextField with the specified formatter factory and initial value.
JFormattedTextField(Object value)
          Creates a JFormattedTextField with the specified value.
 
Method Summary
 void commitEdit()
          Forces the current value from the editor to be set as the current value.
 Action[] getActions()
          Gets the command list supplied by the UI augmented by the specific Actions for JFormattedTextField.
 int getFocusLostBehavior()
          Returns the behaviour of this JFormattedTextField upon losing focus.
 JFormattedTextField.AbstractFormatter getFormatter()
          Returns the current formatter used for this JFormattedTextField.
 JFormattedTextField.AbstractFormatterFactory getFormatterFactory()
          Returns the factory currently used to generate formatters for this JFormattedTextField.
 String getUIClassID()
          Returns the class ID for the UI.
 Object getValue()
          Returns the last valid value.
protected  void invalidEdit()
          This method is used to provide feedback to the user when an invalid value is input during editing.
 boolean isEditValid()
          Returns true if the current value being edited is valid.
protected  void processFocusEvent(FocusEvent evt)
          Processes focus events.
 void setDocument(Document newDocument)
          Associates this JFormattedTextField with a Document and propagates a PropertyChange event to each listener.
 void setFocusLostBehavior(int behavior)
          Sets the behaviour of this JFormattedTextField upon losing focus.
protected  void setFormatter(JFormattedTextField.AbstractFormatter formatter)
          Sets the formatter for this JFormattedTextField.
 void setFormatterFactory(JFormattedTextField.AbstractFormatterFactory factory)
          Sets the factory from which this JFormattedTextField should obtain its formatters.
 void setValue(Object newValue)
          Sets the value that will be formatted and displayed.
 
Methods inherited from class javax.swing.JTextField
addActionListener, configurePropertiesFromAction, createActionPropertyChangeListener, createDefaultModel, fireActionPerformed, getAccessibleContext, getAction, getActionListeners, getColumns, getColumnWidth, getHorizontalAlignment, getHorizontalVisibility, getPreferredSize, getScrollOffset, isValidateRoot, postActionEvent, removeActionListener, scrollRectToVisible, setAction, setActionCommand, setColumns, setFont, setHorizontalAlignment, setScrollOffset
 
Methods inherited from class javax.swing.text.JTextComponent
addCaretListener, addInputMethodListener, addKeymap, copy, cut, fireCaretUpdate, getCaret, getCaretColor, getCaretListeners, getCaretPosition, getDisabledTextColor, getDocument, getDragEnabled, getFocusAccelerator, getHighlighter, getInputMethodListeners, getKeymap, getKeymap, getMargin, getNavigationFilter, getPreferredScrollableViewportSize, getScrollableBlockIncrement, getScrollableTracksViewportHeight, getScrollableTracksViewportWidth, getScrollableUnitIncrement, getSelectedText, getSelectedTextColor, getSelectionColor, getSelectionEnd, getSelectionStart, getText, getText, getToolTipText, getUI, isEditable, loadKeymap, modelToView, moveCaretPosition, paramString, paste, read, removeCaretListener, removeInputMethodListener, removeKeymap, replaceSelection, select, selectAll, setCaret, setCaretColor, setCaretPosition, setDisabledTextColor, setDragEnabled, setEditable, setFocusAccelerator, setHighlighter, setKeymap, setMargin, setNavigationFilter, setSelectedTextColor, setSelectionColor, setSelectionEnd, setSelectionStart, setText, setUI, updateUI, viewToModel, write
 
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingTile, isRequestFocusEnabled, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setNextFocusableComponent, setOpaque, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
 
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalKeys, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusDownCycle, validate, validateTree
 
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getFontMetrics, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setMaximumSize, setMinimumSize, setName, setPreferredSize, setSize, setSize, show, show, size, toString, transferFocus, transferFocusBackward, transferFocusUpCycle
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

COMMIT

public static final int COMMIT
The possible focusLostBehavior options

See Also:
Constant Field Values

COMMIT_OR_REVERT

public static final int COMMIT_OR_REVERT
See Also:
Constant Field Values

REVERT

public static final int REVERT
See Also:
Constant Field Values

PERSIST

public static final int PERSIST
See Also:
Constant Field Values
Constructor Detail

JFormattedTextField

public JFormattedTextField()
Creates a JFormattedTextField with no formatter factory. setValue or setFormatterFactory will properly configure this text field to edit a particular type of value.


JFormattedTextField

public JFormattedTextField(Format format)
Creates a JFormattedTextField that can handle the specified Format. An appopriate AbstractFormatter and AbstractFormatterFactory will be created for the specified Format.

Parameters:
format - the Format that this JFormattedTextField should be able to handle

JFormattedTextField

public JFormattedTextField(JFormattedTextField.AbstractFormatter formatter)
Creates a JFormattedTextField with the specified formatter. This will create a DefaultFormatterFactory with this formatter as the default formatter.

Parameters:
formatter - the formatter to use for this JFormattedTextField

JFormattedTextField

public JFormattedTextField(JFormattedTextField.AbstractFormatterFactory factory)
Creates a JFormattedTextField with the specified formatter factory.

Parameters:
factory - the formatter factory to use for this JFormattedTextField

JFormattedTextField

public JFormattedTextField(JFormattedTextField.AbstractFormatterFactory factory,
                           Object value)
Creates a JFormattedTextField with the specified formatter factory and initial value.

Parameters:
factory - the initial formatter factory for this JFormattedTextField
value - the initial value for the text field

JFormattedTextField

public JFormattedTextField(Object value)
Creates a JFormattedTextField with the specified value. This creates a formatter and formatterFactory that are appropriate for the value.

Parameters:
value - the initial value for this JFormattedTextField
Method Detail

commitEdit

public void commitEdit()
                throws ParseException
Forces the current value from the editor to be set as the current value. If there is no current formatted this has no effect.

Throws:
ParseException - if the formatter cannot format the current value

getActions

public Action[] getActions()
Gets the command list supplied by the UI augmented by the specific Actions for JFormattedTextField.

Overrides:
getActions in class JTextField
Returns:
an array of Actions that this text field supports
See Also:
TextUI.getEditorKit(javax.swing.text.JTextComponent), EditorKit.getActions()

getFocusLostBehavior

public int getFocusLostBehavior()
Returns the behaviour of this JFormattedTextField upon losing focus. This is one of COMMIT, COMMIT_OR_REVERT, PERSIST, or REVERT.

Returns:
the behaviour upon losing focus

getFormatter

public JFormattedTextField.AbstractFormatter getFormatter()
Returns the current formatter used for this JFormattedTextField.

Returns:
the current formatter used for this JFormattedTextField

getFormatterFactory

public JFormattedTextField.AbstractFormatterFactory getFormatterFactory()
Returns the factory currently used to generate formatters for this JFormattedTextField.

Returns:
the factory currently used to generate formatters

getUIClassID

public String getUIClassID()
Description copied from class: JTextField
Returns the class ID for the UI.

Overrides:
getUIClassID in class JTextField
Returns:
"TextFieldUI";
See Also:
JComponent.setUI(javax.swing.plaf.ComponentUI), JComponent.updateUI()

getValue

public Object getValue()
Returns the last valid value. This may not be the value currently shown in the text field depending on whether or not the formatter commits on valid edits and allows invalid input to be temporarily displayed.

Returns:
the last committed valid value

invalidEdit

protected void invalidEdit()
This method is used to provide feedback to the user when an invalid value is input during editing.


isEditValid

public boolean isEditValid()
Returns true if the current value being edited is valid. This property is managed by the current formatted.

Returns:
true if the value being edited is valid.

processFocusEvent

protected void processFocusEvent(FocusEvent evt)
Processes focus events. This is overridden because we may want to change the formatted depending on whether or not this field has focus.

Overrides:
processFocusEvent in class Component
Parameters:
evt - the FocusEvent
See Also:
FocusListener, Component.addFocusListener(FocusListener), Component.enableEvents(long)

setDocument

public void setDocument(Document newDocument)
Associates this JFormattedTextField with a Document and propagates a PropertyChange event to each listener.

Overrides:
setDocument in class JTextField
Parameters:
newDocument - the Document to associate with this text field

setFocusLostBehavior

public void setFocusLostBehavior(int behavior)
Sets the behaviour of this JFormattedTextField upon losing focus. This must be COMMIT, COMMIT_OR_REVERT, PERSIST, or REVERT or an IllegalArgumentException will be thrown.

Parameters:
behavior -
Throws:
IllegalArgumentException - if behaviour is not one of the above

setFormatter

protected void setFormatter(JFormattedTextField.AbstractFormatter formatter)
Sets the formatter for this JFormattedTextField. Normally the formatter factory will take care of this, or calls to setValue will also make sure that the formatter is set appropriately.

Parameters:
formatter - the AbstractFormatter to use for formatting the value for this JFormattedTextField

setFormatterFactory

public void setFormatterFactory(JFormattedTextField.AbstractFormatterFactory factory)
Sets the factory from which this JFormattedTextField should obtain its formatters.

Parameters:
factory - the AbstractFormatterFactory that will be used to generate formatters for this JFormattedTextField

setValue

public void setValue(Object newValue)
Sets the value that will be formatted and displayed.

Parameters:
newValue - the value to be formatted and displayed