[21기 유미영] MaskedTextBox Class

[21기 유미영]

MaskedTextBox기술문서	작성일 : 2011-04-09
	작성자 : 유미영
주제 : MaskedTextBox Class

MaskedTextBox Class

마스크를 사용하여 올바른 사용자 입력과 잘못된 사용자 입력을 구별

상속 계층 구조

System.Object
  System.MarshalByRefObject
    System.ComponentModel.Component
      System.Windows.Forms.Control
        System.Windows.Forms.TextBoxBase
          System.Windows.Forms.MaskedTextBox

네임스페이스 : System.Windows.Forms

어셈블리 : System.Windows.Forms(System.Windows.Forms.dll)

MaskedTextBox 생성자
MaskedTextBox()	기본값을 사용하여 MaskedTextBox 클래스의 새 인스턴스를 초기화
MaskedTextBox      (MaskedTextProvider)	지정된 사용자 지정 마스크 언어 공급자를 사용하여 MaskedTextBox클래스의 새 인스턴스를 초기화
MaskedTextBox(String)	지정된 입력 마스크를 사용하여 MaskedTextBox클래스의 새 인스턴스를 초기화

MaskedTextBox() 생성자는 MaskedTextProvider 속성을 “<>” 문자열로 표현되는 null마스크로 설정한다. null마스크는 모든 문자 조합을 입력으로 받아들인다.

매개변수 maskedTextProvider

MaskedTextBox에서 사용되는 마스킹 언어를 정의한다. 이 언어는 마스크를 구문 분석하고 사용자 입력이 현재 마스크 위치에 맞는지 여부를 확인하는 역할을 한다.

형식 : System.ComponentModel.MaskedTextProvider

MaskedTextprovider 클래스에서 파생된 사용자 지정 마스크 언어 공급자이다.

예외 : ArgumentNullExceprion [maskedTextProvider는 null입니다.]

기본 마스킹 언어를 사용하고 사용자가 직접 입력 마스크를 제공할 경우에는 이 생성자를 사용할 필요가 없다. 대신 MaskedTextBox(String)생성자를 사용하거나, 기본 생성자를 사용한 다음 Mask속성을 설정할 수 있다.

MaskedTextBox 속성
AllowPromptAsInput	사용자가 PromptChar를 올바른 데이터로 입력할 수 있는지 여부를 나타내는 값을 가져오거나 설정
FormatProvider	형식 유효성 검사를 수행할 때 사용할 IFormatProvider를 가져오거나 설정
Mask	런타임에 사용할 입력 마스크를 가져오거나 설정
MaskedTextProvider	마스킹된 텍스트 상자 컨트롤의 이 인스턴스와 관련된 마스크 공급자의 복제본을 가져옴 [MaskedTextProvider는 직접 설정할 수 없다. 그러나 Mask, AllowPromptAsInput, AsciiOnly, Culture와 같은 MaskedTextBox의 일부 속성을 설정하면 내부적으로 MaskedTextProvider가 새로 생성될 수가 있다.]
PasswordChar	사용자 입력 대신 표시되는 문자를 가져오거나 설정
PromptChar	MaskedTextBox에 사용자 입력이없음을 나타내는 데 사용되는 문자를 가져오거나 설정
MaskCompleted	입력 마스크에 모든 필수 입력 사항이 입력되었는지 여부를 나타내는 값을 가져옴
MaskFull	입력 마스크에 모든 필수 및 선택적 입력 사항이 입력되었는지 여부를 나타내는 값을 가져옴

AllowPromptAsInput , PromptChar

사용자에게 입력하라고 요청하는 데 사용되는 문자(PromptChar)을 입력할 수 있으면 true, 그렇지 않으면 false (기본값 = true)

 

Mask

예제 마스크

