A Potential Pitfall with the TextFormatter Class in JavaFX

A common use case for the TextFormatter class in JavaFX is a text field that should convert any lower-case character input into an upper-case character. This can be achieved easily by defining a filter for the text formatter as described here. A straightforward implementation could look like this:

This implementation comes with one pitfall, though. When the (German) user types the character “ß” into the text field, it will be converted into “SS” because that’s how Germans roll. So the resulting string is one character longer than the input string. Why is this a problem? Well, the cursor position will be between the two “S” characters after the conversion:


When the user types in the next character, it will be inserted between the two “S” characters, not behind them. Bummer.

Luckily, the masterminds behind JavaFX give us the tools to correct this unfortunate behaviour since the change object that the filter works on allows for setting the anchor and caret position in the text field. We need to correct them by the difference between the string lengths before and after the conversion:

This puts the cursor at the end of the string no matter how many “ß” characters the user types in or pastes into the text field.

The TextFormatter Class in JavaFX: How to Restrict User Input in a Text Field

There are a lot of code examples for restricting or modifying user input into a JavaFX text field. Most examples I have seen suggest adding a change listener to the text field’s text property. Here’s how you would allow only lower-case characters in your text field using the change listener approach:

This approach comes with one drawback: you’ll have two events being triggered by two changes of the text property. The first change is caused by the direct user input, the second change is caused by the manipulation of the user input by the change listener. The user won’t notice these two events, but somewhere in your code you have another listener for the text property, that listener will receive two events, one with the “invalid” change and a second one with the “valid” change.

Another approach was suggested by Richard Bair a long time ago. His suggestion resulted in the TextFormatter  class being added to JavaFX with version 8u40. It’s a clean way to format, filter, or restrict user input. Here’s how it works:

What’s still missing is support for the backspace key to delete a character in the text field, but that’s just my silly example implementation. [Update 2016-12-28: The implementation was improved to support the deletion and selection of characters.]

This approach intercepts the user input before it’s written into the text property and thus fires only one event. Before that happens, you can examine and modify the Change  object in the UnaryOperator  defined in getFilter()  method.

In addition to filtering, a TextFormatter  object can convert a value to a string representation and vice versa. From the Javadoc:

A value converter and value  can be used to provide a 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.

Sounds pretty handy.