MaskFormatter JDK 1.6)

Description

public class MaskFormatter

MaskFormatter is used to format and edit strings.

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):

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:

If the inserted character is '-', it is accepted.
If the inserted character matches the mask for the next non-literal character, it is accepted at the new location.
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^TM has been added to the java.beans package. Please see XMLEncoder.

See also:

Methods

Hide/Show inherited methods

pack-private boolean canReplace (ReplaceHolder rh) [Overrides DefaultFormatter]

This method does the following (assuming !getAllowsInvalid()): iterate over the max of the deleted region or the text length, for each character: If it is valid (matches the mask at the particular position, or matches the literal character at the position), allow it Else if the position identifies a literal character, add it.

public Object clone () throws CloneNotSupportedException [Inherited From DefaultFormatter]

Creates a copy of the DefaultFormatter.

pack-private void commitEdit () throws ParseException [Inherited From DefaultFormatter]

Invokes commitEdit on the JFormattedTextField.

protected Action getActions () [Inherited From JFormattedTextField.AbstractFormatter]

Subclass and override if you wish to provide a custom set of Actions.

Subclass and override if you wish to provide a custom set of
Actions. install will install these
on the JFormattedTextField's ActionMap.
Returns: Array of Actions to install on JFormattedTextField

public boolean getAllowsInvalid () [Inherited From DefaultFormatter]

Returns whether or not the value being edited is allowed to be invalid for a length of time.

public boolean getCommitsOnValidEdit () [Inherited From DefaultFormatter]

Returns when edits are published back to the JFormattedTextField.

Returns when edits are published back to the
JFormattedTextField.
Returns: true if edits are commited after evey valid edit

protected DocumentFilter getDocumentFilter () [Inherited From DefaultFormatter]

Returns the DocumentFilter used to restrict the characters that can be input into the JFormattedTextField.

Returns the DocumentFilter used to restrict the characters
that can be input into the JFormattedTextField.
Returns: DocumentFilter to restrict edits

protected JFormattedTextField getFormattedTextField () [Inherited From JFormattedTextField.AbstractFormatter]

Returns the current JFormattedTextField the AbstractFormatter is installed on.

Returns the current JFormattedTextField the
AbstractFormatter is installed on.
Returns: JFormattedTextField formatting for.

pack-private int getInitialVisualPosition () [Inherited From DefaultFormatter]

Returns the initial location to position the cursor at.

Returns the initial location to position the cursor at. This forwards
the call to getNextNavigatableChar.

public String getInvalidCharacters ()

Returns the characters that are not valid for input.

public String getMask ()

Returns the formatting mask.

protected NavigationFilter getNavigationFilter () [Inherited From DefaultFormatter]

Returns the NavigationFilter used to restrict where the cursor can be placed.

Returns the NavigationFilter used to restrict where the
cursor can be placed.
Returns: NavigationFilter to restrict navigation

pack-private int getNextCursorPosition (int offset, int direction) [Inherited From DefaultFormatter]

Returns the next cursor position from offset by incrementing direction.

Returns the next cursor position from offset by incrementing
direction. This uses
getNextNavigatableChar
as well as constraining the location to the max position.

pack-private int getNextVisualPositionFrom (JTextComponent text, int pos, Bias bias, int direction, Bias biasRet) throws BadLocationException [Inherited From DefaultFormatter]

Finds the next navigatable character.

public boolean getOverwriteMode () [Inherited From DefaultFormatter]

Returns the behavior when inserting characters.

public String getPlaceholder ()

Returns the String to use if the value does not completely fill in the mask.

public 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.

pack-private ReplaceHolder getReplaceHolder (FilterBypass fb, int offset, int length, String text, AttributeSet attrs) [Inherited From DefaultFormatter]

Returns the ReplaceHolder to track the replace of the specified text.

pack-private String getReplaceString (int offset, int deleteLength, String replaceString) [Inherited From DefaultFormatter]

A convenience methods to return the result of deleting deleteLength characters at offset and inserting replaceString at offset in the current text field.

public String getValidCharacters ()

Returns the valid characters that can be input.

public Class<Object> getValueClass () [Inherited From DefaultFormatter]

Returns that class that is used to create new Objects.

public boolean getValueContainsLiteralCharacters ()

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

Returns true if stringToValue should return literal
characters in the mask.
Returns: True if literal characters in mask should be returned in stringToValue

public void install (JFormattedTextField ftf) [Overrides DefaultFormatter]

Installs the DefaultFormatter onto a particular JFormattedTextField.

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 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.
Parameters:
- ftf - JFormattedTextField to format for, may be null indicating uninstall from current JFormattedTextField.

protected void invalidEdit () [Inherited From JFormattedTextField.AbstractFormatter]

This should be invoked when the user types an invalid character.

pack-private boolean isLegalInsertText (String text) [Inherited From DefaultFormatter]

Returns true if the text in text can be inserted.

Returns true if the text in text can be inserted. This
does not mean the text will ultimately be inserted, it is used if
text can trivially reject certain characters.

pack-private boolean isNavigatable (int offset) [Overrides DefaultFormatter]

Returns true if the MaskFormatter allows invalid, or the offset is less than the max length and the character at offset is a literal.

pack-private boolean isValidEdit (ReplaceHolder rh) [Overrides DefaultFormatter]

pack-private void moveDot (FilterBypass fb, int dot, Bias bias) [Inherited From DefaultFormatter]

NavigationFilter method, subclasses that wish finer control should override this.

