JFormattedTextField extends JTextField adding support for formatting arbitrary values, as well as retrieving a particular object once the user has edited the text. The following illustrates configuring a JFormattedTextField to edit dates:

  JFormattedTextField ftf = new JFormattedTextField();
  ftf.setValue(new Date());

Once a JFormattedTextField has been created, you can listen for editing changes by way of adding a PropertyChangeListener and listening for PropertyChangeEvents with the property name value.

JFormattedTextField allows configuring what action should be taken when focus is lost. The possible configurations are:

Possible JFormattedTextField configurations and their descriptions
Value	Description
JFormattedTextField.REVERT	Revert the display to match that of `getValue`, possibly losing the current edit.
JFormattedTextField.COMMIT	Commits the current value. If the value being edited isn't considered a legal value by the `AbstractFormatter` that is, a `ParseException` is thrown, then the value will not change, and then edited value will persist.
JFormattedTextField.COMMIT_OR_REVERT	Similar to `COMMIT`, but if the value isn't legal, behave like `REVERT`.
JFormattedTextField.PERSIST	Do nothing, don't obtain a new `AbstractFormatter`, and don't update the value.

The default is JFormattedTextField.COMMIT_OR_REVERT, refer to setFocusLostBehavior for more information on this.

JFormattedTextField allows the focus to leave, even if the currently edited value is invalid. To lock the focus down while the JFormattedTextField is an invalid edit state you can attach an InputVerifier. The following code snippet shows a potential implementation of such an InputVerifier:

public class FormattedTextFieldVerifier extends InputVerifier {
    public boolean verify(JComponent input) {
        if (input instanceof JFormattedTextField) {
            JFormattedTextField ftf = (JFormattedTextField)input;
            AbstractFormatter formatter = ftf.getFormatter();
            if (formatter != null) {
                String text = ftf.getText();
                try {
                     formatter.stringToValue(text);
                     return true;
                 } catch (ParseException pe) {
                     return false;
                 }
             }
         }
         return true;
     }
     public boolean shouldYieldFocus(JComponent input) {
         return verify(input);
     }
 }

Alternatively, you could invoke commitEdit, which would also commit the value.

JFormattedTextField does not do the formatting itself, rather formatting is done through an instance of JFormattedTextField.AbstractFormatter which is obtained from an instance of JFormattedTextField.AbstractFormatterFactory. Instances of JFormattedTextField.AbstractFormatter are notified when they become active by way of the install method, at which point the JFormattedTextField.AbstractFormatter can install whatever it needs to, typically a DocumentFilter. Similarly, when JFormattedTextField no longer needs the AbstractFormatter, it will invoke uninstall.

JFormattedTextField typically queries the AbstractFormatterFactory for an AbstractFormat when it gains or loses focus. Although this can change based on the focus lost policy. If the focus lost policy is JFormattedTextField.PERSIST and the JFormattedTextField has been edited, the AbstractFormatterFactory will not be queried until the value has been committed. Similarly, if the focus lost policy is JFormattedTextField.COMMIT and an exception is thrown from stringToValue, the AbstractFormatterFactory will not be queried when focus is lost or gained.

JFormattedTextField.AbstractFormatter is also responsible for determining when values are committed to the JFormattedTextField. Some JFormattedTextField.AbstractFormatters will make new values available on every edit, and others will never commit the value. You can force the current value to be obtained from the current JFormattedTextField.AbstractFormatter by way of invoking commitEdit. commitEdit will be invoked whenever return is pressed in the JFormattedTextField.

If an AbstractFormatterFactory has not been explicitly set, one will be set based on the Class of the value type after setValue has been invoked (assuming value is non-null). For example, in the following code an appropriate AbstractFormatterFactory and AbstractFormatter will be created to handle formatting of numbers:

  JFormattedTextField tf = new JFormattedTextField();
  tf.setValue(100);

Warning

As the AbstractFormatter will typically install a DocumentFilter on the Document, and a NavigationFilter on the JFormattedTextField you should not install your own. If you do, you are likely to see odd behavior in that the editing policy of the AbstractFormatter will not be enforced.

Warning

Swing is not thread safe. For more information see Swing's Threading Policy.

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 has been added to the java.beans package. Please see java.beans.XMLEncoder.

Nested and Inner Type Summary

