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 동작은 Document 모델의 특정의 위치에 있는 유효한 문자를 지정하는 String 마스크 경유로 제어됩니다. 다음의 문자를 지정할 수 있습니다.

문자	설명
#	임의의 유효한 숫자. Character.isDigit를 사용하는
'	이스케이프 문자. 특수한 서식 설정 문자를 이스케이프 하는
U	임의의 문자 (Character.isLetter). 모든 소문자는 대문자에 매핑 되는
L	임의의 문자 (Character.isLetter). 모든 대문자는 소문자에 매핑 되는
A	임의의 문자 또는 숫자 (Character.isLetter 또는 Character.isDigit)
?	임의의 문자 (Character.isLetter)
*	모든 문자 및 숫자
H	임의의 16 진수 문자 (0-9, a-f 또는 A-F)

보통, 문자는 1개의 char에 대응합니다만, 일부의 언어에서는 이것은 들어맞지 않습니다. 마스크는 문자 마다 달라, 필요한 수의 char에 적응하도록 조정됩니다.

setInvalidCharacters와 setValidCharacters 메서드로 입력 가능한 문자를 상세하게 한정할 수 있습니다. setInvalidCharacters에 서는 어느 문자가 부정한가를 지정할 수 있습니다. 또 setValidCharacters에 서는 어느 문자가 유효한가를 지정할 수 있습니다. 예를 들어아래의 코드 블록은 무효 또는 유효한 문자를 가지지 않는 「0 xHHH」의 마스크와 동일해집니다.

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

캐릭터 라인의 길이가 마스크의 길이보다 짧은 경우에 값을 최초로 서식 설정할 때, 플레이스홀더 캐릭터 라인이 사용되는지, 또는 플레이스홀더 문자가 사용됩니다. 우선 순위는 플레이스홀더 캐릭터 라인에 있습니다. 다음에 예를 나타냅니다.

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

결과는 캐릭터 라인 「123-____」이 됩니다. setPlaceholder("555-1212")가 불려 갔을 경우, 결과는 「123-1212」이라고 됩니다. 플레이스홀더 String는 최초의 서식 설정에만 사용되어 그 후의 서식 설정에서는 플레이스홀더 문자만이 사용됩니다.

MaskFormatter가 유효한 문자만을 허가하도록 구성되어 있는 경우 (setAllowsInvalid(false)), 편집시에는 필요에 따라서 리터럴 문자가 스킵 됩니다. 마스크 「###-####」 및 현재가 「555-1212」을 보관 유지하는 MaskFormatter를 생각해 봅시다. 오른쪽 커서 키를 사용해 필드를 안내하면, 아래와 같이 됩니다 (|는 caret의 위치).

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

「-」은 편집 불가능한 리터럴 문자로 스킵 됩니다.

편집시에는 결과적으로 같은 동작이 발생합니다. 위의 예의 MaskFormatter에 캐릭터 라인 「123-45」과「12345」를 삽입하는 경우를 생각해 봅시다. 양쪽 모두를 삽입하면, 결과적으로 같은 String ? 23-45__운엄? 항이w. 문자 위치 3 ( 「-」)으로 MaskFormatter가 삽입 처리를 실시하면, 2개가 일어납니다.

1. 삽입된 문자가 「-」의 경우는 받아들일 수 있다
2. 삽입된 문자가 다음의 비리터럴 문자의 마스크에 일치하는 경우, 새로운 위치에서 받아들일 수 있다
3. 그 이외의 문자가 삽입되면, 무효인 편집이 된다

디폴트에서는 MaskFormatter는 무효인 편집을 허용합니다만, setAllowsInvalid 메서드를 사용한다고 변경할 수 있습니다. 이 경우 유효한 편집으로서 편집 내용을 위탁할 수 있습니다 (변경에는 setCommitsOnValidEdit를 사용).

디폴트에서는 MaskFormatter는 덧쓰기 모드(replace mode)입니다. 즉 문자가 입력되면, 새로운 문자가 삽입되는 것이 아니라, 현재 위치의 문자가 새로운에 입력된 문자에 옮겨집니다. 이 동작은 setOverwriteMode 메서드로 변경할 수 있습니다.

경고: 이 클래스의 직렬화 된 객체는 향후의 Swing 릴리즈와 호환되지 않을 예정입니다. 현재의 직렬화의 지원은 단기간의 운용이나, 같은 버전의 Swing를 실행하는 어플리케이션간의 RMI에 적절하고 있습니다. JDK 버전 1.4 이후, 모든 JavaBeans^™ 장기간의 운용 지원은 java.beans 패키지에 추가되고 있습니다. 자세한 내용은 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()

