Class 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 intial 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 filter or value converter. If value converter is not provided however, setting a value will result in an IllegalStateException and the value is always null.

    Since Formatter contains a value which 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 Detail

      • 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)
    • Field Detail

      • 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 Detail

      • 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 Detail

      • 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.
        See Also:
        getValue(), setValue(V)
      • setValue

        public final void setValue​(V value)
        Sets the value of the property value.
        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.
      • getValue

        public final V getValue()
        Gets the value of the property value.
        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.