/*
 * Copyright (c) 2000, 2017, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */
package javax.swing;

import java.awt.*;
import java.awt.event.*;
import java.awt.im.InputContext;
import java.beans.BeanProperty;
import java.beans.JavaBean;
import java.io.*;
import java.text.*;
import java.util.*;
import javax.swing.event.*;
import javax.swing.plaf.UIResource;
import javax.swing.text.*;

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 it self, 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 XMLEncoder.

Since:1.4
/** * <code>JFormattedTextField</code> extends <code>JTextField</code> 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 <code>JFormattedTextField</code> to edit dates: * <pre> * JFormattedTextField ftf = new JFormattedTextField(); * ftf.setValue(new Date()); * </pre> * <p> * Once a <code>JFormattedTextField</code> has been created, you can * listen for editing changes by way of adding * a <code>PropertyChangeListener</code> and listening for * <code>PropertyChangeEvent</code>s with the property name <code>value</code>. * <p> * <code>JFormattedTextField</code> allows * configuring what action should be taken when focus is lost. The possible * configurations are: * * <table class="striped"> * <caption>Possible JFormattedTextField configurations and their descriptions * </caption> * <thead> * <tr> * <th scope="col">Value * <th scope="col">Description * </thead> * <tbody> * <tr> * <th scope="row">JFormattedTextField.REVERT * <td>Revert the display to match that of {@code getValue}, possibly losing * the current edit. * <tr> * <th scope="row">JFormattedTextField.COMMIT * <td>Commits the current value. If the value being edited isn't considered * a legal value by the {@code AbstractFormatter} that is, a * {@code ParseException} is thrown, then the value will not change, and * then edited value will persist. * <tr> * <th scope="row">JFormattedTextField.COMMIT_OR_REVERT * <td>Similar to {@code COMMIT}, but if the value isn't legal, behave like * {@code REVERT}. * <tr> * <th scope="row">JFormattedTextField.PERSIST * <td>Do nothing, don't obtain a new {@code AbstractFormatter}, and don't * update the value. * </tbody> * </table> * * The default is <code>JFormattedTextField.COMMIT_OR_REVERT</code>, * refer to {@link #setFocusLostBehavior} for more information on this. * <p> * <code>JFormattedTextField</code> allows the focus to leave, even if * the currently edited value is invalid. To lock the focus down while the * <code>JFormattedTextField</code> is an invalid edit state * you can attach an <code>InputVerifier</code>. The following code snippet * shows a potential implementation of such an <code>InputVerifier</code>: * <pre> * 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); * } * } * </pre> * <p> * Alternatively, you could invoke <code>commitEdit</code>, which would also * commit the value. * <p> * <code>JFormattedTextField</code> does not do the formatting it self, * rather formatting is done through an instance of * <code>JFormattedTextField.AbstractFormatter</code> which is obtained from * an instance of <code>JFormattedTextField.AbstractFormatterFactory</code>. * Instances of <code>JFormattedTextField.AbstractFormatter</code> are * notified when they become active by way of the * <code>install</code> method, at which point the * <code>JFormattedTextField.AbstractFormatter</code> can install whatever * it needs to, typically a <code>DocumentFilter</code>. Similarly when * <code>JFormattedTextField</code> no longer * needs the <code>AbstractFormatter</code>, it will invoke * <code>uninstall</code>. * <p> * <code>JFormattedTextField</code> typically * queries the <code>AbstractFormatterFactory</code> for an * <code>AbstractFormat</code> when it gains or loses focus. Although this * can change based on the focus lost policy. If the focus lost * policy is <code>JFormattedTextField.PERSIST</code> * and the <code>JFormattedTextField</code> has been edited, the * <code>AbstractFormatterFactory</code> will not be queried until the * value has been committed. Similarly if the focus lost policy is * <code>JFormattedTextField.COMMIT</code> and an exception * is thrown from <code>stringToValue</code>, the * <code>AbstractFormatterFactory</code> will not be queried when focus is * lost or gained. * <p> * <code>JFormattedTextField.AbstractFormatter</code> * is also responsible for determining when values are committed to * the <code>JFormattedTextField</code>. Some * <code>JFormattedTextField.AbstractFormatter</code>s 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 <code>JFormattedTextField.AbstractFormatter</code> * by way of invoking <code>commitEdit</code>. <code>commitEdit</code> will * be invoked whenever return is pressed in the * <code>JFormattedTextField</code>. * <p> * If an <code>AbstractFormatterFactory</code> has not been explicitly * set, one will be set based on the <code>Class</code> of the value type after * <code>setValue</code> has been invoked (assuming value is non-null). * For example, in the following code an appropriate * <code>AbstractFormatterFactory</code> and <code>AbstractFormatter</code> * will be created to handle formatting of numbers: * <pre> * JFormattedTextField tf = new JFormattedTextField(); * tf.setValue(100); * </pre> * <p> * <strong>Warning:</strong> As the <code>AbstractFormatter</code> will * typically install a <code>DocumentFilter</code> on the * <code>Document</code>, and a <code>NavigationFilter</code> on the * <code>JFormattedTextField</code> you should not install your own. If you do, * you are likely to see odd behavior in that the editing policy of the * <code>AbstractFormatter</code> will not be enforced. * <p> * <strong>Warning:</strong> Swing is not thread safe. For more * information see <a * href="package-summary.html#threading">Swing's Threading * Policy</a>. * <p> * <strong>Warning:</strong> * 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 <code>java.beans</code> package. * Please see {@link java.beans.XMLEncoder}. * * @since 1.4 */
@JavaBean @SuppressWarnings("serial") // Same-version serialization only public class JFormattedTextField extends JTextField { private static final String uiClassID = "FormattedTextFieldUI"; private static final Action[] defaultActions = { new CommitAction(), new CancelAction() };
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
/** * Constant identifying that when focus is lost, * <code>commitEdit</code> should be invoked. If in committing the * new value a <code>ParseException</code> is thrown, the invalid * value will remain. * * @see #setFocusLostBehavior */
public static final int COMMIT = 0;
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
/** * Constant identifying that when focus is lost, * <code>commitEdit</code> should be invoked. If in committing the new * value a <code>ParseException</code> is thrown, the value will be * reverted. * * @see #setFocusLostBehavior */
public static final int COMMIT_OR_REVERT = 1;
Constant identifying that when focus is lost, editing value should be reverted to current value set on the JFormattedTextField.
See Also:
  • setFocusLostBehavior
