/*
* @(#)MaskFormatter.java 1.12 03/12/19
*
* Copyright 2004 Sun Microsystems, Inc. All rights reserved.
* SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
*/
package javax.swing.text;
import java.io.*;
import java.text.*;
import java.util.*;
import javax.swing.*;
import javax.swing.text.*;
/**
* 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|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:
*
* 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 JavaBeansTM
* has been added to the java.beans
package.
* Please see {@link java.beans.XMLEncoder}.
*
* @version 1.12 12/19/03
* @since 1.4
*/
public class MaskFormatter extends DefaultFormatter {
// Potential values in mask.
private static final char DIGIT_KEY = '#';
private static final char LITERAL_KEY = '\'';
private static final char UPPERCASE_KEY = 'U';
private static final char LOWERCASE_KEY = 'L';
private static final char ALPHA_NUMERIC_KEY = 'A';
private static final char CHARACTER_KEY = '?';
private static final char ANYTHING_KEY = '*';
private static final char HEX_KEY = 'H';
private static final MaskCharacter[] EmptyMaskChars = new MaskCharacter[0];
/** The user specified mask. */
private String mask;
private transient MaskCharacter[] maskChars;
/** List of valid characters. */
private String validCharacters;
/** List of invalid characters. */
private String invalidCharacters;
/** String used for the passed in value if it does not completely
* fill the mask. */
private String placeholderString;
/** String used to represent characters not present. */
private char placeholder;
/** Indicates if the value contains the literal characters. */
private boolean containsLiteralChars;
/**
* Creates a MaskFormatter with no mask.
*/
public MaskFormatter() {
setAllowsInvalid(false);
containsLiteralChars = true;
maskChars = EmptyMaskChars;
placeholder = ' ';
}
/**
* Creates a MaskFormatter
with the specified mask.
* A ParseException
* will be thrown if mask
is an invalid mask.
*
* @throws ParseException if mask does not contain valid mask characters
*/
public MaskFormatter(String mask) throws ParseException {
this();
setMask(mask);
}
/**
* Sets the mask dictating the legal characters.
* This will throw a ParseException
if mask
is
* not valid.
*
* @throws ParseException if mask does not contain valid mask characters
*/
public void setMask(String mask) throws ParseException {
this.mask = mask;
updateInternalMask();
}
/**
* Returns the formatting mask.
*
* @return Mask dictating legal character values.
*/
public String getMask() {
return mask;
}
/**
* Allows for further restricting of the characters that can be input.
* Only characters specified in the mask, not in the
* 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.
*
* @param validCharacters If non-null, specifies legal characters.
*/
public void setValidCharacters(String validCharacters) {
this.validCharacters = validCharacters;
}
/**
* Returns the valid characters that can be input.
*
* @return Legal characters
*/
public String getValidCharacters() {
return validCharacters;
}
/**
* Allows for further restricting of the characters that can be input.
* Only characters specified in the mask, not in the
* 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.
*
* @param invalidCharacters If non-null, specifies illegal characters.
*/
public void setInvalidCharacters(String invalidCharacters) {
this.invalidCharacters = invalidCharacters;
}
/**
* Returns the characters that are not valid for input.
*
* @return illegal characters.
*/
public String getInvalidCharacters() {
return invalidCharacters;
}
/**
* Sets the string to use if the value does not completely fill in
* the mask. A null value implies the placeholder char should be used.
*
* @param placeholder String used when formatting if the value does not
* completely fill the mask
*/
public void setPlaceholder(String placeholder) {
this.placeholderString = placeholder;
}
/**
* Returns the String to use if the value does not completely fill
* in the mask.
*
* @return String used when formatting if the value does not
* completely fill the mask
*/
public String getPlaceholder() {
return placeholderString;
}
/**
* Sets the character to use in place of characters that are not present
* in the value, ie the user must fill them in. The default value is
* a space.
*
* This is only applicable if the placeholder string has not been * specified, or does not completely fill in the mask. * * @param placeholder Character used when formatting if the value does not * completely fill the mask */ public void setPlaceholderCharacter(char placeholder) { this.placeholder = placeholder; } /** * Returns the character to use in place of characters that are not present * in the value, ie the user must fill them in. * * @return Character used when formatting if the value does not * completely fill the mask */ public char getPlaceholderCharacter() { return placeholder; } /** * If true, the returned value and set value will also contain the literal * characters in mask. *
* 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'
.
*
* @param containsLiteralChars Used to indicate if literal characters in
* mask should be returned in stringToValue
*/
public void setValueContainsLiteralCharacters(
boolean containsLiteralChars) {
this.containsLiteralChars = containsLiteralChars;
}
/**
* Returns true if stringToValue
should return literal
* characters in the mask.
*
* @return True if literal characters in mask should be returned in
* stringToValue
*/
public boolean getValueContainsLiteralCharacters() {
return containsLiteralChars;
}
/**
* Parses the text, returning the appropriate Object representation of
* the String 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 {@link #setValueContainsLiteralCharacters} for details
* on how literals are treated.
*
* @throws ParseException if there is an error in the conversion
* @param value String to convert
* @see #setValueContainsLiteralCharacters
* @return Object representation of text
*/
public Object stringToValue(String value) throws ParseException {
return stringToValue(value, true);
}
/**
* Returns a String representation of the Object value
* based on the mask. Refer to
* {@link #setValueContainsLiteralCharacters} for details
* on how literals are treated.
*
* @throws ParseException if there is an error in the conversion
* @param value Value to convert
* @see #setValueContainsLiteralCharacters
* @return String representation of value
*/
public String valueToString(Object value) throws ParseException {
String sValue = (value == null) ? "" : value.toString();
StringBuffer result = new StringBuffer();
String placeholder = getPlaceholder();
int[] valueCounter = { 0 };
append(result, sValue, valueCounter, placeholder, maskChars);
return result.toString();
}
/**
* Installs the 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 Action
s 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.
*
* @param ftf JFormattedTextField to format for, may be null indicating
* uninstall from current JFormattedTextField.
*/
public void install(JFormattedTextField ftf) {
super.install(ftf);
// valueToString doesn't throw, but stringToValue does, need to
// update the editValid state appropriately
if (ftf != null) {
Object value = ftf.getValue();
try {
stringToValue(valueToString(value));
} catch (ParseException pe) {
setEditValid(false);
}
}
}
/**
* Actual stringToValue
implementation.
* If completeMatch
is true, the value must exactly match
* the mask, on the other hand if completeMatch
is false
* the string must match the mask or the placeholder string.
*/
private Object stringToValue(String value, boolean completeMatch) throws
ParseException {
int errorOffset = -1;
if ((errorOffset = getInvalidOffset(value, completeMatch)) == -1) {
if (!getValueContainsLiteralCharacters()) {
value = stripLiteralChars(value);
}
return super.stringToValue(value);
}
throw new ParseException("stringToValue passed invalid value",
errorOffset);
}
/**
* Returns -1 if the passed in string is valid, otherwise the index of
* the first bogus character is returned.
*/
private int getInvalidOffset(String string, boolean completeMatch) {
int iLength = string.length();
if (iLength != getMaxLength()) {
// trivially false
return iLength;
}
for (int counter = 0, max = string.length(); counter < max; counter++){
char aChar = string.charAt(counter);
if (!isValidCharacter(counter, aChar) &&
(completeMatch || !isPlaceholder(counter, aChar))) {
return counter;
}
}
return -1;
}
/**
* Invokes append
on the mask characters in
* mask
.
*/
private void append(StringBuffer result, String value, int[] index,
String placeholder, MaskCharacter[] mask)
throws ParseException {
for (int counter = 0, maxCounter = mask.length;
counter < maxCounter; counter++) {
mask[counter].append(result, value, index, placeholder);
}
}
/**
* Updates the internal representation of the mask.
*/
private void updateInternalMask() throws ParseException {
String mask = getMask();
ArrayList fixed = new ArrayList();
ArrayList temp = fixed;
if (mask != null) {
for (int counter = 0, maxCounter = mask.length();
counter < maxCounter; counter++) {
char maskChar = mask.charAt(counter);
switch (maskChar) {
case DIGIT_KEY:
temp.add(new DigitMaskCharacter());
break;
case LITERAL_KEY:
if (++counter < maxCounter) {
maskChar = mask.charAt(counter);
temp.add(new LiteralCharacter(maskChar));
}
// else: Could actually throw if else
break;
case UPPERCASE_KEY:
temp.add(new UpperCaseCharacter());
break;
case LOWERCASE_KEY:
temp.add(new LowerCaseCharacter());
break;
case ALPHA_NUMERIC_KEY:
temp.add(new AlphaNumericCharacter());
break;
case CHARACTER_KEY:
temp.add(new CharCharacter());
break;
case ANYTHING_KEY:
temp.add(new MaskCharacter());
break;
case HEX_KEY:
temp.add(new HexCharacter());
break;
default:
temp.add(new LiteralCharacter(maskChar));
break;
}
}
}
if (fixed.size() == 0) {
maskChars = EmptyMaskChars;
}
else {
maskChars = new MaskCharacter[fixed.size()];
fixed.toArray(maskChars);
}
}
/**
* Returns the MaskCharacter at the specified location.
*/
private MaskCharacter getMaskCharacter(int index) {
if (index >= maskChars.length) {
return null;
}
return maskChars[index];
}
/**
* Returns true if the placeholder character matches aChar.
*/
private boolean isPlaceholder(int index, char aChar) {
return (getPlaceholderCharacter() == aChar);
}
/**
* Returns true if the passed in character matches the mask at the
* specified location.
*/
private boolean isValidCharacter(int index, char aChar) {
return getMaskCharacter(index).isValidCharacter(aChar);
}
/**
* Returns true if the character at the specified location is a literal,
* that is it can not be edited.
*/
private boolean isLiteral(int index) {
return getMaskCharacter(index).isLiteral();
}
/**
* Returns the maximum length the text can be.
*/
private int getMaxLength() {
return maskChars.length;
}
/**
* Returns the literal character at the specified location.
*/
private char getLiteral(int index) {
return getMaskCharacter(index).getChar((char)0);
}
/**
* Returns the character to insert at the specified location based on
* the passed in character. This provides a way to map certain sets
* of characters to alternative values (lowercase to
* uppercase...).
*/
private char getCharacter(int index, char aChar) {
return getMaskCharacter(index).getChar(aChar);
}
/**
* Removes the literal characters from the passed in string.
*/
private String stripLiteralChars(String string) {
StringBuffer sb = null;
int last = 0;
for (int counter = 0, max = string.length(); counter < max; counter++){
if (isLiteral(counter)) {
if (sb == null) {
sb = new StringBuffer();
if (counter > 0) {
sb.append(string.substring(0, counter));
}
last = counter + 1;
}
else if (last != counter) {
sb.append(string.substring(last, counter));
}
last = counter + 1;
}
}
if (sb == null) {
// Assume the mask isn't all literals.
return string;
}
else if (last != string.length()) {
if (sb == null) {
return string.substring(last);
}
sb.append(string.substring(last));
}
return sb.toString();
}
/**
* Subclassed to update the internal representation of the mask after
* the default read operation has completed.
*/
private void readObject(ObjectInputStream s)
throws IOException, ClassNotFoundException {
s.defaultReadObject();
try {
updateInternalMask();
} catch (ParseException pe) {
// assert();
}
}
/**
* Returns true if the MaskFormatter allows invalid, or
* the offset is less than the max length and the character at
* offset
is a literal.
*/
boolean isNavigatable(int offset) {
if (!getAllowsInvalid()) {
return (offset < getMaxLength() && !isLiteral(offset));
}
return true;
}
/*
* Returns true if the operation described by rh
will
* result in a legal edit. This may set the value
* field of rh
.
*
* This is overriden to return true for a partial match. */ boolean isValidEdit(ReplaceHolder rh) { if (!getAllowsInvalid()) { String newString = getReplaceString(rh.offset, rh.length, rh.text); try { rh.value = stringToValue(newString, false); return true; } catch (ParseException pe) { return false; } } return true; } /** * This method does the following (assuming !getAllowsInvalid()): * iterate over the max of the deleted region or the text length, for * each character: *
aChar
is a valid reprensentation of
* the receiver. The default implementation returns true if the
* receiver represents a literal character and getChar
* == aChar. Otherwise, this will return true is aChar
* is contained in the valid characters and not contained
* in the invalid characters.
*/
public boolean isValidCharacter(char aChar) {
if (isLiteral()) {
return (getChar(aChar) == aChar);
}
aChar = getChar(aChar);
String filter = getValidCharacters();
if (filter != null && filter.indexOf(aChar) == -1) {
return false;
}
filter = getInvalidCharacters();
if (filter != null && filter.indexOf(aChar) != -1) {
return false;
}
return true;
}
/**
* Returns the character to insert for aChar
. The
* default implementation returns aChar
. Subclasses
* that wish to do some sort of mapping, perhaps lower case to upper
* case should override this and do the necessary mapping.
*/
public char getChar(char aChar) {
return aChar;
}
/**
* Appends the necessary character in formatting
at
* index
to buff
.
*/
public void append(StringBuffer buff, String formatting, int[] index,
String placeholder)
throws ParseException {
boolean inString = index[0] < formatting.length();
char aChar = inString ? formatting.charAt(index[0]) : 0;
if (isLiteral()) {
buff.append(getChar(aChar));
if (getValueContainsLiteralCharacters()) {
if (inString && aChar != getChar(aChar)) {
throw new ParseException("Invalid character: " +
aChar, index[0]);
}
index[0] = index[0] + 1;
}
}
else if (index[0] >= formatting.length()) {
if (placeholder != null && index[0] < placeholder.length()) {
buff.append(placeholder.charAt(index[0]));
}
else {
buff.append(getPlaceholderCharacter());
}
index[0] = index[0] + 1;
}
else if (isValidCharacter(aChar)) {
buff.append(getChar(aChar));
index[0] = index[0] + 1;
}
else {
throw new ParseException("Invalid character: " + aChar,
index[0]);
}
}
}
/**
* Used to represent a fixed character in the mask.
*/
private class LiteralCharacter extends MaskCharacter {
private char fixedChar;
public LiteralCharacter(char fixedChar) {
this.fixedChar = fixedChar;
}
public boolean isLiteral() {
return true;
}
public char getChar(char aChar) {
return fixedChar;
}
}
/**
* Represents a number, uses Character.isDigit
.
*/
private class DigitMaskCharacter extends MaskCharacter {
public boolean isValidCharacter(char aChar) {
return (Character.isDigit(aChar) &&
super.isValidCharacter(aChar));
}
}
/**
* Represents a character, lower case letters are mapped to upper case
* using Character.toUpperCase
.
*/
private class UpperCaseCharacter extends MaskCharacter {
public boolean isValidCharacter(char aChar) {
return (Character.isLetter(aChar) &&
super.isValidCharacter(aChar));
}
public char getChar(char aChar) {
return Character.toUpperCase(aChar);
}
}
/**
* Represents a character, upper case letters are mapped to lower case
* using Character.toLowerCase
.
*/
private class LowerCaseCharacter extends MaskCharacter {
public boolean isValidCharacter(char aChar) {
return (Character.isLetter(aChar) &&
super.isValidCharacter(aChar));
}
public char getChar(char aChar) {
return Character.toLowerCase(aChar);
}
}
/**
* Represents either a character or digit, uses
* Character.isLetterOrDigit
.
*/
private class AlphaNumericCharacter extends MaskCharacter {
public boolean isValidCharacter(char aChar) {
return (Character.isLetterOrDigit(aChar) &&
super.isValidCharacter(aChar));
}
}
/**
* Represents a letter, uses Character.isLetter
.
*/
private class CharCharacter extends MaskCharacter {
public boolean isValidCharacter(char aChar) {
return (Character.isLetter(aChar) &&
super.isValidCharacter(aChar));
}
}
/**
* Represents a hex character, 0-9a-fA-F. a-f is mapped to A-F
*/
private class HexCharacter extends MaskCharacter {
public boolean isValidCharacter(char aChar) {
return ((aChar == '0' || aChar == '1' ||
aChar == '2' || aChar == '3' ||
aChar == '4' || aChar == '5' ||
aChar == '6' || aChar == '7' ||
aChar == '8' || aChar == '9' ||
aChar == 'a' || aChar == 'A' ||
aChar == 'b' || aChar == 'B' ||
aChar == 'c' || aChar == 'C' ||
aChar == 'd' || aChar == 'D' ||
aChar == 'e' || aChar == 'E' ||
aChar == 'f' || aChar == 'F') &&
super.isValidCharacter(aChar));
}
public char getChar(char aChar) {
if (Character.isDigit(aChar)) {
return aChar;
}
return Character.toUpperCase(aChar);
}
}
}