Module atlantafx.base
Package atlantafx.base.util

Class MaskTextFormatter

java.lang.Object
javafx.scene.control.TextFormatter<String>
atlantafx.base.util.MaskTextFormatter
public class MaskTextFormatter extends javafx.scene.control.TextFormatter<String>
A TextFormatter that can restrict the user input by applying a position-based mask. It works for the editing cases when the input string has a fixed length and each character can be restricted based on its position.

Input Mask

You can specify an input mask either as a string of the predefined characters or as a list of MaskChar, including your own implementation if you're not satisfied with the default SimpleMaskChar, e.g. if you want to override the placeholder character. The pre-defined mask characters are:
  • A - ASCII alphabetic character: [a-zA-Z].
  • N - ASCII alphanumeric character: [a-zA-Z0-9].
  • X - any character except spaces.
  • H - hexadecimal character: [a-fA-F0-9].
  • D - any digit except zero: [1-9].
  • 9 - any digit required: [0-9].
  • 8..1 - any digit from 0 to that number, respectively.
  • 0 - zero only.

Behavior

Any TextField with MaskTextFormatter applied shows a placeholder mask by default. This is basically the input mask with all mask characters replaced with the MaskChar.getPlaceholder() character.

The behavior changes if you set the TextInputControl.promptTextProperty(). In that case placeholder mask is only displayed when TextField gets focus and will be hidden after focus lost. So, the placeholder mask is always displayed when focus is set to the TextField.

You can replace the placeholder mask with any sensible default simply by changing initial TextField text to any string that is valid against the input mask.

The caret will be positioned before the first not fixed character (see MaskChar.isFixed()) starting from the beginning of the input mask.

Validation

Validation is out of the MaskTextFormatter scope. E.g. if one can use "29:59" to restrict time picker input then "27:30" would be a valid input, but obviously an invalid time. Moreover, remember that partial input like this "22:_9" is also possible. Input mask is supposed to assist and guide user input, but can barely cancel the validation completely.