마스크	동작
00/00/0000	국제 날짜 형식의 날짜(일,숫자 월,연도)이다. “/”문자는 논리적으로 날짜 구분 기호이며 사용자에게는 응용 프로그램의 현재 culture에 맞는 날짜 구분 기호로 표시된다.
00->L<LL-0000	미국식 날짜(일,월 약어 및 연도)표기 형식에서 세 문자로 된 월 약어의 첫 문자는 대문자로, 나머지 두 문자는 소문자로 입력한다.
(999)-000-0000	미국 전화 번호로 지역 번호는 선택사항이다.선택적 문자를 입력하지 않으려면 공백을 입력하거나 마스크에서 첫 번째 0으로 표현되는 위치에 마우스 포인터를 직접 놓는다.
$999,999.00	0-999999 범위의 통화 값이다. 통화,1/1000 및 소수 문자는 런타임에서 해당 문화권 별 같은 값으로 변경된다.

private void Form1_Load(object sender, EventArgs e)

       {

            masktxtbox.Mask = "00/00/0000";     //날짜 초기화 

       }

    

PasswordChar

암호 문자로 사용되는 Char값

masktxtbox.Mask = "00/00/0000";    masktxtbox.PasswordChar = '●';

MaskedTextProvider, MaskCompleted , MaskFull

MaskedTextBox에 데이터를 다 입력하게 되면 MaskCompleted가 false에서 true로 바뀌고,MaskFull도 true로 변하게된다.

MaskedTextProvider에는 입력한 데이터가 들어간다.

MaskedTextBox 이벤트
MaskInputRejected	사용자 입력 또는 할당된 문자가 입력 마스크의 해당 서식 요소와 일치하지 않으면 발생
TypeVal‎idationCompleted	MaskedTextBox에서 ValidatingType 속성을 사용하여 현재 값의 구문 분석을 완료하면 발생

TypeVal‎idationCompleted

r  사용자 정의 유효성 검사를 한다. 이 속성이 null이 아니면 다음과 같은 일련의 이벤트가 발생

[1] 다음 중 하나가 발생하면 유효성 검사 시퀀스가 시작된다.

MaskedTextBox 컨트롤이 포커스를 잃는 경우

Text 속성이 검색되는 경우

ValidateText 메서드가 호출된다.

[2] 이러한 이벤트 결과, ValidatingType 속성을 사용하여 지정된 형식의 Parse 메서드가 호출됨

Parse는 형식화된 입력 문자열의 대상 형식으로 전환을 담당하며, 변환이 성공하면 유효성 검사가 성공한 것이다.

[3] Parse가 반환된 후 TypeVal‎idationCompleted 이벤트가 발생한다. 이 이벤트에 대한 이벤트 처리기는 가장 일반적으로 형식 또는 마스크 유효성 검사 처리를 수행하도록 구현된다. 이 처리기는 변환에 대한 정보가 포함된 TypeVal‎idationEbentArgs 매개 변수를 받는다.

[4] TypeVal‎idationCompleted이벤트에 대한 이벤트 처리기가 반환된 후 표준 유효성 검사 이벤트인 Validationg이 발생한다. 이벤트 취소를 포함한 표준 유효성 검사를 수행하도록 처리기를 구현할 수 있다.

[5] 3단계에서 이벤트가 취소되지 않으면 표준 컨트롤 유효성 검사 이벤트인 Validated가 발생한다.

TypeVal‎idationCompleted 이벤트 처리기에서 Cancel 속성이 true로 설정되어 있으면 이후의 Calidating이벤트가 해당 버전의 CancelEventArgs.Cancel 속성을 다시 false로 설정하지 않는 한 이벤트가 취소되고 MaskedTextBox 컨트롤에 포커스가 유지된다.

아래 예제는 사용자 입력을 올바른 DataTime 개체로 구문 분석하려고 시도한다.

실패하면 TypeVal‎idationCompleted 이벤트 처리기가 사용자에게 오류 메시지를 표시한다.

값이 올바르다면 입력한 날짜가 오늘 이전의 날짜가 아닌지 확인한다.