/** * Constant identifying that when focus is lost, editing value should * be reverted to current value set on the * <code>JFormattedTextField</code>. * * @see #setFocusLostBehavior */
public static final int REVERT = 2;
Constant identifying that when focus is lost, the edited value should be left.
See Also:
  • setFocusLostBehavior
/** * Constant identifying that when focus is lost, the edited value * should be left. * * @see #setFocusLostBehavior */
public static final int PERSIST = 3;
Factory used to obtain an instance of AbstractFormatter.
/** * Factory used to obtain an instance of AbstractFormatter. */
private AbstractFormatterFactory factory;
Object responsible for formatting the current value.
/** * Object responsible for formatting the current value. */
private AbstractFormatter format;
Last valid value.
/** * Last valid value. */
private Object value;
True while the value being edited is valid.
/** * True while the value being edited is valid. */
private boolean editValid;
Behavior when focus is lost.
/** * Behavior when focus is lost. */
private int focusLostBehavior;
Indicates the current value has been edited.
/** * Indicates the current value has been edited. */
private boolean edited;
Used to set the dirty state.
/** * Used to set the dirty state. */
private DocumentListener documentListener;
Masked used to set the AbstractFormatterFactory.
/** * Masked used to set the AbstractFormatterFactory. */
private Object mask;
ActionMap that the TextFormatter Actions are added to.
/** * ActionMap that the TextFormatter Actions are added to. */
private ActionMap textFormatterActionMap;
Indicates the input method composed text is in the document
/** * Indicates the input method composed text is in the document */
private boolean composedTextExists = false;
A handler for FOCUS_LOST event
/** * A handler for FOCUS_LOST event */
private FocusLostHandler focusLostHandler;
Creates a JFormattedTextField with no AbstractFormatterFactory. Use setMask or setFormatterFactory to configure the JFormattedTextField to edit a particular type of value.
/** * Creates a <code>JFormattedTextField</code> with no * <code>AbstractFormatterFactory</code>. Use <code>setMask</code> or * <code>setFormatterFactory</code> to configure the * <code>JFormattedTextField</code> to edit a particular type of * value. */
public JFormattedTextField() { super(); enableEvents(AWTEvent.FOCUS_EVENT_MASK); setFocusLostBehavior(COMMIT_OR_REVERT); }
Creates a JFormattedTextField with the specified value. This will create an AbstractFormatterFactory based on the type of value.
Params:
  • value – Initial value for the JFormattedTextField
/** * Creates a JFormattedTextField with the specified value. This will * create an <code>AbstractFormatterFactory</code> based on the * type of <code>value</code>. * * @param value Initial value for the JFormattedTextField */
public JFormattedTextField(Object value) { this(); setValue(value); }
Creates a JFormattedTextField. format is wrapped in an appropriate AbstractFormatter which is then wrapped in an AbstractFormatterFactory.
Params:
  • format – Format used to look up an AbstractFormatter
/** * Creates a <code>JFormattedTextField</code>. <code>format</code> is * wrapped in an appropriate <code>AbstractFormatter</code> which is * then wrapped in an <code>AbstractFormatterFactory</code>. * * @param format Format used to look up an AbstractFormatter */
public JFormattedTextField(java.text.Format format) { this(); setFormatterFactory(getDefaultFormatterFactory(format)); }
Creates a JFormattedTextField with the specified AbstractFormatter. The AbstractFormatter is placed in an AbstractFormatterFactory.
Params:
  • formatter – AbstractFormatter to use for formatting.
/** * Creates a <code>JFormattedTextField</code> with the specified * <code>AbstractFormatter</code>. The <code>AbstractFormatter</code> * is placed in an <code>AbstractFormatterFactory</code>. * * @param formatter AbstractFormatter to use for formatting. */
public JFormattedTextField(AbstractFormatter formatter) { this(new DefaultFormatterFactory(formatter)); }
Creates a JFormattedTextField with the specified AbstractFormatterFactory.
Params:
  • factory – AbstractFormatterFactory used for formatting.
/** * Creates a <code>JFormattedTextField</code> with the specified * <code>AbstractFormatterFactory</code>. * * @param factory AbstractFormatterFactory used for formatting. */
public JFormattedTextField(AbstractFormatterFactory factory) { this(); setFormatterFactory(factory); }
Creates a JFormattedTextField with the specified AbstractFormatterFactory and initial value.
Params:
  • factory – AbstractFormatterFactory used for formatting.
  • currentValue – Initial value to use