Modifier and Type	Class and Description
public abstract static class	JFormattedTextField.AbstractFormatter Instances of `AbstractFormatter` are used by `JFormattedTextField` to handle the conversion both from an Object to a String, and back from a String to an Object.
public abstract static class	JFormattedTextField.AbstractFormatterFactory Instances of `AbstractFormatterFactory` are used by `JFormattedTextField` to obtain instances of `AbstractFormatter` which in turn are used to format values.
private static class	JFormattedTextField.CancelAction CancelAction will reset the value in the JFormattedTextField when `actionPerformed` is invoked.
pack-priv static class	JFormattedTextField.CommitAction Used to commit the edit.
private class	JFormattedTextField.DocumentHandler Sets the dirty state as the document changes.
private class	JFormattedTextField.FocusLostHandler FOCUS_LOST behavior implementation

Field Summary

Modifier and Type	Field and Description
public static final int	COMMIT Constant identifying that when focus is lost, `commitEdit` should be invoked.
public static final int	COMMIT_OR_REVERT Constant identifying that when focus is lost, `commitEdit` should be invoked.
private boolean	composedTextExists Indicates the input method composed text is in the document
private static final Action[]	defaultActions Hides javax.swing.JTextField.defaultActions.
private DocumentListener	documentListener Used to set the dirty state.
private boolean	edited Indicates the current value has been edited.
private boolean	editValid True while the value being edited is valid.
private JFormattedTextField.AbstractFormatterFactory	factory Factory used to obtain an instance of AbstractFormatter.
private int	focusLostBehavior Behavior when focus is lost.
private JFormattedTextField.FocusLostHandler	focusLostHandler A handler for FOCUS_LOST event
private JFormattedTextField.AbstractFormatter	format Object responsible for formatting the current value.
public static final int	PERSIST Constant identifying that when focus is lost, the edited value should be left.
public static final int	REVERT Constant identifying that when focus is lost, editing value should be reverted to current value set on the `JFormattedTextField`.
private ActionMap	textFormatterActionMap ActionMap that the TextFormatter Actions are added to.
private static final String	uiClassID Hides javax.swing.JTextField.uiClassID.
private Object	value Last valid value.

Inherited from javax.swing.JTextField:: notifyAction

Constructor Summary

Access	Constructor and Description
public	JFormattedTextField() Creates a `JFormattedTextField` with no `AbstractFormatterFactory`.
public	JFormattedTextField(Object Initial value for the JFormattedTextField value) Creates a JFormattedTextField with the specified value.
public	JFormattedTextField(Format Format used to look up an AbstractFormatter format) Creates a `JFormattedTextField`.
public	JFormattedTextField(JFormattedTextField.AbstractFormatter AbstractFormatter to use for formatting. formatter) Creates a `JFormattedTextField` with the specified `AbstractFormatter`.
public	JFormattedTextField(JFormattedTextField.AbstractFormatterFactory AbstractFormatterFactory used for formatting. factory) Creates a `JFormattedTextField` with the specified `AbstractFormatterFactory`.
public	JFormattedTextField(JFormattedTextField.AbstractFormatterFactory `AbstractFormatterFactory` used for formatting. factory, Object Initial value to use currentValue) Creates a `JFormattedTextField` with the specified `AbstractFormatterFactory` and initial value.

Method Summary