ToolTip tooltip = new ToolTip();

        private void Form1_Load(object sender, EventArgs e)

        {

            masktxtbox.Mask = "00/00/0000";

            masktxtbox.ValidatingType = typeof(System.DateTime);

           masktxtbox.KeyDown += new KeyEventHandler(masktxtbox_KeyDown);

            masktxtbox.TypeVal‎idationCompleted +=new TypeVal‎idationEventHandler(masktxtbox_TypeVal‎idationCompleted);

            tooltip.IsBalloon = true;

        }

        void masktxtbox_KeyDown(object sender, KeyEventArgs e)

        {

            tooltip.Hide(masktxtbox);

        }

     void masktxtbox_TypeVal‎idationCompleted(object sender, TypeVal‎idationEventArgs e)

        {

            if (!e.IsValidInput)

            {

                tooltip.ToolTipTitle = "Invalid Date";

                tooltip.Show("The data you supplied must be a valid date in the format mm/dd/yyyy.", masktxtbox, 0, -20, 5000);

            }

            else

            {

                DateTime userDate = (DateTime)e.ReturnValue;

                if (userDate < DateTime.Now)

                {

                    tooltip.ToolTipTitle = "Invalid Date";

                    tooltip.Show("The date in this field must be greater than today's date.", masktxtbox, 0, -20, 5000);

                    e.Cancel = true;

                }

            }

        }

MaskeInputRejected

사용자 입력 또는 할당된 문자가 입력 마스크의 해당 서식 요소와 일치하지 않으면 발생

MaskedTextBox의 기본 이벤트이다.

아래 예제는 날짜를 받아들이도록 MaskedTextBox를 초기화하고, MaskInputRejected 이벤트를 사용하여 사용자에게 잘못된 입력에 대해 경고를 한다.

private void Form1_Load(object sender, EventArgs e)

        {

            masktxtbox.Mask = "00/00/0000";     //날짜 초기화

       masktxtbox.MaskInputRejected += new MaskInputRejectedEventHandler

(masktxtbox_MaskInputRejected);

        }

        ToolTip tooltip = new ToolTip();

     void masktxtbox_MaskInputRejected(object sender, MaskInputRejectedEventArgs e)

     {

          if (masktxtbox.MaskFull)

          {

              tooltip.ToolTipTitle = "Input Rejected : Too Much Data";

             tooltip.Show("You cannot enter any more data inito the date field.Delete some characters in order to insert more data.", masktxtbox, 0, -20, 5000);

           }

          else if (e.Position == masktxtbox.Mask.Length)

          {

              tooltip.ToolTipTitle = "Input Rejected - End of Rield";

             tooltip.Show("You cannot add extra charancters to the end of this date field", masktxtbox, 0, -20, 5000);

           }

          else

          {

              tooltip.ToolTipTitle = "Input Rejected";

              tooltip.Show("You can onlt add numeric characters (0-9) into this date field.", masktxtbox, 0, -20, 5000);

           }

        }

설명

MaskedTextBox 클래스는 사용자 입력을 받아들이거나 거부하는 선언적 구문을 지원하는 향상된 TextBox 컨트롤이다.

Mask속성을 사용하면 응용 프로그램에 사용자 지정 유효성 검사 논리를 작성하지 않고 다음과 같은 입력 사항을 지정할 수 있다.

n  필수 입력 문자 (Required input characters)

n  선택적 입력 문자(Optional input characters)

n  마스크에서 지정된 위치에 필요한 입력 형식

(예 : 숫자, 영문자 또는 영숫자)

n  MaskedTextBox에 직접 나타나야 하는 마스크 리터럴 또는 문자

