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:
| 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('_');
formatter.getDisplayValue(tf, "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|212The '-' 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:
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.
| Constructor and Description |
|---|
MaskFormatter()
Creates a MaskFormatter with no mask.
|
MaskFormatter(String mask)
Creates a
MaskFormatter with the specified mask. |
| Modifier and Type | Method and Description |
|---|---|
String |
getInvalidCharacters()
Returns the characters that are not valid for input.
|
String |
getMask()
Returns the formatting mask.
|
String |
getPlaceholder()
Returns the String to use if the value does not completely fill
in the mask.
|
char |
getPlaceholderCharacter()
Returns the character to use in place of characters that are not present
in the value, ie the user must fill them in.
|
String |
getValidCharacters()
Returns the valid characters that can be input.
|
boolean |
getValueContainsLiteralCharacters()
Returns true if
stringToValue should return literal
characters in the mask. |
void |
install(JFormattedTextField ftf)
Installs the
DefaultFormatter onto a particular
JFormattedTextField. |
void |
setInvalidCharacters(String invalidCharacters)
Allows for further restricting of the characters that can be input.
|
void |
setMask(String mask)
Sets the mask dictating the legal characters.
|
void |
setPlaceholder(String placeholder)
Sets the string to use if the value does not completely fill in
the mask.
|
void |
setPlaceholderCharacter(char placeholder)
Sets the character to use in place of characters that are not present
in the value, ie the user must fill them in.
|
void |
setValidCharacters(String validCharacters)
Allows for further restricting of the characters that can be input.
|
void |
setValueContainsLiteralCharacters(boolean containsLiteralChars)
If true, the returned value and set value will also contain the literal
characters in mask.
|
Object |
stringToValue(String value)
Parses the text, returning the appropriate Object representation of
the String
value. |
String |
valueToString(Object value)
Returns a String representation of the Object
value
based on the mask. |
clone, getAllowsInvalid, getCommitsOnValidEdit, getDocumentFilter, getNavigationFilter, getOverwriteMode, getValueClass, setAllowsInvalid, setCommitsOnValidEdit, setOverwriteMode, setValueClassgetActions, getFormattedTextField, invalidEdit, setEditValid, uninstallpublic MaskFormatter()
public MaskFormatter(String mask) throws ParseException
MaskFormatter with the specified mask.
A ParseException
will be thrown if mask is an invalid mask.ParseException - if mask does not contain valid mask characterspublic void setMask(String mask) throws ParseException
ParseException if mask is
not valid.ParseException - if mask does not contain valid mask characterspublic String getMask()
public void setValidCharacters(String validCharacters)
invalidCharacters, and in
validCharacters will be allowed to be input. Passing
in null (the default) implies the valid characters are only bound
by the mask and the invalid characters.validCharacters - If non-null, specifies legal characters.public String getValidCharacters()
public void setInvalidCharacters(String invalidCharacters)
invalidCharacters, and in
validCharacters will be allowed to be input. Passing
in null (the default) implies the valid characters are only bound
by the mask and the valid characters.invalidCharacters - If non-null, specifies illegal characters.public String getInvalidCharacters()
public void setPlaceholder(String placeholder)
placeholder - String used when formatting if the value does not
completely fill the maskpublic String getPlaceholder()
public void setPlaceholderCharacter(char placeholder)
This is only applicable if the placeholder string has not been specified, or does not completely fill in the mask.
placeholder - Character used when formatting if the value does not
completely fill the maskpublic char getPlaceholderCharacter()
public void setValueContainsLiteralCharacters(boolean containsLiteralChars)
For example, if the mask is '(###) ###-####', the
current value is '(415) 555-1212', and
valueContainsLiteralCharacters is
true stringToValue will return
'(415) 555-1212'. On the other hand, if
valueContainsLiteralCharacters is false,
stringToValue will return '4155551212'.
containsLiteralChars - Used to indicate if literal characters in
mask should be returned in stringToValuepublic boolean getValueContainsLiteralCharacters()
stringToValue should return literal
characters in the mask.public Object stringToValue(String value) throws ParseException
value. This strips the literal characters as
necessary and invokes supers stringToValue, so that if
you have specified a value class (setValueClass) an
instance of it will be created. This will throw a
ParseException if the value does not match the current
mask. Refer to setValueContainsLiteralCharacters(boolean) for details
on how literals are treated.stringToValue in class DefaultFormattervalue - String to convertParseException - if there is an error in the conversionsetValueContainsLiteralCharacters(boolean)public String valueToString(Object value) throws ParseException
value
based on the mask. Refer to
setValueContainsLiteralCharacters(boolean) for details
on how literals are treated.valueToString in class DefaultFormattervalue - Value to convertParseException - if there is an error in the conversionsetValueContainsLiteralCharacters(boolean)public void install(JFormattedTextField ftf)
DefaultFormatter onto a particular
JFormattedTextField.
This will invoke valueToString to convert the
current value from the JFormattedTextField to
a String. This will then install the Actions from
getActions, the DocumentFilter
returned from getDocumentFilter and the
NavigationFilter returned from
getNavigationFilter onto the
JFormattedTextField.
Subclasses will typically only need to override this if they
wish to install additional listeners on the
JFormattedTextField.
If there is a ParseException in converting the
current value to a String, this will set the text to an empty
String, and mark the JFormattedTextField as being
in an invalid state.
While this is a public method, this is typically only useful
for subclassers of JFormattedTextField.
JFormattedTextField will invoke this method at
the appropriate times when the value changes, or its internal
state changes.
install in class DefaultFormatterftf - JFormattedTextField to format for, may be null indicating
uninstall from current JFormattedTextField. Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2016, Oracle and/or its affiliates. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.