Home

Windows Control: The Masked Text Box

 

Introduction

The regular text box, also referred to as the edit control in Microsoft Windows (Win32), allows the user to enter any type of string in the control. As we saw in the previous sections, that control can also be changed into a multi-line memo control and allow you to create a type of Notepad application. In some cases, you may want to exercise more control on what the user can enter in a text box. For example, if you provide a text box for a date, the user can still enter a person's name. If you create a text box for a telephone number, the user may instead enter somebody's salary. To assist the user with entering a specific value into a text box, the .NET Framework provides the masked text box.

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.

Creating a Masked Text Box

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.

Characteristics of the Masked Text Box

 

Introduction

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.

The Mask

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
     
    Mask
  • 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...
       
      Mask
    • On the form, click the control, click the arrow button on it, and click Edit Mask...
       
      Mask

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

Input Mask

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:

Character Used For Placeholder Rule
0 Digit Any single digit: 0, 1, 2, 3, 4, 5, 6, 7, 8, or 9.
9 Digit or Empty Space Any single digit can be entered or an empty space can be left.
# Digit or Empty Space Any single digit, a "+" or a "-" sign can be entered, or an empty space can be left.
L Letter Any letter in either uppercase or lowercase MUST be entered and no empty space should be left. Digits and other non-literals are not allowed.
? Letter Any letter in either uppercase or lowercase can be entered or an empty space can be left. Digits and other non-literals are not allowed.
& Character Any letter, digit, or symbol, or empty space can be used. If the AsciiOnly property is True, this placeholder follows the ? behavior.
C Character Any letter, digit, or symbol, or empty space can be used. If the AsciiOnly property is True, this placeholder follows the & behavior.
A or a Letters and Digits A letter (lowercase and uppercase), a digit, or an empty space is allowed. No special characters. If the AsciiOnly property is True, only a letter is allowed.
> Uppercase Converter A letter in lowercase entered in this placeholder, and any letter in lowercase entered on the right side of this placeholder until the next < or I character, will be converted to uppercase. If the letter is entered in uppercase, nothing would happen.
< Lowercase Converter A letter in uppercase entered in this placeholder, and any letter in uppercase entered on the right side of this placeholder until the next < or I character, will be converted to lowercase. If the letter is entered in lowercase, nothing would happen.
| Conversion Remover Removes the < or > rule set on the left side of this placeholder. This means that, in this placeholder and others on the right side, letters will not be converted but will be kept "as is"
. Decimal Symbol The decimal symbol must be used.
, Thousands Separator The character for the thousands separator, which is the comma in US English, must be used.
: Time Separator The character used to separate the sections of a time value, which is ":" in US English, must be used.
/ Date Separator The character used to separate the sections of a date value, which is "/" in US English, must be used.
$ Currency Symbol The currency symbol, which is $ is US and Canada, will be used
\ Escape Sequence Makes the character follow the escape sequence rules.
  Any Other Character Except for the characters reviewed above, all other characters are kept "as is".

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:

The Placeholder Character

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.

Entering the Wrong Character

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

Allowing the Placeholder Character for Input

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.

Hiding the Placeholder When Focus is Lost

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

Keeping the Format on Cut and Copy

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.

 

Home Copyright © 2008-2012 FunctionX