(예 : 전화 번호의 하이픈(-) 또는 가격의 통화 기호

n  입력 문자에 대한 특수 처리

(예 : 영문자를 대문자로 변환)

런타임에 maskedTextBox 컨트롤이 표시되면 마스크가 일련의 프롬프트 문자와 선택적 리터럴 문자로 표현이된다. 필수 입력 또는 선택적 입력을 나타내는 편집 가능한 각 마스크 위치는 단일 프롬프트 문자로 표시된다.

예를 들어, 숫자 기호(#)는 대개 숫자 입력을 위한 자리 표시자로 사용됩니다. PromptChar 속성을 사용하여 사용자 지정 프롬프트 문자를 지정할 수 있습니다. HidePromptOnLeave 속성은 컨트롤이 입력 포커스를 잃었을 때 사용자가 프롬프트 문자를 볼 수 있는지 여부를 결정한다.

사용자가 마스킹된 텍스트 상자에 입력하면 순차적으로 각 프롬프트 문자가 올바른 입력 문자로 바뀝니다. 잘못된 입력 문자를 입력하면 프롬프트 문자가 바뀌지 않고 대신 경고음이 울리며MaskInputRejected 이벤트가 발생한다. 이 이벤트를 처리하여 사용자 지정 오류 논리를 제공할 수 있다.

현재 삽입 지점이 리터럴 문자이면 사용자는 다음과 같은 옵션 중 선택할 수 있다.

·         프롬프트 문자 이외의 다른 문자를 입력하면 리터럴을 자동으로 건너뛰고 다음 프롬프트 문자로 표현되는 편집 가능한 다음 위치에 입력 문자를 적용한다.

·         프롬프트 문자가 입력되고 AllowPromptAsInput 속성이 true이면 프롬프트 문자 위에 입력 문자를 겹쳐쓰고 삽입 지점을 마스크의 다음 위치로 이동한다.

·         다른 경우와 마찬가지로 화살표 키를 사용하여 이전 또는 다음 위치로 이동할 수 있다.

MaskFull 속성을 사용하여 사용자가 필요한 내용을 모두 입력했는지 여부를 확인할 수 있다. Text 속성은 항상 마스크와 TextMaskFormat 속성에 따라 서식이 지정된 사용자 입력을 검색한다.

MaskedTextBox 컨트롤은 실제로 MaskedTextProvider 속성에서 지정한 System.ComponentModel.MaskedTextProvider 클래스에서 모든 마스크를 처리하도록 한다. 이 표준 공급자는 서로게이트 및 수직으로 결합된 문자를 제외한 모든 유니코드 문자를 지원한다. 그러나 AsciiOnly 속성을 사용하면 입력을 a-z, A-Z 및 0-9의 문자 집합으로 제한할 수 있다.

마스크를 사용하더라도 사용자 입력이 반드시 지정된 형식의 올바른 값을 나타낸다고 볼 수는 없습니다. 예를 들어, -9를 나이에 대한 값으로 입력할 수 있다. 해당 값 형식의 인스턴스를 ValidatingType 속성에 할당하여 사용자 입력이 올바른 값을 나타내는지 확인할 수 있다. TypeVal‎idationCompleted 이벤트를 모니터링하여 MaskedTextBox에 잘못된 값이 들어 있을 때 사용자가 이 텍스트 상자에서 포커스를 제거하는지 여부를 확인할 수 있다. 형식 유효성 검사가 성공하면 TypeVal‎idationEventArgs 매개 변수의 ReturnValue 속성을 통해 값을 나타내는 개체를 사용할 수 있게 된다.

TextBox 컨트롤과 마찬가지로 MaskedTextBox에서 몇 가지 일반적인 바로 가기 키를 사용할 수 없다. 특히 Ctrl+R(텍스트 오른쪽 맞춤), Ctrl+L(텍스트 왼쪽 맞춤) 및 Ctrl+C(텍스트 가운데 맞춤)가 작동하지 않는다.

참고문헌

MSDN

[MaskTextBox Class]     : Click

[MaskTextBox Property] :  Click

[MaskTextBox Event ]    : Click