javax.swing.text

Class MaskFormatter

java.lang.Object

javax.swing.JFormattedTextField.AbstractFormatter

javax.swing.text.DefaultFormatter

javax.swing.text.MaskFormatter

All Implemented Interfaces:

Serializable ， Cloneable

public class MaskFormatter
extends DefaultFormatter

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

描述

# 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).

通常字符对应于一个字符，但在某些语言中并不是这样。 面具是以每个字符为基础的，因此将调整为适合所需的许多字符。

您可以进一步限制setInvalidCharacters和setValidCharacters方法可以输入的setInvalidCharacters 。 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) ），则编辑时将根据需要跳过字面字符。 考虑一个带有“### - ####”和当前值“555-1212”的MaskFormatter 。 使用右箭头键浏览该字段将导致（|表示插入符的位置）：

  |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开始，支持所有JavaBeans的长期存储已被添加到java.beans包中。 请参阅XMLEncoder 。

从以下版本开始：

1.4

构造方法摘要

构造方法

Constructor and Description
MaskFormatter() 创建一个没有掩码的MaskFormatter。
MaskFormatter(String mask) 用指定的掩码创建一个 MaskFormatter 。

方法摘要

Modifier and Type	Method and Description
String	getInvalidCharacters() 返回对输入无效的字符。
String	getMask() 返回格式化掩码。
String	getPlaceholder() 如果值未完全填写掩码，则返回要使用的字符串。
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的相应对象表示 value 。
String	valueToString(Object value) 根据掩码返回Object value的String表示形式。

Methods inherited from class javax.swing.text.DefaultFormatter

clone, getAllowsInvalid, getCommitsOnValidEdit, getDocumentFilter, getNavigationFilter, getOverwriteMode, getValueClass, setAllowsInvalid, setCommitsOnValidEdit, setOverwriteMode, setValueClass

Methods inherited from class javax.swing.JFormattedTextField.AbstractFormatter

getActions, getFormattedTextField, invalidEdit, setEditValid, uninstall

Methods inherited from class 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 。 一个ParseException如果将抛出mask是无效的面具。

异常

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

方法详细信息

setMask

public void setMask(String mask)
             throws ParseException

设置掩码规定合法字符。 如果mask无效，将会抛出ParseException 。

异常

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

getMask

public String getMask()

返回格式化掩码。

结果

掩饰法定字符值。

setValidCharacters

public void setValidCharacters(String validCharacters)

允许进一步限制可以输入的字符。 只有在蒙版中指定的invalidCharacters不能在invalidCharacters和validCharacters中被允许输入。 传入null（默认）意味着有效的字符只受掩码和无效字符的约束。

参数

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

getValidCharacters

public String getValidCharacters()

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

结果

法定字符

setInvalidCharacters

public void setInvalidCharacters(String invalidCharacters)

允许进一步限制可以输入的字符。 只有在蒙版中指定的invalidCharacters不能在invalidCharacters和validCharacters中被允许输入。 传入null（默认值）意味着有效字符只受掩码和有效字符的约束。

参数

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

getInvalidCharacters

public String getInvalidCharacters()

返回对输入无效的字符。

结果

非法字符

setPlaceholder

public void setPlaceholder(String placeholder)

如果值未完全填写掩码，则设置要使用的字符串。 null值意味着应该使用占位符char。

参数

placeholder - 如果值未完全填写掩码，则在格式化时使用的字符串

getPlaceholder

public String getPlaceholder()

如果值未完全填写掩码，则返回要使用的字符串。

结果

格式化时使用的字符串，如果该值未完全填满该掩码

setPlaceholderCharacter

public void setPlaceholderCharacter(char placeholder)

设置要使用的字符代替值中不存在的字符，即用户必须填写它们。默认值为空格。

仅当尚未指定占位符字符串或者未完全填写掩码时，才适用。

参数

placeholder - 格式化时使用的字符，如果该值未完全填满该掩码

getPlaceholderCharacter

public char getPlaceholderCharacter()

返回要用于代替值中不存在的字符的字符，即用户必须填写它们。

结果

格式化时使用的字符，如果该值未完全填满该掩码

setValueContainsLiteralCharacters

public void setValueContainsLiteralCharacters(boolean containsLiteralChars)

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

例如，如果掩码为'(###) ###-####' ，则当前值为'(415) 555-1212' ，而valueContainsLiteralCharacters为真stringToValue将返回'(415) 555-1212' 。 另一方面，如果valueContainsLiteralCharacters是假的， stringToValue将返回'4155551212' 。

参数

containsLiteralChars - 用于指示是否应在stringToValue中返回掩码中的字符字符

getValueContainsLiteralCharacters

public boolean getValueContainsLiteralCharacters()

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

结果

如果掩码中的文字字符应该返回到stringToValue，则为真

stringToValue

public Object stringToValue(String value)
                     throws ParseException

解析文本，返回String value的相应对象表示value 。 这将根据需要剥离文字字符，并调用超级stringToValue ，以便如果您指定了一个值类（ setValueClass ），则会创建一个实例。 如果该值与当前掩码不匹配，则会抛出ParseException 。 有关如何处理文字的详细信息，请参阅setValueContainsLiteralCharacters(boolean) 。

重写：

stringToValue在 DefaultFormatter

参数

value - 要转换的字符串

结果

文本的对象表示

异常

ParseException - 转换中是否有错误

另请参见：

setValueContainsLiteralCharacters(boolean)

valueToString

public String valueToString(Object value)
                     throws ParseException

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

重写：

valueToString中的 DefaultFormatter

参数

value - 要转换的价值

结果

值的字符串表示

异常

ParseException - 转换中是否有错误

另请参见：

setValueContainsLiteralCharacters(boolean)

install

public void install(JFormattedTextField ftf)

将DefaultFormatter安装到特定的JFormattedTextField 。 这将调用valueToString将当前值从JFormattedTextField转换为字符串。 那么这将安装Action从s getActions ，该DocumentFilter从返回getDocumentFilter和NavigationFilter从返回getNavigationFilter到JFormattedTextField 。

子类通常只需要覆盖这个，如果他们希望在JFormattedTextField上安装其他监听JFormattedTextField 。

如果有一个ParseException将当前值转换为字符串，则将文本设置为空字符串，并将JFormattedTextField标记为无效状态。

虽然这是一种公共方法，但这通常仅适用于JFormattedTextField的JFormattedTextField 。 JFormattedTextField将在值更改或其内部状态更改的适当时候调用此方法。

重写：

install在 DefaultFormatter

参数

ftf - JFormattedTextField格式化，可能为null表示从当前JFormattedTextField卸载。