pack-private void positionCursorAtInitialLocation () [Inherited From DefaultFormatter]

Positions the cursor at the initial location.

pack-private boolean replace (ReplaceHolder rh) throws BadLocationException [Inherited From DefaultFormatter]

If the edit described by rh is legal, this will return true, commit the edit (if necessary) and update the cursor position.

If the edit described by rh is legal, this will return true, commit the edit (if necessary) and update the cursor position. This forwards to canReplace and isLegalInsertText as necessary to determine if the edit is in fact legal.

All of the DocumentFilter methods funnel into here, you should generally only have to override this.

pack-private void replace (FilterBypass fb, int offset, int length, String text, AttributeSet attrs) throws BadLocationException [Inherited From DefaultFormatter]

DocumentFilter method, funnels into replace.

pack-private void repositionCursor (int offset, int direction) [Inherited From DefaultFormatter]

Resets the cursor by using getNextCursorPosition.

public void setAllowsInvalid (boolean allowsInvalid) [Inherited From DefaultFormatter]

Sets whether or not the value being edited is allowed to be invalid for a length of time (that is, stringToValue throws a ParseException).

Sets whether or not the value being edited is allowed to be invalid
for a length of time (that is, stringToValue throws
a ParseException).
It is often convenient to allow the user to temporarily input an
invalid value.
Parameters:
- allowsInvalid - Used to indicate if the edited value must always be valid

public void setCommitsOnValidEdit (boolean commit) [Inherited From DefaultFormatter]

Sets when edits are published back to the JFormattedTextField.

Sets when edits are published back to the
JFormattedTextField. If true, commitEdit
is invoked after every valid edit (any time the text is edited). On
the other hand, if this is false than the DefaultFormatter
does not publish edits back to the JFormattedTextField.
As such, the only time the value of the JFormattedTextField
will change is when commitEdit is invoked on
JFormattedTextField, typically when enter is pressed
or focus leaves the JFormattedTextField.
Parameters:
- commit - Used to indicate when edits are commited back to the JTextComponent

pack-private void setDot (FilterBypass fb, int dot, Bias bias) [Inherited From DefaultFormatter]

NavigationFilter method, subclasses that wish finer control should override this.

protected void setEditValid (boolean valid) [Inherited From JFormattedTextField.AbstractFormatter]

Invoke this to update the editValid property of the JFormattedTextField.

Invoke this to update the editValid property of the
JFormattedTextField. If you an enforce a policy
such that the JFormattedTextField is always in a
valid state, you will never need to invoke this.
Parameters:
- valid - Valid state of the JFormattedTextField

public void setInvalidCharacters (String invalidCharacters)

Allows for further restricting of the characters that can be input.

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.
Parameters:
- invalidCharacters - If non-null, specifies illegal characters.

public void setMask (String mask) throws ParseException

Sets the mask dictating the legal characters.

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 setOverwriteMode (boolean overwriteMode) [Inherited From DefaultFormatter]

Configures the behavior when inserting characters.

Configures the behavior when inserting characters. If
overwriteMode is true (the default), new characters
overwrite existing characters in the model.
Parameters:
- overwriteMode - Indicates if overwrite or overstrike mode is used

public void setPlaceholder (String placeholder)

Sets the string to use if the value does not completely fill in the mask.

public 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.

public void setValidCharacters (String validCharacters)

Allows for further restricting of the characters that can be input.

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.
Parameters:
- validCharacters - If non-null, specifies legal characters.

public void setValueClass (Class<Object> valueClass) [Inherited From DefaultFormatter]

Sets that class that is used to create new Objects.

public void setValueContainsLiteralCharacters (boolean containsLiteralChars)

If true, the returned value and set value will also contain the literal characters in mask.

public Object stringToValue (String value) throws ParseException [Overrides DefaultFormatter] [Specified in JFormattedTextField.AbstractFormatter]

Parses the text, returning the appropriate Object representation of the String value.

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 MaskFormatter.setValueContainsLiteralCharacters(boolean) for details
on how literals are treated.
Returns: Object representation of text
Parameters:
- value - String to convert
Throws:
- ParseException - if there is an error in the conversion
See Also: MaskFormatter.setValueContainsLiteralCharacters(boolean),

public void uninstall () [Inherited From JFormattedTextField.AbstractFormatter]

Uninstalls any state the AbstractFormatter may have installed on the JFormattedTextField.

Uninstalls any state the AbstractFormatter may have
installed on the JFormattedTextField. This resets the
DocumentFilter, NavigationFilter
and additional Actions installed on the
JFormattedTextField.

pack-private void updateValue () [Inherited From DefaultFormatter]

Pushes the value to the JFormattedTextField if the current value is valid and invokes setEditValid based on the validity of the value.

pack-private void updateValue (Object value) [Inherited From DefaultFormatter]

Pushes the value to the editor if we are to commit on edits.

Pushes the value to the editor if we are to
commit on edits. If value is null, the current value
will be obtained from the text component.

public String valueToString (Object value) throws ParseException [Overrides DefaultFormatter] [Specified in JFormattedTextField.AbstractFormatter]

Returns a String representation of the Object value based on the mask.

Returns a String representation of the Object value
based on the mask. Refer to
MaskFormatter.setValueContainsLiteralCharacters(boolean) for details
on how literals are treated.
Returns: String representation of value
Parameters:
- value - Value to convert
Throws:
- ParseException - if there is an error in the conversion
See Also: MaskFormatter.setValueContainsLiteralCharacters(boolean),