Module javafx.controls
Package javafx.scene.control

# Class TextFormatter<V>

java.lang.Object
javafx.scene.control.TextFormatter<V>

Type Parameters:
  `V` - The type of the value

public class TextFormatter<V> extends Object
A Formatter describes a format of a `TextInputControl` text by using two distinct mechanisms:

- A filter (`getFilter()`) that can intercept and modify user input. This helps to keep the text in the desired format. A default text supplier can be used to provide the initial text.
- A value converter (`getValueConverter()`) and value (`valueProperty()`) can be used to provide special format that represents a value of type `V`. If the control is editable and the text is changed by the user, the value is then updated to correspond to the text.

It's possible to have a formatter with just a filter or a value converter. If a value converter is not provided, setting a value will result in an `IllegalStateException` and the value is always `null`.

Since `Formatter` contains a value that represents the state of the `TextInputControl` to which it is currently assigned, a single `Formatter` instance can be used only in one `TextInputControl` at a time.

Since:
  JavaFX 8u40

- ## Property Summary

  Properties
  Type
  Property
  Description
  `final ObjectProperty<V>`
  `value`
  The current value for this formatter.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static final class`
  `TextFormatter.Change`
  Contains the state representing a change in the content or selection for a TextInputControl.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final StringConverter<String>`
  `IDENTITY_STRING_CONVERTER`
  This string converter converts the text to the same String value.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `TextFormatter(UnaryOperator<TextFormatter.Change> filter)`
  Creates a new Formatter with the provided filter.
  `TextFormatter(StringConverter<V> valueConverter)`
  Creates a new Formatter with the provided value converter.
  `TextFormatter(StringConverter<V> valueConverter, V defaultValue)`
  Creates a new Formatter with the provided value converter and default value.
  `TextFormatter(StringConverter<V> valueConverter, V defaultValue, UnaryOperator<TextFormatter.Change> filter)`
  Creates a new Formatter with the provided filter, value converter and default value.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `final UnaryOperator<TextFormatter.Change>`
  `getFilter()`
  Filter allows user to intercept and modify any change done to the text content.
  `final V`
  `getValue()`
  Gets the value of the `value` property.
  `final StringConverter<V>`
  `getValueConverter()`
  The converter between the values and text.
  `final void`
  `setValue(V value)`
  Sets the value of the `value` property.
  `final ObjectProperty<V>`
  `valueProperty()`
  The current value for this formatter.

  ### Methods declared in class java.lang.Object

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

- ## Property Details

  - ### value

    public final ObjectProperty<V> valueProperty
    The current value for this formatter. When the formatter is set on a `TextInputControl` and has a `valueConverter`, the value is set by the control, when the text is commited.
    See Also:
      - `getValue()`
      - `setValue(V)`
      - `valueProperty()`

- ## Field Details

  - ### IDENTITY_STRING_CONVERTER

    public static final StringConverter<String> IDENTITY_STRING_CONVERTER
    This string converter converts the text to the same String value. This might be useful for cases where you want to manipulate with the text through the value or you need to provide a default text value.

- ## Constructor Details

  - ### TextFormatter

    public TextFormatter(UnaryOperator<TextFormatter.Change> filter)
    Creates a new Formatter with the provided filter.
    Parameters:
      `filter` - The filter to use in this formatter or null

  - ### TextFormatter

    public TextFormatter(StringConverter<V> valueConverter, V defaultValue, UnaryOperator<TextFormatter.Change> filter)
    Creates a new Formatter with the provided filter, value converter and default value.
    Parameters:
      `valueConverter` - The value converter to use in this formatter or null.
      `defaultValue` - the default value.
      `filter` - The filter to use in this formatter or null

  - ### TextFormatter

    public TextFormatter(StringConverter<V> valueConverter, V defaultValue)
    Creates a new Formatter with the provided value converter and default value.
    Parameters:
      `valueConverter` - The value converter to use in this formatter. This must not be null.
      `defaultValue` - the default value

  - ### TextFormatter

    public TextFormatter(StringConverter<V> valueConverter)
    Creates a new Formatter with the provided value converter. The default value will be null.
    Parameters:
      `valueConverter` - The value converter to use in this formatter. This must not be null.

- ## Method Details

  - ### getValueConverter

    public final StringConverter<V> getValueConverter()
    The converter between the values and text. It maintains a "binding" between the `TextInputControl.textProperty()` } and `valueProperty()` }. The value is updated when the control loses it's focus or it is commited (TextField only). Setting the value will update the text of the control, usin the provided converter. If it's impossible to convert text to value, an exception should be thrown.
    Returns:
      StringConverter for values or null if none provided
    See Also:
      - `TextInputControl.commitValue()`
      - `TextInputControl.cancelEdit()`

  - ### getFilter

    public final UnaryOperator<TextFormatter.Change> getFilter()
    Filter allows user to intercept and modify any change done to the text content.

    The filter itself is an `UnaryOperator` that accepts `TextFormatter.Change` object. It should return a `TextFormatter.Change` object that contains the actual (filtered) change. Returning null rejects the change.

    Returns:
      the filter for this formatter or null if there is none

  - ### valueProperty

    public final ObjectProperty<V> valueProperty()
    The current value for this formatter. When the formatter is set on a `TextInputControl` and has a `valueConverter`, the value is set by the control, when the text is commited.
    Returns:
      the `value` property
    See Also:
      - `getValue()`
      - `setValue(V)`

  - ### setValue

    public final void setValue(V value)
    Sets the value of the `value` property.
    Property description:
      The current value for this formatter. When the formatter is set on a `TextInputControl` and has a `valueConverter`, the value is set by the control, when the text is commited.
    Parameters:
      `value` - the value for the `value` property
    See Also:
      - `getValue()`
      - `valueProperty()`

  - ### getValue

    public final V getValue()
    Gets the value of the `value` property.
    Property description:
      The current value for this formatter. When the formatter is set on a `TextInputControl` and has a `valueConverter`, the value is set by the control, when the text is commited.
    Returns:
      the value of the `value` property
    See Also:
      - `setValue(V)`
      - `valueProperty()`