/** * Creates a <code>JFormattedTextField</code> with the specified * <code>AbstractFormatterFactory</code> and initial value. * * @param factory <code>AbstractFormatterFactory</code> used for * formatting. * @param currentValue Initial value to use */
public JFormattedTextField(AbstractFormatterFactory factory, Object currentValue) { this(currentValue); setFormatterFactory(factory); }
Sets the behavior when focus is lost. This will be one of JFormattedTextField.COMMIT_OR_REVERT, JFormattedTextField.REVERT, JFormattedTextField.COMMIT or JFormattedTextField.PERSIST Note that some AbstractFormatters may push changes as they occur, so that the value of this will have no effect.

This will throw an IllegalArgumentException if the object passed in is not one of the afore mentioned values.

The default value of this property is JFormattedTextField.COMMIT_OR_REVERT.

Params:
  • behavior – Identifies behavior when focus is lost
Throws:
/** * Sets the behavior when focus is lost. This will be one of * <code>JFormattedTextField.COMMIT_OR_REVERT</code>, * <code>JFormattedTextField.REVERT</code>, * <code>JFormattedTextField.COMMIT</code> or * <code>JFormattedTextField.PERSIST</code> * Note that some <code>AbstractFormatter</code>s may push changes as * they occur, so that the value of this will have no effect. * <p> * This will throw an <code>IllegalArgumentException</code> if the object * passed in is not one of the afore mentioned values. * <p> * The default value of this property is * <code>JFormattedTextField.COMMIT_OR_REVERT</code>. * * @param behavior Identifies behavior when focus is lost * @throws IllegalArgumentException if behavior is not one of the known * values */
@BeanProperty(bound = false, enumerationValues = { "JFormattedTextField.COMMIT", "JFormattedTextField.COMMIT_OR_REVERT", "JFormattedTextField.REVERT", "JFormattedTextField.PERSIST"}, description = "Behavior when component loses focus") public void setFocusLostBehavior(int behavior) { if (behavior != COMMIT && behavior != COMMIT_OR_REVERT && behavior != PERSIST && behavior != REVERT) { throw new IllegalArgumentException("setFocusLostBehavior must be one of: JFormattedTextField.COMMIT, JFormattedTextField.COMMIT_OR_REVERT, JFormattedTextField.PERSIST or JFormattedTextField.REVERT"); } focusLostBehavior = behavior; }
Returns the behavior when focus is lost. This will be one of COMMIT_OR_REVERT, COMMIT, REVERT or PERSIST Note that some AbstractFormatters may push changes as they occur, so that the value of this will have no effect.
Returns:returns behavior when focus is lost
/** * Returns the behavior when focus is lost. This will be one of * <code>COMMIT_OR_REVERT</code>, * <code>COMMIT</code>, * <code>REVERT</code> or * <code>PERSIST</code> * Note that some <code>AbstractFormatter</code>s may push changes as * they occur, so that the value of this will have no effect. * * @return returns behavior when focus is lost */
public int getFocusLostBehavior() { return focusLostBehavior; }
Sets the AbstractFormatterFactory. AbstractFormatterFactory is able to return an instance of AbstractFormatter that is used to format a value for display, as well an enforcing an editing policy.

If you have not explicitly set an AbstractFormatterFactory by way of this method (or a constructor) an AbstractFormatterFactory and consequently an AbstractFormatter will be used based on the Class of the value. NumberFormatter will be used for Numbers, DateFormatter will be used for Dates, otherwise DefaultFormatter will be used.

This is a JavaBeans bound property.

Params:
  • tf – AbstractFormatterFactory used to lookup instances of AbstractFormatter
/** * Sets the <code>AbstractFormatterFactory</code>. * <code>AbstractFormatterFactory</code> is * able to return an instance of <code>AbstractFormatter</code> that is * used to format a value for display, as well an enforcing an editing * policy. * <p> * If you have not explicitly set an <code>AbstractFormatterFactory</code> * by way of this method (or a constructor) an * <code>AbstractFormatterFactory</code> and consequently an * <code>AbstractFormatter</code> will be used based on the * <code>Class</code> of the value. <code>NumberFormatter</code> will * be used for <code>Number</code>s, <code>DateFormatter</code> will * be used for <code>Dates</code>, otherwise <code>DefaultFormatter</code> * will be used. * <p> * This is a JavaBeans bound property. * * @param tf <code>AbstractFormatterFactory</code> used to lookup * instances of <code>AbstractFormatter</code> */
@BeanProperty(visualUpdate = true, description = "AbstractFormatterFactory, responsible for returning an AbstractFormatter that can format the current value.") public void setFormatterFactory(AbstractFormatterFactory tf) { AbstractFormatterFactory oldFactory = factory; factory = tf; firePropertyChange("formatterFactory", oldFactory, tf); setValue(getValue(), true, false); }
Returns the current AbstractFormatterFactory.
See Also:
  • setFormatterFactory
Returns:AbstractFormatterFactory used to determine AbstractFormatters
/** * Returns the current <code>AbstractFormatterFactory</code>. * * @see #setFormatterFactory * @return <code>AbstractFormatterFactory</code> used to determine * <code>AbstractFormatter</code>s */
public AbstractFormatterFactory getFormatterFactory() { return factory; }
Sets the current AbstractFormatter.