입력이 무효인 문자를 리턴합니다.

반환값:

부정한 문자

setPlaceholder

public void setPlaceholder(String  placeholder)

값이 마스크를 완전하게 묻지 않은 경우에 사용하는 캐릭터 라인을 설정합니다. null 치는 플레이스홀더 char를 사용하는 것을 나타냅니다.

파라미터:

placeholder - 값이 마스크를 완전하게 묻지 않은 경우, 서식 설정에 사용되는 String

getPlaceholder

public String  getPlaceholder()

값이 마스크를 완전하게 묻지 않은 경우에 사용하는 String를 리턴합니다.

반환값:

값이 마스크를 완전하게 묻지 않은 경우, 서식 설정에 사용되는 String

setPlaceholderCharacter

public void setPlaceholderCharacter(char placeholder)

값에는 없는 문자 (즉 사용자가 입력할 필요가 있는 문자) 대신에 사용하는 문자를 설정합니다. 기본값는 공백 문자입니다.

이것은 플레이스홀더 캐릭터 라인이 지정되어 있지 않은지, 마스크가 완전하게 매장되어 있지 않은 경우에만 적용 가능합니다.

파라미터:

placeholder - 값이 마스크를 완전하게 묻지 않은 경우, 서식 설정에 사용되는 문자

getPlaceholderCharacter

public char getPlaceholderCharacter()

값에는 없는 문자 (즉 사용자가 입력할 필요가 있는 문자) 대신에 사용하는 문자를 리턴합니다.

반환값:

값이 마스크를 완전하게 묻지 않은 경우, 서식 설정에 사용되는 문자

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 표현을 리턴합니다. 값클래스 (setValueClass)를 지정되어 있는 경우는 그 인스턴스를 작성하기 위해, 필요에 따라서 리터럴 문자를 없애, 슈퍼 클래스 stringToValue를 호출합니다. 값이 현재의 마스크에 일치하지 않는 경우, ParseException가 발생 됩니다. 리터럴의 취급 방법의자세한 내용은 setValueContainsLiteralCharacters(boolean)를 참조하십시오.

오버라이드(override):

클래스 DefaultFormatter 내의 stringToValue

파라미터:

value - 변환 대상의 캐릭터 라인

반환값:

텍스트의 객체 표현

예외:

ParseException - 변환으로 에러가 발생했을 경우

관련 항목:

setValueContainsLiteralCharacters(boolean)

valueToString

public String  valueToString(Object  value)
                     throws ParseException 

마스크에 근거한 Object value String 표현을 리턴합니다. 리터럴의 취급 방법의자세한 내용은 setValueContainsLiteralCharacters(boolean)를 참조하십시오.

오버라이드(override):

클래스 DefaultFormatter 내의 valueToString

파라미터:

value - 변환 대상의 값

반환값:

치의 캐릭터 라인 표현

예외:

ParseException - 변환으로 에러가 발생했을 경우

관련 항목:

setValueContainsLiteralCharacters(boolean)

install

public void install(JFormattedTextField  ftf)

DefaultFormatter를 특정의 JFormattedTextField에 인스톨 합니다. 이것에 의해 valueToString가 불려가, 현재의 값이 JFormattedTextField로 부터 String에 변환됩니다. 다음에 getActions로 부터의 Action, getDocumentFilter로 부터 리턴된 DocumentFilter, getNavigationFilter로 부터 리턴된 NavigationFilter가 JFormattedTextField에 인스톨 됩니다.

보통, 서브 클래스에서의 오버라이드(override)가 필요하게 되는 것은, JFormattedTextField에 추가 리스너를 인스톨 하는 경우만입니다.

현재의 값을 캐릭터 라인으로 변환할 때 ParseException가 발생했을 경우는 텍스트로서 비어있는 캐릭터 라인이 설정되어JFormattedTextField에 부정한 상태를 나타내는 값이 설정됩니다.

이것은 public 메서드입니다만, 일반적으로 JFormattedTextField 서브 클래스에 대해서만 유효합니다. 값이 변경되는지, 내부 상태가 변경되는 경우, JFormattedTextField에 의해 이 메서드가 호출됩니다.

오버라이드(override):

클래스 DefaultFormatter 내의 install

파라미터:

ftf - 서식 설정용의 JformattedTextField. null인 경우는 현재의 JFormattedTextField 로부터의 언인스톨을 나타낸다