JFormattedTextField (Java Platform SE 8 ) (original) (raw)

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 forPropertyChangeEvents with the property name value.

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

The default is JFormattedTextField.COMMIT_OR_REVERT, refer to setFocusLostBehavior(int) 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 theJFormattedTextField 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 it self, rather formatting is done through an instance ofJFormattedTextField.AbstractFormatter which is obtained from an instance of JFormattedTextField.AbstractFormatterFactory. Instances of JFormattedTextField.AbstractFormatter are notified when they become active by way of theinstall method, at which point theJFormattedTextField.AbstractFormatter can install whatever it needs to, typically a DocumentFilter. Similarly whenJFormattedTextField no longer needs the AbstractFormatter, it will invokeuninstall.

JFormattedTextField typically queries the AbstractFormatterFactory for anAbstractFormat 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, theAbstractFormatterFactory will not be queried until the value has been committed. Similarly if the focus lost policy isJFormattedTextField.COMMIT and an exception is thrown from stringToValue, theAbstractFormatterFactory will not be queried when focus is lost or gained.

JFormattedTextField.AbstractFormatter is also responsible for determining when values are committed to the JFormattedTextField. SomeJFormattedTextField.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 theJFormattedTextField.

If an AbstractFormatterFactory has not been explicitly set, one will be set based on the Class of the value type aftersetValue has been invoked (assuming value is non-null). For example, in the following code an appropriateAbstractFormatterFactory 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 theDocument, and a NavigationFilter on theJFormattedTextField you should not install your own. If you do, you are likely to see odd behavior in that the editing policy of theAbstractFormatter 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 XMLEncoder.