You should not normally invoke this, instead set the AbstractFormatterFactory or set the value. JFormattedTextField will invoke this as the state of the JFormattedTextField changes and requires the value to be reset. JFormattedTextField passes in the AbstractFormatter obtained from the AbstractFormatterFactory.

This is a JavaBeans bound property.

Params:
  • format – AbstractFormatter to use for formatting
See Also:
  • setFormatterFactory
/** * Sets the current <code>AbstractFormatter</code>. * <p> * You should not normally invoke this, instead set the * <code>AbstractFormatterFactory</code> or set the value. * <code>JFormattedTextField</code> will * invoke this as the state of the <code>JFormattedTextField</code> * changes and requires the value to be reset. * <code>JFormattedTextField</code> passes in the * <code>AbstractFormatter</code> obtained from the * <code>AbstractFormatterFactory</code>. * <p> * This is a JavaBeans bound property. * * @see #setFormatterFactory * @param format AbstractFormatter to use for formatting */
protected void setFormatter(AbstractFormatter format) { AbstractFormatter oldFormat = this.format; if (oldFormat != null) { oldFormat.uninstall(); } setEditValid(true); this.format = format; if (format != null) { format.install(this); } setEdited(false); firePropertyChange("textFormatter", oldFormat, format); }
Returns the AbstractFormatter that is used to format and parse the current value.
Returns:AbstractFormatter used for formatting
/** * Returns the <code>AbstractFormatter</code> that is used to format and * parse the current value. * * @return AbstractFormatter used for formatting */
@BeanProperty(visualUpdate = true, description = "TextFormatter, responsible for formatting the current value") public AbstractFormatter getFormatter() { return format; }
Sets the value that will be formatted by an AbstractFormatter obtained from the current AbstractFormatterFactory. If no AbstractFormatterFactory has been specified, this will attempt to create one based on the type of value.

The default value of this property is null.

This is a JavaBeans bound property.

Params:
  • value – Current value to display
/** * Sets the value that will be formatted by an * <code>AbstractFormatter</code> obtained from the current * <code>AbstractFormatterFactory</code>. If no * <code>AbstractFormatterFactory</code> has been specified, this will * attempt to create one based on the type of <code>value</code>. * <p> * The default value of this property is null. * <p> * This is a JavaBeans bound property. * * @param value Current value to display */
@BeanProperty(visualUpdate = true, description = "The value to be formatted.") public void setValue(Object value) { if (value != null && getFormatterFactory() == null) { setFormatterFactory(getDefaultFormatterFactory(value)); } setValue(value, true, true); }
Returns the last valid value. Based on the editing policy of the AbstractFormatter this may not return the current value. The currently edited value can be obtained by invoking commitEdit followed by getValue.
Returns:Last valid value
/** * Returns the last valid value. Based on the editing policy of * the <code>AbstractFormatter</code> this may not return the current * value. The currently edited value can be obtained by invoking * <code>commitEdit</code> followed by <code>getValue</code>. * * @return Last valid value */
public Object getValue() { return value; }
Forces the current value to be taken from the AbstractFormatter and set as the current value. This has no effect if there is no current AbstractFormatter installed.
Throws:
  • ParseException – if the AbstractFormatter is not able to format the current value
/** * Forces the current value to be taken from the * <code>AbstractFormatter</code> and set as the current value. * This has no effect if there is no current * <code>AbstractFormatter</code> installed. * * @throws ParseException if the <code>AbstractFormatter</code> is not able * to format the current value */
public void commitEdit() throws ParseException { AbstractFormatter format = getFormatter(); if (format != null) { setValue(format.stringToValue(getText()), false, true); } }
Sets the validity of the edit on the receiver. You should not normally invoke this. This will be invoked by the AbstractFormatter as the user edits the value.

Not all formatters will allow the component to get into an invalid state, and thus this may never be invoked.

Based on the look and feel this may visually change the state of the receiver.

Params:
  • isValid – boolean indicating if the currently edited value is valid.
/** * Sets the validity of the edit on the receiver. You should not normally * invoke this. This will be invoked by the * <code>AbstractFormatter</code> as the user edits the value. * <p> * Not all formatters will allow the component to get into an invalid * state, and thus this may never be invoked. * <p> * Based on the look and feel this may visually change the state of * the receiver. * * @param isValid boolean indicating if the currently edited value is * valid. */
@BeanProperty(visualUpdate = true, description = "True indicates the edited value is valid") private void setEditValid(boolean isValid) { if (isValid != editValid) { editValid = isValid; firePropertyChange("editValid", Boolean.valueOf(!isValid), Boolean.valueOf(isValid)); } }
Returns true if the current value being edited is valid. The value of this is managed by the current AbstractFormatter, as such there is no public setter for it.
Returns:true if the current value being edited is valid.
/** * Returns true if the current value being edited is valid. The value of * this is managed by the current <code>AbstractFormatter</code>, as such * there is no public setter for it. * * @return true if the current value being edited is valid. */
@BeanProperty(bound = false) public boolean isEditValid() { return editValid; }
Invoked when the user inputs an invalid value. This gives the component a chance to provide feedback. The default implementation beeps.
/** * Invoked when the user inputs an invalid value. This gives the * component a chance to provide feedback. The default * implementation beeps. */
protected void invalidEdit() { UIManager.getLookAndFeel().provideErrorFeedback(JFormattedTextField.this); }
Processes any input method events, such as InputMethodEvent.INPUT_METHOD_TEXT_CHANGED or InputMethodEvent.CARET_POSITION_CHANGED.
Params:
  • e – the InputMethodEvent
