20.1 The JFormattedTextField Class

JFormattedTextField extends JTextField primarily by having a value property in addition to its content (accessed by the text property). The user may manipulate the field's content, but its value doesn't (necessarily) change until the user commits the edit. If the user cancels the edit, the content reverts back to the most recent valid value.

The field's value may be of any Object type, but it is displayed and edited as a String. The field uses its formatter to translate between Object and String representations.

JFormattedTextField works by maintaining an AbstractFormatterFactory (defined as a public abstract inner class). Whenever the field receives focus, it obtains an AbstractFormatter (another public abstract inner class) from the factory to oversee editing until it loses focus. It also queries the factory for a formatter at other times, such as when it loses focus or when setValue( ) is called.

The factory does not generally create new objects (as other factory classes typically do), but usually just hands out an appropriate existing formatter instance for the field to use. The factory is used to permit different formatters to be used for viewing versus editing, not to support a variety of different types. JFormattedTextField does support a variety of types, but its constructor creates a custom factory for the type passed in. So if you create a new JFormattedTextField(new java.util.Date( )), every formatter it gets from its factory is for dates,^[1] and it rejects user input that looks like a java.net.URL or some other class.^[2]

^[1] Unless you replace the factory, of course, using setFormatterFactory( ).

^[2] Subclasses of java.lang.Number are an exception of sorts. By default, JFormattedTextField creates the same factory for any subclass of java.lang.Number. So, for example, a simple formatted text field created with a java.lang.Integer accepts floating-point values. See Section 20.2 later in this chapter.

20.1.1 Properties

Table 20-1 shows the properties defined by JFormattedTextField. It has its own unique UIClassID value but does not override the inherited accessibleContext. The document property is listed in the table only because JFormattedTextField overrides setDocument( ) to register itself as a listener for the new document and remove itself as a listener for the previous one.

Table 20-1. JFormattedTextField properties

Property	Data type	get	is	set	Default value
actionso	Action[]	·			From superclass plus CommitAction, CancelAction
documentb, o	Document	·		·	PlainDocument
editValid	boolean		·		true
focusLostBehavior	int	·		·	COMMIT_OR_REVERT
formatterb	JFormattedTextField.AbstractFormatter	·			null
formatterFactoryb	JFormattedTextField.AbstractFormatterFactory	·		·	null
UIClassIDo	String	·			"FormattedTextFieldUI"
valueb	Object	·		·	null
1.3since 1.3, bbound, ooverridden See also properties from the JTextField class (Table 19-3).

The actions property appears here because JFormattedTextField adds CommitAction and CancelAction to the array of utility actions inherited from the superclass. CommitAction extends JTextField's NotifyAction to call commitEdit( ) (to set the current edit as the value) before firing. CancelAction resets value, canceling the current edit (if any).

editValid is false if the current edit does not meet the field's formatting requirements, and true otherwise. This property is managed by the field's formatter. If the formatter permits the field to be in a temporary invalid state, it needs to update the value of this property appropriately.

formatter is the AbstractFormatter installed to oversee editing and is obtained from the formatterFactory. (Note that this is technically the case even if you instantiated the JFormattedTextField with the constructor that takes an AbstractFormatter. The constructor simply creates an unsophisticated formatterFactory that always returns the formatter you passed in. Whenever the field receives or loses focus, it queries the factory for an AbstractFormatter and receives your formatter.) The formatter is used to convert between the value (which may be any Object type) and its String representation displayed in the field.

The formatterFactory is responsible for supplying the field with a formatter whenever it asks for one. All of JFormattedTextField's constructors, except for the default constructor, use their arguments to create the formatterFactory. The default constructor leaves a null value for formatterFactory, but a factory is created the first time setValue( ) is called with a non-null argument.

value is the most recent valid content of the field, which may not be the current content of the field if an edit is in progress. Because of this, it is usually wise to call the field's commitEdit( ) method before calling getValue( ).^[3]

^[3] Especially if the focusLostBehavior property is set to PERSIST. In the other cases it is likely that the field lost focus (causing its value to be committed or reverted) when the user clicked on the button or other GUI element that resulted in this call to getValue( ). Calling commitEdit( ) is easy enough that it makes sense to do it unless you're sure it isn't required.

The focusLostBehavior property specifies how the field behaves when it loses focus. The legal values are COMMIT_OR_REVERT, REVERT, COMMIT, and PERSIST. These are described in Table 20-2. (Some formatters "push" values when an edit is in progress and ignore the value of this property.) This property doesn't help you if you want an invalid field to refuse to lose focus, but you can do that with an InputVerifier like this:

myFTF.setInputVerifier(new InputVerifier( ) {
  public boolean verify(JComponent input) {
    if (!(input instanceof JFormattedTextField))
      return true; // Give up focus.
    return ((JFormattedTextField)input).isEditValid( );
}   }); 

See Section 20.10 at the end of this chapter for details.

20.1.2 Events

JFormattedTextField does not fire any new event types. It inherits event behavior from JTextField and fires property change events when the values of the value, formatter, or formatterFactory properties are changed.

20.1.3 Constants

Table 20-2 defines the JFormattedTextField constants. These are the legal values of the focusLostBehavior property.

Table 20-2. JFormattedTextField constants

Constant	Type	Description
COMMIT	int	When the field loses focus, commitEdit( ) is called. If commitEdit( ) throws a ParseException, the field retains its invalid content.
COMMIT_OR_REVERT	int	When the field loses focus, commitEdit( ) is called. If commitEdit( ) throws a ParseException, the field reverts to its most recent valid content.
REVERT	int	When the field loses focus, it reverts to its most recent valid content.
PERSIST	int	Nothing happens when the field loses focus. (It retains its current content.)

20.1.4 Constructors

public JFormattedTextField( )

Create a new formatted text field with no formatter factory.

public JFormattedTextField(Object value)

Create a new formatted text field with the specified initial value. A formatter factory is automatically created based on the type of value. This constructor can handle java.util.Date, subclasses of java.lang.Number, or any class with a constructor that takes a single String argument.^[4] Use one of the other constructors to support other types.

^[4] This works only if the constructor can accept strings generated by the toString( ) method.

public JFormattedTextField(java.text.Format format)

Create a new formatted text field. A simple formatter factory is automatically created based on format.

public JFormattedTextField(JFormattedTextField.AbstractFormatter formatter)

Create a new formatted text field and set formatterFactory to the result of calling new DefaultFormatterFactory(formatter).

public JFormattedTextField(JFormattedTextField.AbstractFormatterFactory factory)

Create a new formatted text field with the specified formatter factory.

public JFormattedTextField(JFormattedTextField.AbstractFormatterFactory factory, Object value)

Create a new formatted text field with the specified initial value, then set formatterFactory to the specified factory.

20.1.5 Public Method

public void commitEdit( ) throws java.text.ParseException

Attempt to set the current content of the field as the value. It uses the field's formatter to convert from String to Object type.