JFormattedTextField.AbstractFormatter (Java SE 17 & JDK 17)
Description: declaration: module: java.desktop, package: javax.swing, class: JFormattedTextField, class: AbstractFormatter
Keywords: javax.swing.JFormattedTextField.AbstractFormatter class

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
  Modifier
  Constructor
  Description
  `protected`
  `AbstractFormatter()`
  Constructor for subclasses to call.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `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 declared in class java.lang.Object

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

- ## Constructor Details

  - ### AbstractFormatter

    protected AbstractFormatter()
    Constructor for subclasses to call.

- ## Method Details

  - ### 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`.
    Implementation Requirements:
      The default implementation returns `null`.
    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`.
    Implementation Requirements:
      The default implementation returns `null`.
    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`