Introduction

The masked text box allows you to configure one or more placeholders in the field of the control so that the control can accept some characters, must reject some characters, and/or can display some other characters you will have put so the user cannot delete them.

To create a masked text box, from the Common Controls section of the Toolbox, you can click MaskedTextBox and click the form. To programmatically create a masked text box, declare a variable of type MaskedTextBox, use the New operator to initialize it, and add it to the Controls collection of its container. Here is an example:

Imports System.Drawing
Imports System.Windows.Forms

Module Exercise

    Public Class Starter
        Inherits Form

        Private txtHomePhone As MaskedTextBox

        Dim components As System.ComponentModel.Container

        Public Sub New()
            InitializeComponent()
        End Sub

        Public Sub InitializeComponent()

            txtHomePhone = New MaskedTextBox
            
            Controls.Add(txtHomePhone)

        End Sub

    End Class

    Function Main() As Integer

        Dim frmStart As Starter = New Starter

        Application.Run(frmStart)

        Return 0
    End Function

End Module

The masked text box uses the same common characteristics of other visual control: location, size, etc.

The masked text box uses the same common characteristics of other visual control: name, location, size, background color, border size, anchoring, docking, font, etc. Like the regular text box, the MaskedTextBox class is derived from TextBoxBase that provides its fundamental properties. This means that with the masked text box, you can cut or copy text from it, you can paste text to it, you can measure the length of its text, you can select some part of its text from a specific position to another, or you can select all of its text. Like the regular text box, the masked text box uses the AsciiOnly property, which indicates whether the control should accept or allow only ASCII characters.

The primary reason for using a masked text box is to control short lengths of text entered into it. For this reason, you should not consider some of the multi-line characteristics of a regular text box: word wrapping, scroll bars, the ability to use the Tab key inside the control, etc.

Probably the most important property of a masked text box, which sets it apart from the (traditional) text box control, is its ability to control what the user can and cannot enter in the text side. To visually configure this text, the MaskedTextBox class is equipped with a property named Mask. There are two main ways you can configure it:

• If you already know the mask you want to use, access the Properties window for the control and, in the Mask field, type the right formula
   
  
• If you do not know or are not sure, in the Properties window for the control
  • Click Mask and click its ellipsis button
  • On the form, click the control and, under the Properties window, click Set Mask...
     
    
  • On the form, click the control, click the arrow button on it, and click Edit Mask...
     
    

Any of these actions would open the Input Mask dialog box:

The Input Mask dialog box provides some of the most regularly used masks in Windows and database applications (the contents of the Input Mask dialog box depends on the language settings of the computer on which you are using Microsoft Visual Studio. For example, the above Input Box is adapted for US English with the US Social Security Number and telephone format). To use an existing mask, you can click it and click OK.

If none of the masks in the list suits you, you can create your own. In the Input Mask dialog box, you can click <Custom>, click the masked text box, create the format, and click OK. Or, in the Properties window for the masked text box, you can click the Mask field and create your mask. To create a mask, you use some characters and combine them as you see fit. The characters you can use are:

To programmatically specify a mask, create it in a string and assign that string to the Mask property. Here is an example:

Public Sub InitializeComponent()

            txtHomePhone = New MaskedTextBox
            txtHomePhone.Location = New Point(20, 20)

            txtHomePhone.Mask = "999-000-0000"
            
            Controls.Add(txtHomePhone)

End Sub

This would produce:

When you create a mask, to indicate a placeholder for a letter, a digit, or a symbol, the control uses a specific character. The default character is the underscore. If you want, you can use a different character. To support this, the MaskedTextBox class is equipped with the PromptChar property. To change it visually, access the Properties window for the control, click PromptChar and type the desired character. To programmatically specify the character of the placeholders, assign a string to the PromptChar property.

