Module java.desktop
Package javax.swing

## Class JFormattedTextField.AbstractFormatter

- java.lang.Object
- - javax.swing.JFormattedTextField.AbstractFormatter

All Implemented Interfaces:
  Serializable

Direct Known Subclasses:
  DefaultFormatter

Enclosing class:
  JFormattedTextField

    public abstract static class JFormattedTextField.AbstractFormatter
    extends Object
    implements Serializable

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. `AbstractFormatter`s 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

### Constructor Summary

Constructors
Constructor and Description
`AbstractFormatter()`

### Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
`protected Object` `clone()` Clones the `AbstractFormatter`.
`protected Action[]` `getActions()` Subclass and override if you wish to provide a custom set of `Action`s.
`protected DocumentFilter` `getDocumentFilter()` Subclass and override if you wish to provide a `DocumentFilter` to restrict what can be input.
`protected JFormattedTextField` `getFormattedTextField()` Returns the current `JFormattedTextField` the `AbstractFormatter` is installed on.
`protected NavigationFilter` `getNavigationFilter()` Subclass and override if you wish to provide a filter to restrict where the user can navigate to.
`void` `install(JFormattedTextField ftf)` Installs the `AbstractFormatter` onto a particular `JFormattedTextField`.
`protected void` `invalidEdit()` This should be invoked when the user types an invalid character.
`protected void` `setEditValid(boolean valid)` Invoke this to update the `editValid` property of the `JFormattedTextField`.
`abstract Object` `stringToValue(String text)` Parses `text` returning an arbitrary Object.
`void` `uninstall()` Uninstalls any state the `AbstractFormatter` may have installed on the `JFormattedTextField`.
`abstract String` `valueToString(Object value)` Returns the string value to display for `value`.

### Methods inherited from class java.lang.Object

`equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Constructor Detail

#### AbstractFormatter

    public AbstractFormatter()

### Method Detail

#### install

    public void install(JFormattedTextField ftf)

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 `Action`s 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.

Parameters:
  `ftf` - JFormattedTextField to format for, may be null indicating uninstall from current JFormattedTextField.

#### uninstall

    public void uninstall()

Uninstalls any state the `AbstractFormatter` may have installed on the `JFormattedTextField`. This resets the `DocumentFilter`, `NavigationFilter` and additional `Action`s installed on the `JFormattedTextField`.

#### stringToValue

    public abstract Object stringToValue(String text)
                                  throws ParseException

Parses `text` returning an arbitrary Object. Some formatters may return null.

Parameters:
  `text` - String to convert
Returns:
  Object representation of text
Throws:
  `ParseException` - if there is an error in the conversion

#### valueToString

    public abstract String valueToString(Object value)
                                  throws ParseException

Returns the string value to display for `value`.

Parameters:
  `value` - Value to convert
Returns:
  String representation of value
Throws:
  `ParseException` - if there is an error in the conversion

#### getFormattedTextField

    protected JFormattedTextField getFormattedTextField()

Returns the current `JFormattedTextField` the `AbstractFormatter` is installed on.

Returns:
  JFormattedTextField formatting for.

#### invalidEdit

    protected void invalidEdit()

This should be invoked when the user types an invalid character. This forwards the call to the current JFormattedTextField.

#### setEditValid

    protected void setEditValid(boolean valid)

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.

Parameters:
  `valid` - Valid state of the JFormattedTextField

#### getActions

    protected Action[] getActions()

Subclass and override if you wish to provide a custom set of `Action`s. `install` will install these on the `JFormattedTextField`'s `ActionMap`.

Returns:
  Array of Actions to install on JFormattedTextField

#### getDocumentFilter

    protected DocumentFilter getDocumentFilter()

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

#### getNavigationFilter

    protected NavigationFilter getNavigationFilter()

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

#### clone

    protected Object clone()
                    throws CloneNotSupportedException

Clones the `AbstractFormatter`. The returned instance is not associated with a `JFormattedTextField`.

Overrides:
  `clone` in class `Object`
Returns:
  Copy of the AbstractFormatter
Throws:
  `CloneNotSupportedException` - if the object's class does not support the `Cloneable` interface. Subclasses that override the `clone` method can also throw this exception to indicate that an instance cannot be cloned.
See Also:
  `Cloneable`