javax.swing.text
Class MaskFormatter

java.lang.Object
  extended by javax.swing.JFormattedTextField.AbstractFormatter
      extended by javax.swing.text.DefaultFormatter
          extended by javax.swing.text.MaskFormatter
All Implemented Interfaces:
Serializable, Cloneable

public class MaskFormatter
extends DefaultFormatter

See Also:
Serialized Form

Constructor Summary
MaskFormatter()
           
MaskFormatter(String mask)
          Creates a MaskFormatter with the specified mask.
 
Method Summary
 String getInvalidCharacters()
          Returns a String containing the characters that are not valid for input for this MaskFormatter.
 String getMask()
          Returns the mask used in this MaskFormatter.
 String getPlaceholder()
          Returns the place holder String that is used in place of missing characters when the value doesn't completely fill in the spaces in the mask.
 char getPlaceholderCharacter()
          Returns the character used in place of missing characters when the value doesn't completely fill the mask.
 String getValidCharacters()
          Returns a String containing the characters that are valid for input for this MaskFormatter.
 boolean getValueContainsLiteralCharacters()
          Returns true if stringToValue should return the literal characters in the mask.
 void install(JFormattedTextField ftf)
          Installs this MaskFormatter on the JFormattedTextField.
 void setInvalidCharacters(String invalidCharacters)
          Sets characters that are not valid for input.
 void setMask(String mask)
          Sets the mask for this MaskFormatter.
 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 char to use if the value does not completely fill in the mask.
 void setValidCharacters(String validCharacters)
          Sets characters that are valid for input.
 void setValueContainsLiteralCharacters(boolean containsLiteralChars)
          Determines whether stringToValue will return literal characters or not.
 Object stringToValue(String value)
          Parses the text using the mask, valid characters, and invalid characters to determine the appropriate Object to return.
 String valueToString(Object value)
          Returns a String representation of the Object value based on the mask.
 
Methods inherited from class javax.swing.text.DefaultFormatter
clone, getAllowsInvalid, getCommitsOnValidEdit, getDocumentFilter, getOverwriteMode, getValueClass, setAllowsInvalid, setCommitsOnValidEdit, setOverwriteMode, setValueClass
 
Methods inherited from class javax.swing.JFormattedTextField.AbstractFormatter
getActions, getFormattedTextField, getNavigationFilter, invalidEdit, setEditValid, uninstall
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

MaskFormatter

public MaskFormatter()

MaskFormatter

public MaskFormatter(String mask)
              throws ParseException
Creates a MaskFormatter with the specified mask.

Parameters:
mask -
Throws:
ParseException
Method Detail

getMask

public String getMask()
Returns the mask used in this MaskFormatter.

Returns:
the mask used in this MaskFormatter.

getInvalidCharacters

public String getInvalidCharacters()
Returns a String containing the characters that are not valid for input for this MaskFormatter.

Returns:
a String containing the invalid characters.

setInvalidCharacters

public void setInvalidCharacters(String invalidCharacters)
Sets characters that are not valid for input. If invalidCharacters is non-null then no characters contained in it will be allowed to be input.

Parameters:
invalidCharacters - the String specifying invalid characters.

getValidCharacters

public String getValidCharacters()
Returns a String containing the characters that are valid for input for this MaskFormatter.

Returns:
a String containing the valid characters.

setValidCharacters

public void setValidCharacters(String validCharacters)
Sets characters that are valid for input. If validCharacters is non-null then no characters that are not contained in it will be allowed to be input.

Parameters:
validCharacters - the String specifying valid characters.

getPlaceholder

public String getPlaceholder()
Returns the place holder String that is used in place of missing characters when the value doesn't completely fill in the spaces in the mask.

Returns:
the place holder String.

setPlaceholder

public void setPlaceholder(String placeholder)
Sets the string to use if the value does not completely fill in the mask. If this is null, the place holder character will be used instead.

Parameters:
placeholder - the String to use if the value doesn't completely fill in the mask.

getPlaceholderCharacter

public char getPlaceholderCharacter()
Returns the character used in place of missing characters when the value doesn't completely fill the mask.

Returns:
the place holder character

setPlaceholderCharacter

public void setPlaceholderCharacter(char placeholder)
Sets the char to use if the value does not completely fill in the mask. This is only used if the place holder String has not been set or does not completely fill in the mask.

Parameters:
placeholder - the char to use if the value doesn't completely fill in the mask.

getValueContainsLiteralCharacters

public boolean getValueContainsLiteralCharacters()
Returns true if stringToValue should return the literal characters in the mask.

Returns:
true if stringToValue should return the literal characters in the mask

setValueContainsLiteralCharacters

public void setValueContainsLiteralCharacters(boolean containsLiteralChars)
Determines whether stringToValue will return literal characters or not.

Parameters:
containsLiteralChars - if true, stringToValue will return the literal characters in the mask, otherwise it will not.

setMask

public void setMask(String mask)
             throws ParseException
Sets the mask for this MaskFormatter.

Parameters:
mask - the new mask for this MaskFormatter
Throws:
ParseException - if mask is not valid.

install

public void install(JFormattedTextField ftf)
Installs this MaskFormatter on the JFormattedTextField. Invokes valueToString to convert the current value from the JFormattedTextField to a String, then installs the Actions from getActions, the DocumentFilter from getDocumentFilter, and the NavigationFilter from getNavigationFilter. If valueToString throws a ParseException, this method sets the text to an empty String and marks the JFormattedTextField as invalid.

Overrides:
install in class DefaultFormatter
Parameters:
ftf - the JFormattedTextField in which this formatter is installed

stringToValue

public Object stringToValue(String value)
                     throws ParseException
Parses the text using the mask, valid characters, and invalid characters to determine the appropriate Object to return. This strips the literal characters if necessary and invokes super.stringToValue. If the paramter is invalid for the current mask and valid/invalid character sets this method will throw a ParseException.

Overrides:
stringToValue in class DefaultFormatter
Parameters:
value - the String to parse
Returns:
the value for the string
Throws:
ParseException - if value doesn't match the mask and valid/invalid character sets

valueToString

public String valueToString(Object value)
                     throws ParseException
Returns a String representation of the Object value based on the mask.

Overrides:
valueToString in class DefaultFormatter
Parameters:
value - the value to convert
Returns:
the string representation of the value
Throws:
ParseException - if value is invalid for this mask and valid/invalid character sets