When using the control, the user must must know the rules to follow based on the mask in the control: dates, telephone numbers, etc. The user must also enter only the allowed characters. If the user enters an invalid character, you can make the computer produce a sound (a beep). To assist you with this, the MaskedTextBox is equipped with a Boolean property named BeepOnError. When this property is set to True, if the user enters an invalid character, the computer produces the beep sound:

Public Sub InitializeComponent()

            txtHomePhone = New MaskedTextBox
            txtHomePhone.Location = New Point(20, 20)
            txtHomePhone.Mask = "999-000-0000"

            txtHomePhone.BeepOnError = True

            Controls.Add(txtHomePhone)

End Sub

Also, if the user enters an invalid character in the control, the control fires a MaskInputRejected event. You can (continuously) use this event to find out whenever the user enters a wrong character so you can assist the user. Here is an example of implementing it:

Imports System.Drawing
Imports System.Windows.Forms

Module Exercise

    Public Class Starter
        Inherits Form

        Friend WithEvents txtHomePhone As MaskedTextBox

        Dim components As System.ComponentModel.Container

        Public Sub New()
            InitializeComponent()
        End Sub

        Public Sub InitializeComponent()

            txtHomePhone = New MaskedTextBox
            txtHomePhone.Location = New Point(20, 20)
            txtHomePhone.Mask = "999-000-0000"

            txtHomePhone.BeepOnError = True

            Controls.Add(txtHomePhone)

        End Sub

        Private Sub MaskedInputWasRejected(ByVal sender As Object, _
                                           ByVal e As MaskInputRejectedEventArgs) _
                                           Handles txtHomePhone.MaskInputRejected

            MsgBox("You entered an invalid character")

        End Sub
    End Class

    Function Main() As Integer

        Dim frmStart As Starter = New Starter

        Application.Run(frmStart)

        Return 0
    End Function

End Module

After creating the control, you can then use it in your application. When the control comes up, it usually shows its placeholders using a specific character. The most regularly used character is the underscore. Put in reverse, the presence of the underscore indicates a placeholder. If you skip a placeholder by pressing the Space bar, an underscore displays in the space you left. This rule also apples for all other characters we reviewed. In some cases, you may want to formally use the character in the placeholder. To illustrate this, consider that you have applied a mask as &&&&&&. When the control comes up, if Fe_ GT4, this would be considered as Fe GT4 (with an empty space where the _ was typed). In some cases, you may want the user to be able to enter the character of the placeholder so that Fe_ GT4 would produce Fe_ GT4. To assist you with this, the MaskedTextBox class is equipped with the AllowPromptAsInput Boolean property.

By default, when the control comes up, it uses some characters, such as _, to show its placeholder(s). This allows the user to know where a character is expected and the number of characters that are expected. After the user has used the control and pressed Tab or clicked another control, the masked text box may still show its placeholders. If you want, you can hide the placeholders when the control looses focus. To assist you with this, the MaskedTextBox class is equipped with a Boolean property named HidePromptOnLeave. The default value of this property is False, which indicates that the control would always show its placeholder(s). Otherwise, you can set this property to true to hide the placeholder character when the control loses focus. Here is an example:

Public Sub InitializeComponent()

            txtHomePhone = New MaskedTextBox
            txtHomePhone.Location = New Point(20, 20)
            txtHomePhone.Mask = "999-000-0000"
            txtHomePhone.BeepOnError = True

            txtHomePhone.HidePromptOnLeave = True

            Controls.Add(txtHomePhone)

End Sub

In some cases, the user can enter less than the number of placeholders in the control. Unlike the regular text box, the user cannot enter characters beyond the number of placeholders. As a class derived from the TextBoxBase class, the masked text box is equipped with a context menu that allows the user to cut, copy, and paste. When the user performs any of these operations, you may want to control whether the mask characters would be included in the cut, copied, or pasted text. To control this, the MaskedTextBox class is equipped with a property named CutCopyMaskFormat, which is based on the MaskFormat enumeration. Its members are: ExcludePromptAndLiterals, IncludeLiterals, IncludePrompt, and IncludePromptAndLiterals.