Input for WinForms | ComponentOne
Input Controls / MaskedTextBox
In This Topic
    MaskedTextBox
    In This Topic

    MaskedTextBox is an advanced textbox control which automatically validates the input entered by a user. When a MaskedTextBox is added to a form, it exists as a completely functional text box which includes a basic text input area and can be further customized with a mask. The desired mask can be set by using EditMask property of the C1MaskedTextBox class.

    Create MaskedTextBox Control
    Copy Code
    this.c1MaskedTextBox1 = new C1.Win.Input.C1MaskedTextBox();
    ((System.ComponentModel.ISupportInitialize)(this.c1MaskedTextBox1)).BeginInit();
    this.c1MaskedTextBox1.Location = new System.Drawing.Point(7, 26);
    this.c1MaskedTextBox1.Name = "c1MaskedTextBox1";
    this.c1MaskedTextBox1.Size = new System.Drawing.Size(100, 25);
    

    Mask Types

    You can apply different types of masks to the MaskedTextBox control by specifying the following placeholders to the EditMask property. Once the mask is applied, the input entered by a user will be validated and invalid characters will not be allowed in the control: 

    Placeholder Description
    # Digit placeholder permits a numeric character or a plus or minus sign in this position (entry optional)
    . Decimal placeholder. The actual character used is the one specified as the decimal placeholder in your international settings. This character is treated as a literal for masking purposes.
    , Thousands separator. The actual character used is the one specified as the thousands separator in your international settings. This character is treated as a literal for masking purposes.
    : Time separator. The actual character used is the one specified as the time separator in your international settings. This character is treated as a literal for masking purposes.
    / Date separator. The actual character used is the one specified as the date separator in your international settings. This character is treated as a literal for masking purposes.
    \ Treat the next character in the mask string as a literal. This allows you to include the #, &, A, … characters in the mask. This character is treated as a literal for masking purposes.
    & Character placeholder (entry required). Any character is permitted.
    > Convert all the characters that follow to uppercase.
    < Convert all the characters that follow to lowercase.
    ~ Turns off the previous < or >.
    ! Causes the optional characters that follow in the edit mask to display from right to left, rather than from left to right. So, blanks appear on the left.
    ^ Turns off the previous ! character. After ^, blanks appear on the right.
    A Alphanumeric character placeholder (entry required). For example: a – z, A – Z, or 0 – 9.
    a Alphanumeric character placeholder (entry optional).
    0 Digit placeholder (entry required). For example: 0 – 9.
    9 Digit placeholder (entry optional).
    C Character or space placeholder (entry optional). Any character is permitted.
    L Letter placeholder (entry required). For example: a – z or A – Z.
    ? Letter placeholder (entry optional).
    \n New line literal. It is applicable when Multiline property is set to True.
    " All characters in a string enclosed in double quotes are considered as literals.
    Literal All other symbols are displayed as literals; that is, as themselves.

    Apart from the above placeholders, regular expressions can also be defined in the MaskedTextBox. The following keywords can be defined in regular expressions:

    Keywords  Description
    \A Matches any upper case alphabet [A-Z].
    \a Matches any lower case alphabet [a-z].
    \D Matches any decimal digit [0-9].
    \W Matches any word character. It is same as [a-z A-Z 0-9].
    \K Matches SBCS Katakana.
    \H Matches all SBCS characters.
    \ A Matches any upper case DBCS alphabet [A-Z].
    \ a Matches any lower case DBCS alphabet [a-z].
    \ D Matches any DBCS decimal digit [0-9].
    \ W Matches any DBCS word character. It is same as [a-z A-Z 0-9].
    \ K Matches all DBCS Katakana.
    \ J Matches all Hiragana.
    \ Z Matches all DBCS characters.
    \N Matches all SBCS big Katakana.
    \ N Matches all DBCS big Katakana.
    \ G Matches DBCS big Hiragana.
    \ T Matches surrogate character.
    [] Matches a character subset.
    [^] To express an exclude subset.
    - Defines contiguous character range.
    {} Specifies the number of times to match.
    * Specifies zero or more matches. It is the short expression for {0,}.
    + Specifies one or more matches. It is the short expression for {1,}.
    ? Specifies zero or one matches. It is the short expression for {0,1}.

    Mask Settings

    You can set the desired mask to MaskedTextBox control by setting the EditMask property to a mask string. On defining an edit mask, each character position in the control maps to either a special placeholder or a literal character. Literal characters, or literals, can give visual cues about the type of data being used. For example, the parenthesis surrounding the area code of a telephone number and dashes are literals: +1-(412)-123-4567.

    Although setting EditMask property is enough in simple cases, there is also a MaskInfo property containing sub-properties controlling various important aspects of masked input. A few of these sub-properties are CustomPlaceholders, PromptChar, RegexpEditMask, ErrorMessage, ShowLiterals etc.

    The phone number in the above image is represented with a mask where EditMask is set to "+0-(000)-000-0000"

    Set EditMask and MaskInfo
    Copy Code
    this.c1MaskedTextBox1.EditMask = "-(000)-000-0000";
    this.c1MaskedTextBox1.MaskInfo.PromptChar = '#';
    

    Further, you can also set the mask expression style using RegexpMaskType property of the MaskInfo class. The RegexpMaskType property uses the RegexpMaskType enumeration to determine the RegexpEditMask pattern processing and validation by accepting one of the following two values:

    The code snippet below shows how to set the RegexpMaskType property:

    C#
    Copy Code
    //set the Regexptype
    c1MaskedTextBox1.MaskInfo.RegexpMaskType = C1.Win.Input.Formating.RegexpMaskType.C1RegexpEditMask;
    //set the regex mask
    c1MaskedTextBox1.MaskInfo.RegexpEditMask = "[1-9]{1}[0-9]{9}";
    

    Back to Top

    Prompt Characters and Literals

    With the MaskedTextBox control, you can choose to show prompt characters and literals.

    The prompt character is the text that appears in the control (like # or _)and prompts the user to enter the text. You can choose to include prompt characters in the MaskedTextBox control by setting PromptChar property.

    Literals are non-mask characters that appear as themselves within the mask, like / or -. Literals always occupy a static position in the mask at run time, and cannot be moved or deleted by the user.

    For example, in the below image, the EditMask property is set to "000-0000" to define a zip code. Here, the mask character include the "0" element, the "-" is a literal and "#" is a prompt character.

    Add Literals and Prompt Characters
    Copy Code
    this.c1MaskedTextBox1.EditMask = "000-0000";
    this.c1MaskedTextBox1.MaskInfo.PromptChar = '#';
    

    Back to Top

    Placeholder Text

    The placeholder text provides hint about what value a user should enter in a control. MaskedTextBox lets you display a placeholder text in the control when nothing is selected or entered in it by using Placeholder property of the C1MaskedTextBox class. When you click within the control and enter text, the Placeholder text disappears.

    For example, the following image shows "Enter Phone Number" as a placeholder text in the MaskedtextBox control which hints the user to enter a phone number. 

    Set Placeholder text
    Copy Code
    this.c1MaskedTextBox1.Placeholder = "Enter Phone Number";
    

    Back to Top

    Password

    User can set a password of desired length and characters in a MaskedTextBox control and can use UseSystemPasswordChar property which ensures that the system-supplied password character is used.

    Set Password in MaskedTextbox
    Copy Code
    this.c1MaskedTextBox4.UseSystemPasswordChar = true;
    this.c1MaskedTextBox4.MaskInfo.EditMask = "AAAAAAAAaaaa";
    

    Back to Top

    Maximum Character Length

    You can limit the number of characters which can be entered in the control by specifying the desired number of characters in the EditMask property. For example, the below image shows Zip code of an area where maximum limit is 7 digits.

    Set Maximum Character Limit
    Copy Code
    this.c1MaskedTextBox1.EditMask = "000-0000";
    

    Back to Top

    Display and Edit Format

    MaskedTextBox allows you to specify two different formats, one for display (when the control is read-only or is not in the edit mode), and another for edit mode. These two formatting modes are governed by the DisplayFormat and EditFormat properties.

     

    Set Display and Edit Format
    Copy Code
    this.c1MaskedTextBox1.DisplayFormat.FormatType = FormatType.LongDate;
    this.c1MaskedTextBox3.EditFormat.FormatType = FormatType.ShortDate;
    

    Back to Top


    Multiline MaskedTextBox

    A MaskedTextBox can be converted into a multiline MaskedTextbox by using the Multiline property. This is particularly useful in cases where a considerable amount of data needs to be entered in the textbox, like an address or a customized choice.

     

    Set Multiline maskedTextBox
    Copy Code
    this.c1MaskedTextBox1.Multiline = true;
    

    Back to Top