Module java.desktop
Package javax.swing.text

Class MaskFormatter

java.lang.Object
javax.swing.JFormattedTextField.AbstractFormatter
javax.swing.text.DefaultFormatter
javax.swing.text.MaskFormatter
All Implemented Interfaces:
Serializable, Cloneable
public class MaskFormatter extends DefaultFormatter
MaskFormatter is used to format and edit strings. The behavior of a MaskFormatter is controlled by way of a String mask that specifies the valid characters that can be contained at a particular location in the Document model. The following characters can be specified:
Valid characters and their descriptions
Character Description
# Any valid number, uses Character.isDigit.
' Escape character, used to escape any of the special formatting characters.
U Any character (Character.isLetter). All lowercase letters are mapped to upper case.
L Any character (Character.isLetter). All upper case letters are mapped to lower case.
A Any character or number (Character.isLetter or Character.isDigit).
? Any character (Character.isLetter).
* Anything.
H Any hex character (0-9, a-f or A-F).

Typically characters correspond to one char, but in certain languages this is not the case. The mask is on a per character basis, and will thus adjust to fit as many chars as are needed.

You can further restrict the characters that can be input by the setInvalidCharacters and setValidCharacters methods. setInvalidCharacters allows you to specify which characters are not legal. setValidCharacters allows you to specify which characters are valid. For example, the following code block is equivalent to a mask of '0xHHH' with no invalid/valid characters: 

 MaskFormatter formatter = new MaskFormatter("0x***");
 formatter.setValidCharacters("0123456789abcdefABCDEF");

When initially formatting a value if the length of the string is less than the length of the mask, two things can happen. Either the placeholder string will be used, or the placeholder character will be used. Precedence is given to the placeholder string. For example: 

   MaskFormatter formatter = new MaskFormatter("###-####");
   formatter.setPlaceholderCharacter('_');
   System.out.println(formatter.valueToString("123"));

Would result in the string '123-____'. If setPlaceholder("555-1212") was invoked '123-1212' would result. The placeholder String is only used on the initial format, on subsequent formats only the placeholder character will be used.

If a MaskFormatter is configured to only allow valid characters (setAllowsInvalid(false)) literal characters will be skipped as necessary when editing. Consider a MaskFormatter with the mask "###-####" and current value "555-1212". Using the right arrow key to navigate through the field will result in (| indicates the position of the caret): 

   |555-1212
   5|55-1212
   55|5-1212
   555-|1212
   555-1|212
The '-' is a literal (non-editable) character, and is skipped.

Similar behavior will result when editing. Consider inserting the string '123-45' and '12345' into the MaskFormatter in the previous example. Both inserts will result in the same String, '123-45__'. When MaskFormatter is processing the insert at character position 3 (the '-'), two things can happen:

  1. If the inserted character is '-', it is accepted.
  2. If the inserted character matches the mask for the next non-literal character, it is accepted at the new location.
  3. Anything else results in an invalid edit

By default MaskFormatter will not allow invalid edits, you can change this with the setAllowsInvalid method, and will commit edits on valid edits (use the setCommitsOnValidEdit to change this).

By default, MaskFormatter is in overwrite mode. That is as characters are typed a new character is not inserted, rather the character at the current location is replaced with the newly typed character. You can change this behavior by way of the method setOverwriteMode.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeans has been added to the java.beans package. Please see XMLEncoder.

Since:
1.4