< prev index next >

src/java.desktop/share/classes/javax/swing/text/MaskFormatter.java

Print this page

        

*** 29,70 **** import java.text.*; import java.util.*; import javax.swing.*; /** ! * <code>MaskFormatter</code> is used to format and edit strings. The behavior ! * of a <code>MaskFormatter</code> is controlled by way of a String mask * that specifies the valid characters that can be contained at a particular ! * location in the <code>Document</code> model. The following characters can * be specified: * * <table border=1 summary="Valid characters and their descriptions"> * <tr> * <th>Character&nbsp;</th> * <th><p style="text-align:left">Description</p></th> * </tr> * <tr> * <td>#</td> ! * <td>Any valid number, uses <code>Character.isDigit</code>.</td> * </tr> * <tr> * <td>'</td> * <td>Escape character, used to escape any of the * special formatting characters.</td> * </tr> * <tr> ! * <td>U</td><td>Any character (<code>Character.isLetter</code>). All * lowercase letters are mapped to upper case.</td> * </tr> ! * <tr><td>L</td><td>Any character (<code>Character.isLetter</code>). All * upper case letters are mapped to lower case.</td> * </tr> ! * <tr><td>A</td><td>Any character or number (<code>Character.isLetter</code> ! * or <code>Character.isDigit</code>)</td> * </tr> * <tr><td>?</td><td>Any character ! * (<code>Character.isLetter</code>).</td> * </tr> * <tr><td>*</td><td>Anything.</td></tr> * <tr><td>H</td><td>Any hex character (0-9, a-f or A-F).</td></tr> * </table> * --- 29,70 ---- import java.text.*; import java.util.*; import javax.swing.*; /** ! * {@code MaskFormatter} is used to format and edit strings. The behavior ! * of a {@code MaskFormatter} is controlled by way of a String mask * that specifies the valid characters that can be contained at a particular ! * location in the {@code Document} model. The following characters can * be specified: * * <table border=1 summary="Valid characters and their descriptions"> * <tr> * <th>Character&nbsp;</th> * <th><p style="text-align:left">Description</p></th> * </tr> * <tr> * <td>#</td> ! * <td>Any valid number, uses {@code Character.isDigit}.</td> * </tr> * <tr> * <td>'</td> * <td>Escape character, used to escape any of the * special formatting characters.</td> * </tr> * <tr> ! * <td>U</td><td>Any character ({@code Character.isLetter}). All * lowercase letters are mapped to upper case.</td> * </tr> ! * <tr><td>L</td><td>Any character ({@code Character.isLetter}). All * upper case letters are mapped to lower case.</td> * </tr> ! * <tr><td>A</td><td>Any character or number ({@code Character.isLetter} ! * or {@code Character.isDigit})</td> * </tr> * <tr><td>?</td><td>Any character ! * ({@code Character.isLetter}).</td> * </tr> * <tr><td>*</td><td>Anything.</td></tr> * <tr><td>H</td><td>Any hex character (0-9, a-f or A-F).</td></tr> * </table> *
*** 72,84 **** * 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. * <p> * You can further restrict the characters that can be input by the ! * <code>setInvalidCharacters</code> and <code>setValidCharacters</code> ! * methods. <code>setInvalidCharacters</code> allows you to specify ! * which characters are not legal. <code>setValidCharacters</code> 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: * <pre> * MaskFormatter formatter = new MaskFormatter("0x***"); --- 72,84 ---- * 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. * <p> * You can further restrict the characters that can be input by the ! * {@code setInvalidCharacters} and {@code setValidCharacters} ! * methods. {@code setInvalidCharacters} allows you to specify ! * which characters are not legal. {@code 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: * <pre> * MaskFormatter formatter = new MaskFormatter("0x***");
*** 94,110 **** * formatter.setPlaceholderCharacter('_'); * formatter.getDisplayValue(tf, "123"); * </pre> * <p> * Would result in the string '123-____'. If ! * <code>setPlaceholder("555-1212")</code> 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. * <p> ! * If a <code>MaskFormatter</code> is configured to only allow valid characters ! * (<code>setAllowsInvalid(false)</code>) literal characters will be skipped as ! * necessary when editing. Consider a <code>MaskFormatter</code> 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): * <pre> * |555-1212 --- 94,110 ---- * formatter.setPlaceholderCharacter('_'); * formatter.getDisplayValue(tf, "123"); * </pre> * <p> * Would result in the string '123-____'. If ! * {@code 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. * <p> ! * If a {@code MaskFormatter} is configured to only allow valid characters ! * ({@code setAllowsInvalid(false)}) literal characters will be skipped as ! * necessary when editing. Consider a {@code 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): * <pre> * |555-1212
*** 114,152 **** * 555-1|212 * </pre> * The '-' is a literal (non-editable) character, and is skipped. * <p> * Similar behavior will result when editing. Consider inserting the string ! * '123-45' and '12345' into the <code>MaskFormatter</code> in the * previous example. Both inserts will result in the same String, ! * '123-45__'. When <code>MaskFormatter</code> * is processing the insert at character position 3 (the '-'), two things can * happen: * <ol> * <li>If the inserted character is '-', it is accepted. * <li>If the inserted character matches the mask for the next non-literal * character, it is accepted at the new location. * <li>Anything else results in an invalid edit * </ol> * <p> ! * By default <code>MaskFormatter</code> will not allow invalid edits, you can ! * change this with the <code>setAllowsInvalid</code> method, and will ! * commit edits on valid edits (use the <code>setCommitsOnValidEdit</code> to * change this). * <p> ! * By default, <code>MaskFormatter</code> 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 <code>setOverwriteMode</code>. * <p> * <strong>Warning:</strong> * 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&trade; ! * has been added to the <code>java.beans</code> package. * Please see {@link java.beans.XMLEncoder}. * * @since 1.4 */ @SuppressWarnings("serial") // Same-version serialization only --- 114,152 ---- * 555-1|212 * </pre> * The '-' is a literal (non-editable) character, and is skipped. * <p> * Similar behavior will result when editing. Consider inserting the string ! * '123-45' and '12345' into the {@code MaskFormatter} in the * previous example. Both inserts will result in the same String, ! * '123-45__'. When {@code MaskFormatter} * is processing the insert at character position 3 (the '-'), two things can * happen: * <ol> * <li>If the inserted character is '-', it is accepted. * <li>If the inserted character matches the mask for the next non-literal * character, it is accepted at the new location. * <li>Anything else results in an invalid edit * </ol> * <p> ! * By default {@code MaskFormatter} will not allow invalid edits, you can ! * change this with the {@code setAllowsInvalid} method, and will ! * commit edits on valid edits (use the {@code setCommitsOnValidEdit} to * change this). * <p> ! * By default, {@code 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 {@code setOverwriteMode}. * <p> * <strong>Warning:</strong> * 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&trade; ! * has been added to the {@code java.beans} package. * Please see {@link java.beans.XMLEncoder}. * * @since 1.4 */ @SuppressWarnings("serial") // Same-version serialization only
*** 194,217 **** maskChars = EmptyMaskChars; placeholder = ' '; } /** ! * Creates a <code>MaskFormatter</code> with the specified mask. ! * A <code>ParseException</code> ! * will be thrown if <code>mask</code> is an invalid mask. * @param mask the 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 <code>ParseException</code> if <code>mask</code> is * not valid. * @param mask the mask * * @throws ParseException if mask does not contain valid mask characters */ --- 194,217 ---- maskChars = EmptyMaskChars; placeholder = ' '; } /** ! * Creates a {@code MaskFormatter} with the specified mask. ! * A {@code ParseException} ! * will be thrown if {@code mask} is an invalid mask. * @param mask the 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 {@code ParseException} if {@code mask} is * not valid. * @param mask the mask * * @throws ParseException if mask does not contain valid mask characters */
*** 230,241 **** } /** * Allows for further restricting of the characters that can be input. * Only characters specified in the mask, not in the ! * <code>invalidCharacters</code>, and in ! * <code>validCharacters</code> 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. */ --- 230,241 ---- } /** * Allows for further restricting of the characters that can be input. * Only characters specified in the mask, not in the ! * {@code invalidCharacters}, and in ! * {@code 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. */
*** 253,264 **** } /** * Allows for further restricting of the characters that can be input. * Only characters specified in the mask, not in the ! * <code>invalidCharacters</code>, and in ! * <code>validCharacters</code> 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. */ --- 253,264 ---- } /** * Allows for further restricting of the characters that can be input. * Only characters specified in the mask, not in the ! * {@code invalidCharacters}, and in ! * {@code 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. */
*** 325,352 **** /** * If true, the returned value and set value will also contain the literal * characters in mask. * <p> ! * For example, if the mask is <code>'(###) ###-####'</code>, the ! * current value is <code>'(415) 555-1212'</code>, and ! * <code>valueContainsLiteralCharacters</code> is ! * true <code>stringToValue</code> will return ! * <code>'(415) 555-1212'</code>. On the other hand, if ! * <code>valueContainsLiteralCharacters</code> is false, ! * <code>stringToValue</code> will return <code>'4155551212'</code>. * * @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 <code>stringToValue</code> should return literal * characters in the mask. * * @return True if literal characters in mask should be returned in * stringToValue */ --- 325,352 ---- /** * If true, the returned value and set value will also contain the literal * characters in mask. * <p> ! * For example, if the mask is {@code '(###) ###-####'}, the ! * current value is {@code '(415) 555-1212'}, and ! * {@code valueContainsLiteralCharacters} is ! * true {@code stringToValue} will return ! * {@code '(415) 555-1212'}. On the other hand, if ! * {@code valueContainsLiteralCharacters} is false, ! * {@code stringToValue} will return {@code '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 {@code stringToValue} should return literal * characters in the mask. * * @return True if literal characters in mask should be returned in * stringToValue */
*** 354,368 **** return containsLiteralChars; } /** * Parses the text, returning the appropriate Object representation of ! * the String <code>value</code>. This strips the literal characters as ! * necessary and invokes supers <code>stringToValue</code>, so that if ! * you have specified a value class (<code>setValueClass</code>) an * instance of it will be created. This will throw a ! * <code>ParseException</code> 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 --- 354,368 ---- return containsLiteralChars; } /** * Parses the text, returning the appropriate Object representation of ! * the String {@code value}. This strips the literal characters as ! * necessary and invokes supers {@code stringToValue}, so that if ! * you have specified a value class ({@code setValueClass}) an * instance of it will be created. This will throw a ! * {@code 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
*** 372,382 **** public Object stringToValue(String value) throws ParseException { return stringToValue(value, true); } /** ! * Returns a String representation of the Object <code>value</code> * 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 --- 372,382 ---- public Object stringToValue(String value) throws ParseException { return stringToValue(value, true); } /** ! * Returns a String representation of the Object {@code 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
*** 393,425 **** append(result, sValue, valueCounter, placeholder, maskChars); return result.toString(); } /** ! * Installs the <code>DefaultFormatter</code> onto a particular ! * <code>JFormattedTextField</code>. ! * This will invoke <code>valueToString</code> to convert the ! * current value from the <code>JFormattedTextField</code> to ! * a String. This will then install the <code>Action</code>s from ! * <code>getActions</code>, the <code>DocumentFilter</code> ! * returned from <code>getDocumentFilter</code> and the ! * <code>NavigationFilter</code> returned from ! * <code>getNavigationFilter</code> onto the ! * <code>JFormattedTextField</code>. * <p> * Subclasses will typically only need to override this if they * wish to install additional listeners on the ! * <code>JFormattedTextField</code>. * <p> ! * If there is a <code>ParseException</code> in converting the * current value to a String, this will set the text to an empty ! * String, and mark the <code>JFormattedTextField</code> as being * in an invalid state. * <p> * While this is a public method, this is typically only useful ! * for subclassers of <code>JFormattedTextField</code>. ! * <code>JFormattedTextField</code> 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. --- 393,425 ---- append(result, sValue, valueCounter, placeholder, maskChars); return result.toString(); } /** ! * Installs the {@code DefaultFormatter} onto a particular ! * {@code JFormattedTextField}. ! * This will invoke {@code valueToString} to convert the ! * current value from the {@code JFormattedTextField} to ! * a String. This will then install the {@code Action}s from ! * {@code getActions}, the {@code DocumentFilter} ! * returned from {@code getDocumentFilter} and the ! * {@code NavigationFilter} returned from ! * {@code getNavigationFilter} onto the ! * {@code JFormattedTextField}. * <p> * Subclasses will typically only need to override this if they * wish to install additional listeners on the ! * {@code JFormattedTextField}. * <p> ! * If there is a {@code ParseException} in converting the * current value to a String, this will set the text to an empty ! * String, and mark the {@code JFormattedTextField} as being * in an invalid state. * <p> * While this is a public method, this is typically only useful ! * for subclassers of {@code JFormattedTextField}. ! * {@code 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.
*** 438,450 **** } } } /** ! * Actual <code>stringToValue</code> implementation. ! * If <code>completeMatch</code> is true, the value must exactly match ! * the mask, on the other hand if <code>completeMatch</code> is false * the string must match the mask or the placeholder string. */ private Object stringToValue(String value, boolean completeMatch) throws ParseException { int errorOffset; --- 438,450 ---- } } } /** ! * Actual {@code stringToValue} implementation. ! * If {@code completeMatch} is true, the value must exactly match ! * the mask, on the other hand if {@code completeMatch} is false * the string must match the mask or the placeholder string. */ private Object stringToValue(String value, boolean completeMatch) throws ParseException { int errorOffset;
*** 480,491 **** } return -1; } /** ! * Invokes <code>append</code> on the mask characters in ! * <code>mask</code>. */ private void append(StringBuilder result, String value, int[] index, String placeholder, MaskCharacter[] mask) throws ParseException { for (int counter = 0, maxCounter = mask.length; --- 480,491 ---- } return -1; } /** ! * Invokes {@code append} on the mask characters in ! * {@code mask}. */ private void append(StringBuilder result, String value, int[] index, String placeholder, MaskCharacter[] mask) throws ParseException { for (int counter = 0, maxCounter = mask.length;
*** 667,689 **** } /** * Returns true if the MaskFormatter allows invalid, or * the offset is less than the max length and the character at ! * <code>offset</code> is a literal. */ boolean isNavigatable(int offset) { if (!getAllowsInvalid()) { return (offset < getMaxLength() && !isLiteral(offset)); } return true; } /* ! * Returns true if the operation described by <code>rh</code> will ! * result in a legal edit. This may set the <code>value</code> ! * field of <code>rh</code>. * <p> * This is overriden to return true for a partial match. */ boolean isValidEdit(ReplaceHolder rh) { if (!getAllowsInvalid()) { --- 667,689 ---- } /** * Returns true if the MaskFormatter allows invalid, or * the offset is less than the max length and the character at ! * {@code offset} is a literal. */ boolean isNavigatable(int offset) { if (!getAllowsInvalid()) { return (offset < getMaxLength() && !isLiteral(offset)); } return true; } /* ! * Returns true if the operation described by {@code rh} will ! * result in a legal edit. This may set the {@code value} ! * field of {@code rh}. * <p> * This is overriden to return true for a partial match. */ boolean isValidEdit(ReplaceHolder rh) { if (!getAllowsInvalid()) {
*** 830,843 **** public boolean isLiteral() { return false; } /** ! * Returns true if <code>aChar</code> is a valid reprensentation of * the receiver. The default implementation returns true if the ! * receiver represents a literal character and <code>getChar</code> ! * == aChar. Otherwise, this will return true is <code>aChar</code> * is contained in the valid characters and not contained * in the invalid characters. */ public boolean isValidCharacter(char aChar) { if (isLiteral()) { --- 830,843 ---- public boolean isLiteral() { return false; } /** ! * Returns true if {@code aChar} is a valid reprensentation of * the receiver. The default implementation returns true if the ! * receiver represents a literal character and {@code getChar} ! * == aChar. Otherwise, this will return true is {@code aChar} * is contained in the valid characters and not contained * in the invalid characters. */ public boolean isValidCharacter(char aChar) { if (isLiteral()) {
*** 857,878 **** } return true; } /** ! * Returns the character to insert for <code>aChar</code>. The ! * default implementation returns <code>aChar</code>. 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 <code>formatting</code> at ! * <code>index</code> to <code>buff</code>. */ public void append(StringBuilder buff, String formatting, int[] index, String placeholder) throws ParseException { boolean inString = index[0] < formatting.length(); --- 857,878 ---- } return true; } /** ! * Returns the character to insert for {@code aChar}. The ! * default implementation returns {@code 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 {@code formatting} at ! * {@code index} to {@code buff}. */ public void append(StringBuilder buff, String formatting, int[] index, String placeholder) throws ParseException { boolean inString = index[0] < formatting.length();
*** 928,938 **** } } /** ! * Represents a number, uses <code>Character.isDigit</code>. */ private class DigitMaskCharacter extends MaskCharacter { public boolean isValidCharacter(char aChar) { return (Character.isDigit(aChar) && super.isValidCharacter(aChar)); --- 928,938 ---- } } /** ! * Represents a number, uses {@code Character.isDigit}. */ private class DigitMaskCharacter extends MaskCharacter { public boolean isValidCharacter(char aChar) { return (Character.isDigit(aChar) && super.isValidCharacter(aChar));
*** 940,950 **** } /** * Represents a character, lower case letters are mapped to upper case ! * using <code>Character.toUpperCase</code>. */ private class UpperCaseCharacter extends MaskCharacter { public boolean isValidCharacter(char aChar) { return (Character.isLetter(aChar) && super.isValidCharacter(aChar)); --- 940,950 ---- } /** * Represents a character, lower case letters are mapped to upper case ! * using {@code Character.toUpperCase}. */ private class UpperCaseCharacter extends MaskCharacter { public boolean isValidCharacter(char aChar) { return (Character.isLetter(aChar) && super.isValidCharacter(aChar));
*** 956,966 **** } /** * Represents a character, upper case letters are mapped to lower case ! * using <code>Character.toLowerCase</code>. */ private class LowerCaseCharacter extends MaskCharacter { public boolean isValidCharacter(char aChar) { return (Character.isLetter(aChar) && super.isValidCharacter(aChar)); --- 956,966 ---- } /** * Represents a character, upper case letters are mapped to lower case ! * using {@code Character.toLowerCase}. */ private class LowerCaseCharacter extends MaskCharacter { public boolean isValidCharacter(char aChar) { return (Character.isLetter(aChar) && super.isValidCharacter(aChar));
*** 972,993 **** } /** * Represents either a character or digit, uses ! * <code>Character.isLetterOrDigit</code>. */ private class AlphaNumericCharacter extends MaskCharacter { public boolean isValidCharacter(char aChar) { return (Character.isLetterOrDigit(aChar) && super.isValidCharacter(aChar)); } } /** ! * Represents a letter, uses <code>Character.isLetter</code>. */ private class CharCharacter extends MaskCharacter { public boolean isValidCharacter(char aChar) { return (Character.isLetter(aChar) && super.isValidCharacter(aChar)); --- 972,993 ---- } /** * Represents either a character or digit, uses ! * {@code Character.isLetterOrDigit}. */ private class AlphaNumericCharacter extends MaskCharacter { public boolean isValidCharacter(char aChar) { return (Character.isLetterOrDigit(aChar) && super.isValidCharacter(aChar)); } } /** ! * Represents a letter, uses {@code Character.isLetter}. */ private class CharCharacter extends MaskCharacter { public boolean isValidCharacter(char aChar) { return (Character.isLetter(aChar) && super.isValidCharacter(aChar));
< prev index next >