20.2 Handling Numerics

To a certain extent, JFormattedTextField treats the types Float, Double, Integer, Long, Short, and Byte (all subclasses of java.lang.Number) as interchangeable. This can sometimes be surprising. For example, with this field:

JFormattedTextField ftf = new JFormattedTextField(new Integer(4));

you might expect to be able to retrieve the value like this:

int val = ((Integer)ftf.getValue( )).intValue( ); // Incorrect

This code is likely to throw a ClassCastException because ftf.getValue( ) might return one of the other numeric types if the user has edited the field.^[5]

^[5] By default, it tends to return either a Long or a Double, but it's not so simple even when knowing that. A field showing 5.008 may return a Double value, but if the user shortens it to 5.00 with the Backspace key, it may now return a Long value (despite the presence of the decimal point).

A safer way to retrieve the value is:

int val = ((Number)ftf.getValue( )).intValue( ); // Correct

Casting to Number like this always works because the methods floatValue( ), doubleValue( ), integerValue( ), longValue( ), shortValue( ), and byteValue( ) are all defined in the java.lang.Number class.

If for some reason you want to force getValue( ) to return a specific numeric type, this can be done by instantiating a NumberFormat, calling its setValueClass( ) method, and passing the NumberFormat into the JFormattedTextField constructor.

20.2.1 The JFormattedTextField.AbstractFormatter Class

AbstractFormatter is an abstract inner class of JFormattedTextField that defines the basic API for formatters. Usually, there is no reason to extend AbstractFormatter directly since DefaultFormatter (discussed in the next section) provides a more complete starting point.

20.2.1.1 Public methods

public abstract Object stringToValue(String text) throws java.text.ParseException

public abstract String valueToString(Object value) throws java.text.ParseException

These two methods are the heart of the formatter API. They are used by the field to convert between the field's value (which may be any Object type) and the String representation displayed in the field. If conversion is impossible, a java.text.ParseException is thrown. In particular, the stringToValue( ) method throws a ParseException if its argument is not valid. Returning without throwing a ParseException indicates that the input was deemed valid.

public void install(JFormattedTextField ftf)

Immediately after a JFormattedTextField obtains a formatter from its formatterFactory, it calls this method so the formatter can initialize itself for a new field. AbstractFormatter's implementation of this method stores ftf for later use (by the getFormattedTextField( ) method, for example) and sets the text content of the field. It also installs any values returned by getActions( ), getDocumentFilter( ), and getNavigationFilter( ) on ftf. (AbstractFormatter returns null in all three of those methods but is prepared for subclasses not to.) Subclasses may override this method if they wish to add listeners to the field or its Document or to modify the field's selection or caret position.

public void uninstall( )

JFormattedTextField calls this method on its formatter just before it obtains a new formatter from its formatterFactory to undo anything done in the install( ) method. Subclasses that override install( ) may need to override uninstall( ) also.

20.2.1.2 Protected methods

protected JFormattedTextField getFormattedTextField( )

Return the JFormattedTextField on which this formatter is installed.

protected Action[] getActions( )

AbstractFormatter's implementation returns null. Subclasses may override this method to add one or more Actions to the field's ActionMap. An Action is invoked only if its name matches something in the field's InputMap. Formatters may be especially interested in "increment", "decrement", and "reset-field-edit", which most L&Fs assign to the up arrow, down arrow, and Escape keys, respectively. See Appendix B for a complete list.

protected DocumentFilter getDocumentFilter( )

AbstractFormatter's implementation returns null. Subclasses may override this method to set a DocumentFilter on the field. (See Section 22.6.)

protected NavigationFilter getNavigationFilter( )

AbstractFormatter's implementation returns null. Subclasses may override this method to set a NavigationFilter on the field. (See Section 22.7.)

protected void invalidEdit( )

Call this method to provide error feedback (for example, when the user attempts to enter an invalid character into the field). AbstractFormatter's implementation simply calls the field's invalidEdit( ) method.

protected void setEditValid(boolean valid)

This utility method simply passes its argument to the field's setEditValid( ) method. The formatter is responsible for keeping the field's editValid property up to date.

protected Object clone( ) throws CloneNotSupportedException

Because JFormattedTextFields cannot share a formatter, the clone is in an unattached state and may be installed on some other JFormattedTextField.