See Also:
/** * Processes any input method events, such as * <code>InputMethodEvent.INPUT_METHOD_TEXT_CHANGED</code> or * <code>InputMethodEvent.CARET_POSITION_CHANGED</code>. * * @param e the <code>InputMethodEvent</code> * @see InputMethodEvent */
protected void processInputMethodEvent(InputMethodEvent e) { AttributedCharacterIterator text = e.getText(); int commitCount = e.getCommittedCharacterCount(); // Keep track of the composed text if (text != null) { int begin = text.getBeginIndex(); int end = text.getEndIndex(); composedTextExists = ((end - begin) > commitCount); } else { composedTextExists = false; } super.processInputMethodEvent(e); }
Processes any focus events, such as FocusEvent.FOCUS_GAINED or FocusEvent.FOCUS_LOST.
Params:
  • e – the FocusEvent
See Also:
/** * Processes any focus events, such as * <code>FocusEvent.FOCUS_GAINED</code> or * <code>FocusEvent.FOCUS_LOST</code>. * * @param e the <code>FocusEvent</code> * @see FocusEvent */
protected void processFocusEvent(FocusEvent e) { super.processFocusEvent(e); // ignore temporary focus event if (e.isTemporary()) { return; } if (isEdited() && e.getID() == FocusEvent.FOCUS_LOST) { InputContext ic = getInputContext(); if (focusLostHandler == null) { focusLostHandler = new FocusLostHandler(); } // if there is a composed text, process it first if ((ic != null) && composedTextExists) { ic.endComposition(); EventQueue.invokeLater(focusLostHandler); } else { focusLostHandler.run(); } } else if (!isEdited()) { // reformat setValue(getValue(), true, true); } }
FOCUS_LOST behavior implementation
/** * FOCUS_LOST behavior implementation */
private class FocusLostHandler implements Runnable, Serializable { public void run() { int fb = JFormattedTextField.this.getFocusLostBehavior(); if (fb == JFormattedTextField.COMMIT || fb == JFormattedTextField.COMMIT_OR_REVERT) { try { JFormattedTextField.this.commitEdit(); // Give it a chance to reformat. JFormattedTextField.this.setValue( JFormattedTextField.this.getValue(), true, true); } catch (ParseException pe) { if (fb == JFormattedTextField.COMMIT_OR_REVERT) { JFormattedTextField.this.setValue( JFormattedTextField.this.getValue(), true, true); } } } else if (fb == JFormattedTextField.REVERT) { JFormattedTextField.this.setValue( JFormattedTextField.this.getValue(), true, true); } } }
Fetches the command list for the editor. This is the list of commands supported by the plugged-in UI augmented by the collection of commands that the editor itself supports. These are useful for binding to events, such as in a keymap.
Returns:the command list
/** * Fetches the command list for the editor. This is * the list of commands supported by the plugged-in UI * augmented by the collection of commands that the * editor itself supports. These are useful for binding * to events, such as in a keymap. * * @return the command list */
@BeanProperty(bound = false) public Action[] getActions() { return TextAction.augmentList(super.getActions(), defaultActions); }
Gets the class ID for a UI.
See Also:
Returns:the string "FormattedTextFieldUI"
/** * Gets the class ID for a UI. * * @return the string "FormattedTextFieldUI" * @see JComponent#getUIClassID */
@BeanProperty(bound = false) public String getUIClassID() { return uiClassID; }
Associates the editor with a text document. The currently registered factory is used to build a view for the document, which gets displayed by the editor after revalidation. A PropertyChange event ("document") is propagated to each listener.
Params:
  • doc – the document to display/edit
See Also:
/** * Associates the editor with a text document. * The currently registered factory is used to build a view for * the document, which gets displayed by the editor after revalidation. * A PropertyChange event ("document") is propagated to each listener. * * @param doc the document to display/edit * @see #getDocument */
@BeanProperty(expert = true, description = "the text document model") public void setDocument(Document doc) { if (documentListener != null && getDocument() != null) { getDocument().removeDocumentListener(documentListener); } super.setDocument(doc); if (documentListener == null) { documentListener = new DocumentHandler(); } doc.addDocumentListener(documentListener); } /* * See readObject and writeObject in JComponent for more * information about serialization in Swing. * * @param s Stream to write to */ private void writeObject(ObjectOutputStream s) throws IOException { s.defaultWriteObject(); if (getUIClassID().equals(uiClassID)) { byte count = JComponent.getWriteObjCounter(this); JComponent.setWriteObjCounter(this, --count); if (count == 0 && ui != null) { ui.installUI(this); } } }
Resets the Actions that come from the TextFormatter to actions.
/** * Resets the Actions that come from the TextFormatter to * <code>actions</code>. */
private void setFormatterActions(Action[] actions) { if (actions == null) { if (textFormatterActionMap != null) { textFormatterActionMap.clear(); } } else { if (textFormatterActionMap == null) { ActionMap map = getActionMap(); textFormatterActionMap = new ActionMap(); while (map != null) { ActionMap parent = map.getParent(); if (parent instanceof UIResource || parent == null) { map.setParent(textFormatterActionMap); textFormatterActionMap.setParent(parent); break; } map = parent; } } for (int counter = actions.length - 1; counter >= 0; counter--) { Object key = actions[counter].getValue(Action.NAME); if (key != null) { textFormatterActionMap.put(key, actions[counter]); } } } }
Does the setting of the value. If createFormat is true, this will also obtain a new AbstractFormatter from the current factory. The property change event will be fired if firePC is true.
/** * Does the setting of the value. If <code>createFormat</code> is true, * this will also obtain a new <code>AbstractFormatter</code> from the * current factory. The property change event will be fired if * <code>firePC</code> is true. */
private void setValue(Object value, boolean createFormat, boolean firePC) { Object oldValue = this.value; this.value = value; if (createFormat) { AbstractFormatterFactory factory = getFormatterFactory(); AbstractFormatter atf; if (factory != null) { atf = factory.getFormatter(this); } else { atf = null; } setFormatter(atf); } else { // Assumed to be valid setEditValid(true); } setEdited(false); if (firePC) { firePropertyChange("value", oldValue, value); } }
Sets the edited state of the receiver.
/** * Sets the edited state of the receiver. */
private void setEdited(boolean edited) { this.edited = edited; }
Returns true if the receiver has been edited.
/** * Returns true if the receiver has been edited. */
private boolean isEdited() { return edited; }
Returns an AbstractFormatterFactory suitable for the passed in Object type.
/** * Returns an AbstractFormatterFactory suitable for the passed in * Object type. */
private AbstractFormatterFactory getDefaultFormatterFactory(Object type) { if (type instanceof DateFormat) { return new DefaultFormatterFactory(new DateFormatter ((DateFormat)type)); } if (type instanceof NumberFormat) { return new DefaultFormatterFactory(new NumberFormatter( (NumberFormat)type)); } if (type instanceof Format) { return new DefaultFormatterFactory(new InternationalFormatter( (Format)type)); } if (type instanceof Date) { return new DefaultFormatterFactory(new DateFormatter()); } if (type instanceof Number) { AbstractFormatter displayFormatter = new NumberFormatter(); ((NumberFormatter)displayFormatter).setValueClass(type.getClass()); AbstractFormatter editFormatter = new NumberFormatter( new DecimalFormat("#.#")); ((NumberFormatter)editFormatter).setValueClass(type.getClass()); return new DefaultFormatterFactory(displayFormatter, displayFormatter,editFormatter); } return new DefaultFormatterFactory(new DefaultFormatter()); }
Instances of AbstractFormatterFactory are used by JFormattedTextField to obtain instances of AbstractFormatter which in turn are used to format values. AbstractFormatterFactory can return different AbstractFormatters based on the state of the JFormattedTextField, perhaps returning different AbstractFormatters when the JFormattedTextField has focus vs when it doesn't have focus.
Since:1.4
/** * Instances of <code>AbstractFormatterFactory</code> are used by * <code>JFormattedTextField</code> to obtain instances of * <code>AbstractFormatter</code> which in turn are used to format values. * <code>AbstractFormatterFactory</code> can return different * <code>AbstractFormatter</code>s based on the state of the * <code>JFormattedTextField</code>, perhaps returning different * <code>AbstractFormatter</code>s when the * <code>JFormattedTextField</code> has focus vs when it * doesn't have focus. * @since 1.4 */
public abstract static class AbstractFormatterFactory {
Constructor for subclasses to call.
/** * Constructor for subclasses to call. */
protected AbstractFormatterFactory() {}
Returns an AbstractFormatter that can handle formatting of the passed in JFormattedTextField.
Params:
  • tf – JFormattedTextField requesting AbstractFormatter
Returns:AbstractFormatter to handle formatting duties, a null return value implies the JFormattedTextField should behave like a normal JTextField
/** * Returns an <code>AbstractFormatter</code> that can handle formatting * of the passed in <code>JFormattedTextField</code>. * * @param tf JFormattedTextField requesting AbstractFormatter * @return AbstractFormatter to handle formatting duties, a null * return value implies the JFormattedTextField should behave * like a normal JTextField */
public abstract AbstractFormatter getFormatter(JFormattedTextField tf); }
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. AbstractFormatters can also enforce editing policies, or navigation policies, or manipulate the JFormattedTextField in any way it sees fit to enforce the desired policy.

An AbstractFormatter can only be active in one JFormattedTextField at a time. JFormattedTextField invokes install when it is ready to use it followed by uninstall when done. Subclasses that wish to install additional state should override install and message super appropriately.

Subclasses must override the conversion methods stringToValue and valueToString. Optionally they can override getActions, getNavigationFilter and getDocumentFilter to restrict the JFormattedTextField in a particular way.

Subclasses that allow the JFormattedTextField to be in a temporarily invalid state should invoke setEditValid at the appropriate times.

Since:1.4
/** * Instances of <code>AbstractFormatter</code> are used by * <code>JFormattedTextField</code> to handle the conversion both * from an Object to a String, and back from a String to an Object. * <code>AbstractFormatter</code>s can also enforce editing policies, * or navigation policies, or manipulate the * <code>JFormattedTextField</code> in any way it sees fit to * enforce the desired policy. * <p> * An <code>AbstractFormatter</code> can only be active in * one <code>JFormattedTextField</code> at a time. * <code>JFormattedTextField</code> invokes * <code>install</code> when it is ready to use it followed * by <code>uninstall</code> when done. Subclasses * that wish to install additional state should override * <code>install</code> and message super appropriately. * <p> * Subclasses must override the conversion methods * <code>stringToValue</code> and <code>valueToString</code>. Optionally * they can override <code>getActions</code>, * <code>getNavigationFilter</code> and <code>getDocumentFilter</code> * to restrict the <code>JFormattedTextField</code> in a particular * way. * <p> * Subclasses that allow the <code>JFormattedTextField</code> to be in * a temporarily invalid state should invoke <code>setEditValid</code> * at the appropriate times. * @since 1.4 */
public abstract static class AbstractFormatter implements Serializable { private JFormattedTextField ftf;
Constructor for subclasses to call.
/** * Constructor for subclasses to call. */
protected AbstractFormatter() {}
Installs the AbstractFormatter onto a particular JFormattedTextField. This will invoke valueToString to convert the current value from the JFormattedTextField to a String. This will then install the Actions from getActions, the DocumentFilter returned from getDocumentFilter and the NavigationFilter returned from getNavigationFilter onto the JFormattedTextField.

Subclasses will typically only need to override this if they wish to install additional listeners on the JFormattedTextField.

If there is a ParseException in converting the current value to a String, this will set the text to an empty String, and mark the JFormattedTextField as being in an invalid state.

While this is a public method, this is typically only useful for subclassers of JFormattedTextField. JFormattedTextField will invoke this method at the appropriate times when the value changes, or its internal state changes. You will only need to invoke this yourself if you are subclassing JFormattedTextField and installing/uninstalling AbstractFormatter at a different time than JFormattedTextField does.

Params:
  • ftf – JFormattedTextField to format for, may be null indicating uninstall from current JFormattedTextField.
/** * Installs the <code>AbstractFormatter</code> onto a particular * <code>JFormattedTextField</code>. * This will invoke <code>valueToString</code> to convert the * current value from the <code>JFormattedTextField</code> to * a String. This will then install the <code>Action</code>s from * <code>getActions</code>, the <code>DocumentFilter</code> * returned from <code>getDocumentFilter</code> and the * <code>NavigationFilter</code> returned from * <code>getNavigationFilter</code> onto the * <code>JFormattedTextField</code>. * <p> * Subclasses will typically only need to override this if they * wish to install additional listeners on the * <code>JFormattedTextField</code>. * <p> * If there is a <code>ParseException</code> in converting the * current value to a String, this will set the text to an empty * String, and mark the <code>JFormattedTextField</code> as being * in an invalid state. * <p> * While this is a public method, this is typically only useful * for subclassers of <code>JFormattedTextField</code>. * <code>JFormattedTextField</code> will invoke this method at * the appropriate times when the value changes, or its internal * state changes. You will only need to invoke this yourself if * you are subclassing <code>JFormattedTextField</code> and * installing/uninstalling <code>AbstractFormatter</code> at a * different time than <code>JFormattedTextField</code> does. * * @param ftf JFormattedTextField to format for, may be null indicating * uninstall from current JFormattedTextField. */
public void install(JFormattedTextField ftf) { if (this.ftf != null) { uninstall(); } this.ftf = ftf; if (ftf != null) { try { ftf.setText(valueToString(ftf.getValue())); } catch (ParseException pe) { ftf.setText(""); setEditValid(false); } installDocumentFilter(getDocumentFilter()); ftf.setNavigationFilter(getNavigationFilter()); ftf.setFormatterActions(getActions()); } }
Uninstalls any state the AbstractFormatter may have installed on the JFormattedTextField. This resets the DocumentFilter, NavigationFilter and additional Actions installed on the JFormattedTextField.
/** * Uninstalls any state the <code>AbstractFormatter</code> may have * installed on the <code>JFormattedTextField</code>. This resets the * <code>DocumentFilter</code>, <code>NavigationFilter</code> * and additional <code>Action</code>s installed on the * <code>JFormattedTextField</code>. */
public void uninstall() { if (this.ftf != null) { installDocumentFilter(null); this.ftf.setNavigationFilter(null); this.ftf.setFormatterActions(null); } }
Parses text returning an arbitrary Object. Some formatters may return null.
Params:
  • text – String to convert
Throws:
  • ParseException – if there is an error in the conversion
Returns:Object representation of text
/** * Parses <code>text</code> returning an arbitrary Object. Some * formatters may return null. * * @throws ParseException if there is an error in the conversion * @param text String to convert * @return Object representation of text */
public abstract Object stringToValue(String text) throws ParseException;
Returns the string value to display for value.
Params:
  • value – Value to convert
Throws:
  • ParseException – if there is an error in the conversion
Returns:String representation of value
/** * Returns the string value to display for <code>value</code>. * * @throws ParseException if there is an error in the conversion * @param value Value to convert * @return String representation of value */
public abstract String valueToString(Object value) throws ParseException;
Returns the current JFormattedTextField the AbstractFormatter is installed on.
Returns:JFormattedTextField formatting for.
/** * Returns the current <code>JFormattedTextField</code> the * <code>AbstractFormatter</code> is installed on. * * @return JFormattedTextField formatting for. */
protected JFormattedTextField getFormattedTextField() { return ftf; }
This should be invoked when the user types an invalid character. This forwards the call to the current JFormattedTextField.
/** * This should be invoked when the user types an invalid character. * This forwards the call to the current JFormattedTextField. */
protected void invalidEdit() { JFormattedTextField ftf = getFormattedTextField(); if (ftf != null) { ftf.invalidEdit(); } }
Invoke this to update the editValid property of the JFormattedTextField. If you an enforce a policy such that the JFormattedTextField is always in a valid state, you will never need to invoke this.
Params:
  • valid – Valid state of the JFormattedTextField
/** * Invoke this to update the <code>editValid</code> property of the * <code>JFormattedTextField</code>. If you an enforce a policy * such that the <code>JFormattedTextField</code> is always in a * valid state, you will never need to invoke this. * * @param valid Valid state of the JFormattedTextField */
protected void setEditValid(boolean valid) { JFormattedTextField ftf = getFormattedTextField(); if (ftf != null) { ftf.setEditValid(valid); } }
Subclass and override if you wish to provide a custom set of Actions. install will install these on the JFormattedTextField's ActionMap.
Returns:Array of Actions to install on JFormattedTextField
/** * Subclass and override if you wish to provide a custom set of * <code>Action</code>s. <code>install</code> will install these * on the <code>JFormattedTextField</code>'s <code>ActionMap</code>. * * @return Array of Actions to install on JFormattedTextField */
protected Action[] getActions() { return null; }
Subclass and override if you wish to provide a DocumentFilter to restrict what can be input. install will install the returned value onto the JFormattedTextField.
Returns:DocumentFilter to restrict edits
/** * Subclass and override if you wish to provide a * <code>DocumentFilter</code> to restrict what can be input. * <code>install</code> will install the returned value onto * the <code>JFormattedTextField</code>. * * @return DocumentFilter to restrict edits */
protected DocumentFilter getDocumentFilter() { return null; }
Subclass and override if you wish to provide a filter to restrict where the user can navigate to. install will install the returned value onto the JFormattedTextField.
Returns:NavigationFilter to restrict navigation
/** * Subclass and override if you wish to provide a filter to restrict * where the user can navigate to. * <code>install</code> will install the returned value onto * the <code>JFormattedTextField</code>. * * @return NavigationFilter to restrict navigation */
protected NavigationFilter getNavigationFilter() { return null; }
Clones the AbstractFormatter. The returned instance is not associated with a JFormattedTextField.
Returns:Copy of the AbstractFormatter
/** * Clones the <code>AbstractFormatter</code>. The returned instance * is not associated with a <code>JFormattedTextField</code>. * * @return Copy of the AbstractFormatter */
protected Object clone() throws CloneNotSupportedException { AbstractFormatter formatter = (AbstractFormatter)super.clone(); formatter.ftf = null; return formatter; }
Installs the DocumentFilter filter onto the current JFormattedTextField.
Params:
  • filter – DocumentFilter to install on the Document.
/** * Installs the <code>DocumentFilter</code> <code>filter</code> * onto the current <code>JFormattedTextField</code>. * * @param filter DocumentFilter to install on the Document. */
private void installDocumentFilter(DocumentFilter filter) { JFormattedTextField ftf = getFormattedTextField(); if (ftf != null) { Document doc = ftf.getDocument(); if (doc instanceof AbstractDocument) { ((AbstractDocument)doc).setDocumentFilter(filter); } doc.putProperty(DocumentFilter.class, null); } } }
Used to commit the edit. This extends JTextField.NotifyAction so that isEnabled is true while a JFormattedTextField has focus, and extends actionPerformed to invoke commitEdit.
/** * Used to commit the edit. This extends JTextField.NotifyAction * so that <code>isEnabled</code> is true while a JFormattedTextField * has focus, and extends <code>actionPerformed</code> to invoke * commitEdit. */
static class CommitAction extends JTextField.NotifyAction { public void actionPerformed(ActionEvent e) { JTextComponent target = getFocusedComponent(); if (target instanceof JFormattedTextField) { // Attempt to commit the value try { ((JFormattedTextField)target).commitEdit(); } catch (ParseException pe) { ((JFormattedTextField)target).invalidEdit(); // value not committed, don't notify ActionListeners return; } } // Super behavior. super.actionPerformed(e); } public boolean isEnabled() { JTextComponent target = getFocusedComponent(); if (target instanceof JFormattedTextField) { JFormattedTextField ftf = (JFormattedTextField)target; if (!ftf.isEdited()) { return false; } return true; } return super.isEnabled(); } }
CancelAction will reset the value in the JFormattedTextField when actionPerformed is invoked. It will only be enabled if the focused component is an instance of JFormattedTextField.
/** * CancelAction will reset the value in the JFormattedTextField when * <code>actionPerformed</code> is invoked. It will only be * enabled if the focused component is an instance of * JFormattedTextField. */
private static class CancelAction extends TextAction { public CancelAction() { super("reset-field-edit"); } public void actionPerformed(ActionEvent e) { JTextComponent target = getFocusedComponent(); if (target instanceof JFormattedTextField) { JFormattedTextField ftf = (JFormattedTextField)target; ftf.setValue(ftf.getValue()); } } public boolean isEnabled() { JTextComponent target = getFocusedComponent(); if (target instanceof JFormattedTextField) { JFormattedTextField ftf = (JFormattedTextField)target; if (!ftf.isEdited()) { return false; } return true; } return super.isEnabled(); } }
Sets the dirty state as the document changes.
/** * Sets the dirty state as the document changes. */
private class DocumentHandler implements DocumentListener, Serializable { public void insertUpdate(DocumentEvent e) { setEdited(true); } public void removeUpdate(DocumentEvent e) { setEdited(true); } public void changedUpdate(DocumentEvent e) {} } }