Modifier and Type	Method and Description
public void	commitEdit() Forces the current value to be taken from the `AbstractFormatter` and set as the current value.
public Action[]	Returns: the command list getActions() Overrides javax.swing.JTextField.getActions. Fetches the command list for the editor.
private JFormattedTextField.AbstractFormatterFactory	getDefaultFormatterFactory(Object type) Returns an AbstractFormatterFactory suitable for the passed in Object type.
public int	Returns: returns behavior when focus is lost getFocusLostBehavior() Returns the behavior when focus is lost.
public JFormattedTextField.AbstractFormatter	Returns: AbstractFormatter used for formatting getFormatter() Returns the `AbstractFormatter` that is used to format and parse the current value.
public JFormattedTextField.AbstractFormatterFactory	Returns: `AbstractFormatterFactory` used to determine `AbstractFormatter`s getFormatterFactory() Returns the current `AbstractFormatterFactory`.
public String	Returns: the string "FormattedTextFieldUI" getUIClassID() Overrides javax.swing.JTextField.getUIClassID. Gets the class ID for a UI.
public Object	Returns: Last valid value getValue() Returns the last valid value.
protected void	invalidEdit() Invoked when the user inputs an invalid value.
private boolean	isEdited() Returns true if the receiver has been edited.
public boolean	Returns: true if the current value being edited is valid. isEditValid() Returns true if the current value being edited is valid.
protected void	processFocusEvent(FocusEvent the `FocusEvent` e) Overrides java.awt.Component.processFocusEvent. Processes any focus events, such as `FocusEvent.FOCUS_GAINED` or `FocusEvent.FOCUS_LOST`.
protected void	processInputMethodEvent(InputMethodEvent the `InputMethodEvent` e) Overrides javax.swing.text.JTextComponent.processInputMethodEvent. Processes any input method events, such as `InputMethodEvent.INPUT_METHOD_TEXT_CHANGED` or `InputMethodEvent.CARET_POSITION_CHANGED`.
public void	setDocument(Document the document to display/edit doc) Overrides javax.swing.JTextField.setDocument. Associates the editor with a text document.
private void	setEdited(boolean edited) Sets the edited state of the receiver.
private void	setEditValid(boolean boolean indicating if the currently edited value is valid. isValid) Sets the validity of the edit on the receiver.
public void	setFocusLostBehavior(int Identifies behavior when focus is lost behavior) Sets the behavior when focus is lost.
protected void	setFormatter(JFormattedTextField.AbstractFormatter AbstractFormatter to use for formatting format) Sets the current `AbstractFormatter`.
private void	setFormatterActions(Action[] actions) Resets the Actions that come from the TextFormatter to `actions`.
public void	setFormatterFactory(JFormattedTextField.AbstractFormatterFactory `AbstractFormatterFactory` used to lookup instances of `AbstractFormatter` tf) Sets the `AbstractFormatterFactory`.
public void	setValue(Object Current value to display value) Sets the value that will be formatted by an `AbstractFormatter` obtained from the current `AbstractFormatterFactory`.
private void	setValue(Object value, boolean createFormat, boolean firePC) Does the setting of the value.
private void	writeObject(ObjectOutputStream s) Hides javax.swing.JTextField.writeObject. See `readObject` and `writeObject` in `JComponent` for more information about serialization in Swing.

Field Detail

COMMIT back to summary

COMMIT	back to summary
public static final int COMMIT Constant identifying that when focus is lost, `commitEdit` should be invoked. If in committing the new value a `ParseException` is thrown, the invalid value will remain. See Also `setFocusLostBehavior`

public static final int COMMIT

Constant identifying that when focus is lost, commitEdit should be invoked. If in committing the new value a ParseException is thrown, the invalid value will remain.

See Also: setFocusLostBehavior

COMMIT_OR_REVERT back to summary

COMMIT_OR_REVERT	back to summary
public static final int COMMIT_OR_REVERT Constant identifying that when focus is lost, `commitEdit` should be invoked. If in committing the new value a `ParseException` is thrown, the value will be reverted. See Also `setFocusLostBehavior`

public static final int COMMIT_OR_REVERT

Constant identifying that when focus is lost, commitEdit should be invoked. If in committing the new value a ParseException is thrown, the value will be reverted.

See Also: setFocusLostBehavior

composedTextExists	back to summary
private boolean composedTextExists Indicates the input method composed text is in the document

defaultActions	back to summary
private static final Action[] defaultActions Hides javax.swing.JTextField.defaultActions.

documentListener	back to summary
private DocumentListener documentListener Used to set the dirty state.

edited	back to summary
private boolean edited Indicates the current value has been edited.

editValid	back to summary
private boolean editValid True while the value being edited is valid.

factory	back to summary
private JFormattedTextField.AbstractFormatterFactory factory Factory used to obtain an instance of AbstractFormatter.

focusLostBehavior	back to summary
private int focusLostBehavior Behavior when focus is lost.

focusLostHandler	back to summary
private JFormattedTextField.FocusLostHandler focusLostHandler A handler for FOCUS_LOST event

format	back to summary
private JFormattedTextField.AbstractFormatter format Object responsible for formatting the current value.

PERSIST back to summary

PERSIST	back to summary
public static final int PERSIST Constant identifying that when focus is lost, the edited value should be left. See Also `setFocusLostBehavior`

public static final int PERSIST

Constant identifying that when focus is lost, the edited value should be left.

See Also: setFocusLostBehavior

REVERT back to summary

REVERT	back to summary
public static final int REVERT Constant identifying that when focus is lost, editing value should be reverted to current value set on the `JFormattedTextField`. See Also `setFocusLostBehavior`

public static final int REVERT

Constant identifying that when focus is lost, editing value should be reverted to current value set on the JFormattedTextField.

See Also: setFocusLostBehavior

textFormatterActionMap	back to summary
private ActionMap textFormatterActionMap ActionMap that the TextFormatter Actions are added to.

uiClassID	back to summary
private static final String uiClassID Hides javax.swing.JTextField.uiClassID.

value	back to summary
private Object value Last valid value.