javax.swing.text
类 MaskFormatter

java.lang.Object
  javax.swing.JFormattedTextField.AbstractFormatter
      javax.swing.text.DefaultFormatter
          javax.swing.text.MaskFormatter

所有已实现的接口：

Serializable, Cloneable

public class MaskFormatter
     

      extends 
      DefaultFormatter
     

MaskFormatter 用于格式化和编辑字符串。MaskFormatter 的行为通过 String 掩码控制，该掩码指定可以包含在 Document 模型中特定位置的有效字符。可以指定以下字符：

字符通常对应于一个 char，但在某些语言中不是这样。掩码是以单个字符为基础的，因此可以任意调整 char 数量来满足需要。

可以进一步限制可通过 setInvalidCharacters 和 setValidCharacters 方法输入的字符。setInvalidCharacters 允许指定哪些字符无效。setValidCharacters 允许指定哪些字符有效。例如，以下代码块与具有无效/有效字符的 '0xHHH' 掩码等效：

 MaskFormatter formatter = new MaskFormatter("0x***");
 formatter.setValidCharacters("0123456789abcdefABCDEF");
 

最初格式化值时，如果字符串的长度小于掩码的长度，则可能发生以下两种情况。要么使用占位符字符串，要么使用占位符字符。优先考虑使用占位符字符串。例如：

   MaskFormatter formatter = new MaskFormatter("###-####");
   formatter.setPlaceholderCharacter('_');
   formatter.getDisplayValue(tf, "123");
 

可能生成字符串 '123-____'。如果已调用 setPlaceholder("555-1212")，则生成 '123-1212'。占位符字符串只用于初始格式，后续格式只使用占位符字符。

如果 MaskFormatter 配置为只允许有效字符 (setAllowsInvalid(false))，则在编辑时将根据需要跳过字面值字符。假定 MaskFormatter 带有掩码 "###-####"，且当前值为 "555-1212"。使用右箭头键通过字段导航将生成（| 指示插入符的位置）：

   |555-1212
   5|55-1212
   55|5-1212
   555-|1212
   555-1|212
 

编辑时会导致类似行为。假定在前一示例中将字符串 '123-45' 和 '12345' 插入 MaskFormatter。两项插入都将导致相同的字符串 '123-45__'。MaskFormatter 在字符位置 3（即 '-'）处理插入时，可能发生以下两种情况：

1. 如果插入的字符是 '-'，则接受它。
2. 如果插入的字符与下一个非字面值字符的掩码匹配，则在新位置接受它。
3. 其他任何情况都将导致无效的编辑

默认情况下，MaskFormatter 将不允许无效编辑，您可以使用 setAllowsInvalid 方法更改此设置，并在有效编辑状态提交编辑（使用 setCommitsOnValidEdit 更改此设置）。

默认情况下，MaskFormatter 处于改写模式。也就是说，键入字符时不插入新字符，而是使用新键入的字符替换当前位置的字符。可以通过方法 setOverwriteMode 更改此行为。

警告：此类的已序列化对象与以后的 Swing 版本不兼容。当前序列化支持适用于短期存储或运行相同 Swing 版本的应用程序之间的 RMI。从 1.4 版本开始，已在 java.beans 包中添加了支持所有 JavaBeans^TM 长期存储的功能。请参见 XMLEncoder。

从以下版本开始：

1.4

MaskFormatter

public MaskFormatter()

创建一个不带掩码的 MaskFormatter。

MaskFormatter

public MaskFormatter(String mask)
              throws ParseException

创建具有指定掩码的 MaskFormatter。如果 mask 不是有效掩码，则抛出 ParseException。

抛出：

ParseException - 如果掩码不包含有效掩码字符

setMask

public void setMask(String mask)
             throws ParseException

设置指示合法字符的掩码。如果 mask 无效，这将抛出一个 ParseException。

抛出：

ParseException - 如果掩码不包含有效掩码字符

getMask

public String getMask()

返回格式化掩码。

返回：

指示合法字符值的掩码。

setValidCharacters

public void setValidCharacters(String validCharacters)

允许进一步限制可以输入的字符。只允许输入在掩码中指定的（不是 invalidCharacters，而是 validCharacters）字符。传入 null（默认）意味着有效字符只由掩码和无效字符限定范围。

参数：

validCharacters - 如果为非 null，则指定合法字符。

getValidCharacters

public String getValidCharacters()

返回可以输入的有效字符。

返回：

合法字符

setInvalidCharacters

public void setInvalidCharacters(String invalidCharacters)

