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)

일반적으로, 문자는 하나의 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'가 됩니다. 플레이스홀더 캐릭터 라인은, 처음으로 서식 설정을 실시할 때 마셔 사용됩니다. 2 번째 이후의 서식 설정시에는, 플레이스홀더 문자만이 사용됩니다.

유효한 문자만을 허가하도록(듯이) MaskFormatter 가 설정되어 있는 경우 (setAllowsInvalid(false)), 리터럴 캐릭터 라인은 편집시에 필요에 따라서 스킵 됩니다. MaskFormatter 의 마스크가 "###-####" 로, 현재의 값이 "555-1212" 라고 합니다. 오른쪽 커서 키를 사용해 필드를 안내해 나가면(자), 다음과 같은 결과를 얻을 수 있습니다 (| 는 caret 위치).

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

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

편집시도 같은 동작을 얻을 수 있습니다. 전술의 예의 MaskFormatter 에 캐릭터 라인 '123-45'와 '12345'를 삽입해 보겠습니다. 어느 쪽의 경우도, 결과는 같은 캐릭터 라인 '123-45__'가 됩니다. MaskFormatter 가 문자 위치 3 ('-')으로 삽입을 실시하는 경우, 다음의 2개의 처리가 발생합니다.

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

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

디폴트에서는,MaskFormatter 는 덧쓰기 모드(replace mode)입니다. 이 경우, 새로운 문자를 입력했을 때에, 그 문자가 삽입되는 것이 아니라, 현재의 위치의 문자가 새로운 문자로 옮겨놓을 수 있습니다. 이 동작을 변경하려면 ,setOverwriteMode 메소드를 사용합니다.

경고: 이 클래스의 직렬화 된 객체는, 향후의 Swing 릴리스와 호환은 아니게 될 예정입니다. 현재의 직렬화의 지원는, 단기간의 운용이나, 같은 버젼의 Swing 를 실행하는 어플리케이션간의 RMI 에 적절하고 있습니다. JDK Version 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 가 throw 됩니다.

예외:

ParseException - 마스크에 유효한 마스크 문자가 없는 경우

메소드의 상세

setMask

public void setMask(String  mask)
             throws ParseException 

적정한 문자의 값을 지정하는 마스크를 설정합니다. mask 가 무효인 경우는,ParseException 를 throw 합니다.

예외:

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 를 돌려줍니다.

반환값:

치가 마스크를 완전하게 묻지 않은 경우의 서식 설정시에 사용하는 캐릭터 라인

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 를 throw 합니다. 리터럴 캐릭터 라인의 자세한 처리 방법에 대해서는,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 가 발생했을 경우는, 텍스트로서 빈 상태(empty)의 캐릭터 라인이 설정되어JFormattedTextField 에 부정한 상태를 나타내는 값이 설정됩니다.

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

오버라이드(override):

클래스 DefaultFormatter 내의 install

파라미터:

ftf - 포맷 대상의 JformattedTextField. null 의 경우는, 현재의 JFormattedTextField 로부터의 언인스톨을 나타낸다