Java javax.swing.text 类 MaskFormatter（JDK5）

177 阅读 0 评论 0 点赞

所有类

概述

软件包

类

使用

树

已过时

索引

帮助

摘要：嵌套 | 字段 | 构造方法 | 方法

详细信息：字段 | 构造方法 | 方法

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
extends DefaultFormatter

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

字符	描述
#	任何有效数字，使用 `Character.isDigit`。
'	转义字符，用于避开任何具有特殊格式的字符。
U	任何字符 (`Character.isLetter`)。将所有小写字母映射为大写。
L	任何字符 (`Character.isLetter`)。将所有大写字母映射为小写。
A	任何字符或数字（`Character.isLetter` 或 `Character.isDigit`）
?	任何字符 (`Character.isLetter`)。
*	所有字符。
H	任何十六进制字符（0-9、a-f 或 A-F）。

字符通常对应于一个 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"。使用右箭头键通过字段导航将生成（| 指示插入符的位置）：

'-' 为字面值（不可编辑的）字符，将跳过这一字符。

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

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

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

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

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

从以下版本开始：: 1.4

构造方法摘要
`MaskFormatter()` 创建一个不带掩码的 MaskFormatter。
`MaskFormatter(String mask)` 创建具有指定掩码的 `MaskFormatter`。

方法摘要
`String`	`getInvalidCharacters()` 返回输入无效的字符。
`String`	`getMask()` 返回格式化掩码。
`String`	`getPlaceholder()` 如果值未完全填充掩码，则返回要使用的 String。
`char`	`getPlaceholderCharacter()` 返回用来替代值中没有的字符的字符（即用户必须填充它们）。
`String`	`getValidCharacters()` 返回可以输入的有效字符。
`boolean`	`getValueContainsLiteralCharacters()` 如果 `stringToValue` 应该返回掩码中的字面值，则返回 true。
`void`	`install(JFormattedTextField ftf)` 将 `DefaultFormatter` 安装在特定的 `JFormattedTextField` 上。
`void`	`setInvalidCharacters(String invalidCharacters)` 允许进一步限制可以输入的字符。
`void`	`setMask(String mask)` 设置指示合法字符的掩码。
`void`	`setPlaceholder(String placeholder)` 设置值未完全填充掩码时要使用的字符串。
`void`	`setPlaceholderCharacter(char placeholder)` 设置一个字符，用来替代值中不存在的字符（即用户必须填充它们）。
`void`	`setValidCharacters(String validCharacters)` 允许进一步限制可以输入的字符。
`void`	`setValueContainsLiteralCharacters(boolean containsLiteralChars)` 如果为 true，则返回的值和设置的值还将包含掩码中的字面值字符。
`Object`	`stringToValue(String value)` 解析文本，返回 String `value` 的适当 Object 表示形式。
`String`	`valueToString(Object value)` 返回基于掩码的 Object `value` 的 String 表示形式。

从类 javax.swing.text.DefaultFormatter 继承的方法
`clone, getAllowsInvalid, getCommitsOnValidEdit, getDocumentFilter, getNavigationFilter, getOverwriteMode, getValueClass, setAllowsInvalid, setCommitsOnValidEdit, setOverwriteMode, setValueClass`

从类 javax.swing.JFormattedTextField.AbstractFormatter 继承的方法
`getActions, getFormattedTextField, invalidEdit, setEditValid, uninstall`

从类 java.lang.Object 继承的方法
`equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

构造方法详细信息

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

返回输入无效的字符。

返回：: 非法字符。