允许进一步限制可以输入的字符。只允许输入在掩码中指定的（不是 invalidCharacters，而是 validCharacters）字符。传入 null （默认）意味着有效字符只由掩码和有效字符限定范围。

参数：

invalidCharacters - 如果为非 null，则指定非法字符。

getInvalidCharacters

public String getInvalidCharacters()

返回输入无效的字符。

返回：

非法字符。

setPlaceholder

public void setPlaceholder(String placeholder)

设置值未完全填充掩码时要使用的字符串。null 值意味着应该使用占位字符。

参数：

placeholder - 值未完全填充掩码的情况下格式化时使用的字符串

getPlaceholder

public String getPlaceholder()

如果值未完全填充掩码，则返回要使用的 String。

返回：

如果值未完全填充掩码，则返回格式化时使用的 String

setPlaceholderCharacter

public void setPlaceholderCharacter(char placeholder)

设置一个字符，用来替代值中不存在的字符（即用户必须填充它们）。默认值为一个空格。

此方法仅适用于占位符字符串尚未指定，或未完全填充掩码的情况。

参数：

placeholder - 如果值未完全填充掩码，则为格式化时使用的 Character

getPlaceholderCharacter

public char getPlaceholderCharacter()

返回用来替代值中没有的字符的字符（即用户必须填充它们）。

返回：

如果值未完全填充掩码，则返回格式化时使用的 Character

setValueContainsLiteralCharacters

public void setValueContainsLiteralCharacters(boolean containsLiteralChars)

如果为 true，则返回的值和设置的值还将包含掩码中的字面值字符。

例如，如果掩码为 '(###) ###-####'，当前值为 '(415) 555-1212'，且 valueContainsLiteralCharacters 为 true，则 stringToValue 将返回 '(415) 555-1212'。另一方面，如果 valueContainsLiteralCharacters 为 false，则 stringToValue 将返回 '4155551212'。

参数：

containsLiteralChars - 用于指示掩码中的字面值是否应该在 stringToValue 中返回。

getValueContainsLiteralCharacters

public boolean getValueContainsLiteralCharacters()

如果 stringToValue 应该返回掩码中的字面值，则返回 true。

返回：

如果掩码中的字面值应该在 stringToValue 中返回，则返回 True

stringToValue

public Object stringToValue(String value)
                     throws ParseException

解析文本，返回 String value 的适当 Object 表示形式。此方法将在必要时将字面值字符分开并调用超类 stringToValue，所以，如果已指定了值类 ( setValueClass)，则将创建它的一个实例。如果该值与当前掩码不匹配，这将抛出一个 ParseException。有关如何处理字面值的详细信息，请参阅 setValueContainsLiteralCharacters(boolean)。

覆盖：

类 DefaultFormatter 中的 stringToValue

参数：

value - 要转换的字符串

返回：

文本的 Object 表示形式

抛出：

ParseException - 如果在转换时发生错误

另请参见：

setValueContainsLiteralCharacters(boolean)

valueToString

public String valueToString(Object value)
                     throws ParseException

返回基于掩码的 Object value 的 String 表示形式。有关如何处理字面值的详细信息，请参阅 setValueContainsLiteralCharacters(boolean)。

覆盖：

类 DefaultFormatter 中的 valueToString

参数：

value - 要转换的 Value

返回：

值的 String 表示形式

抛出：

ParseException - 如果在转换时发生错误

另请参见：

setValueContainsLiteralCharacters(boolean)

install

public void install(JFormattedTextField ftf)

将 DefaultFormatter 安装在特定的 JFormattedTextField 上。这将调用 valueToString，将 JFormattedTextField 中的当前值转换为 String。此方法稍后将会把 getActions 返回的 Action、 getDocumentFilter 返回的 DocumentFilter 和 getNavigationFilter 返回的 NavigationFilter 安装到 JFormattedTextField 上。

如果子类希望在 JFormattedTextField 上安装其他侦听器，则通常只需要重写此方法。

如果在将当前值转换为 String 时存在 ParseException，则这会将文本设置为空 String，并将 JFormattedTextField 标记为正处在无效状态。

尽管这是一个公共方法，但通常仅供 JFormattedTextField 的子类使用。当值发生更改，或内部状态发生更改时，JFormattedTextField 将在适当的时候调用此方法。

覆盖：

类 DefaultFormatter 中的 install

参数：

ftf - 要格式化为的 JFormattedTextField，可以为 null，这指示从当前的 JFormattedTextField 卸载。