javax.swing.text
클래스 MaskFormatter

java.lang.Object 
  |
  +--javax.swing.JFormattedTextField.AbstractFormatter 
        |
        +--javax.swing.text.DefaultFormatter 
              |
              +--javax.swing.text.MaskFormatter

모든 구현 인터페이스:

Cloneable , Serializable

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 "123-45__#가 됩니다. 캐릭터 위치 3 ( 「-」)으로 MaskFormatter 가 삽입 처리를 실시하면, 2 kr가 일어납니다.

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

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

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

경고: 이 클래스의 직렬화 된 오브젝트는 향후의 Swing 의 릴리스와는 호환성을 가지지 않습니다. 현재의 직렬화 서포트는 단기간의 운용이나, 같은 버젼의 Swing 를 실행하는 어플리케이션간의 RMI 에 적절하고 있습니다. 1.4 에서는 모든 JavaBeans^TM 의 장기 운용 서포트가, 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 를 건네준다 (디폴트)라고 하는 것은 유효한 캐릭터가 마스크나 무효인 캐릭터 에 의해서만 바인드 되고 있는 것을 나타냅니다.

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 가 슬로우 됩니다.

오버라이드(override):

클래스 DefaultFormatter 내의 stringToValue

반환값:

텍스트의 Object 표현

예외:

ParseException - 변환에 에러가 있는 경우

valueToString

public String  valueToString(Object  value)
                     throws ParseException 

마스크에 근거한 Object value 의 String 표현을 돌려줍니다.

오버라이드(override):

클래스 DefaultFormatter 내의 valueToString

파라미터:

value - 변환하는 값

반환값:

치의 String 표현

예외:

ParseException - 변환에 에러가 있는 경우

install

public void install(JFormattedTextField  ftf)

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

서브 클래스가 청취자를 JFormattedTextField 에 추가 인스톨 하는 경우는 통상, 이것을 오버라이드(override) 할 뿐입니다.

현재가를 String 로 변환할 때에 ParseException 가 슬로우 되는 경우, 텍스트는 하늘의 String 로 설정되어JFormattedTextField 는 무효인 상태로서 마크 됩니다.

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

오버라이드(override):

클래스 DefaultFormatter 내의 install

파라미터:

ftf - 서식 설정용의 JFormattedTextField. null 도 가능 (현행의 JFormattedTextField 의 언인스톨을 나타낸다)