Windows Controls: The Masked Text Box

The Masked Text Box

Description

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:

using System;
using System.Drawing;
using System.Windows.Forms;

public class Exercise : System.Windows.Forms.Form
{
    MaskedTextBox txtFunctional;

    public Exercise()
    {
        InitializeComponent();
    }

    void InitializeComponent()
    {
        txtFunctional = new MaskedTextBox();

        Controls.Add(txtFunctional);
    }
}

public class Program
{
    static int Main()
    {
        System.Windows.Forms.Application.Run(new Exercise());
        return 0;
    }
}

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:

public string Mask { get; set; }

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... This would open the Input Mask dialog box
  • 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 class Exercise : System.Windows.Forms.Form
{
    MaskedTextBox txtFunctional;

    public Exercise()
    {
        InitializeComponent();
    }

    void InitializeComponent()
    {
        txtFunctional = new MaskedTextBox();
        txtFunctional.Location = new Point(12, 12);
        
        txtFunctional.Mask = "999-000-0000";

        Text = "Mask Text Box";
        Controls.Add(txtFunctional);
    }
}

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, which is of type char:

public char PromptChar { get; set; }

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 masked text box, the user 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 class is equipped with a Boolean property named BeepOnError:

public bool BeepOnError { get; set; }

When this property is set to True, if the user enters an invalid character, the computer produces the beep sound:

public class Exercise : System.Windows.Forms.Form
{
    MaskedTextBox txtFunctional;

    public Exercise()
    {
        InitializeComponent();
    }

    void InitializeComponent()
    {
        txtFunctional = new MaskedTextBox();
        txtFunctional.Location = new Point(12, 12);
        txtFunctional.Mask = "999-000-0000";

        txtFunctional.BeepOnError = true;

        Text = "Mask Text Box";
        Controls.Add(txtFunctional);
    }
}

Also, if the user enters an invalid character in the control, the control fires a MaskInputRejected event, which is carried by a class named MaskInputRejectedEventHandler:

public event MaskInputRejectedEventHandler MaskInputRejected

You can (continuously) use this event to find out whenever the user enters a wrong character so you can provide assistance.

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:

public bool AllowPromptAsInput { get; set; }

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 class Exercise : System.Windows.Forms.Form
{
    MaskedTextBox txtFunctional;

    public Exercise()
    {
        InitializeComponent();
    }

    void InitializeComponent()
    {
        txtFunctional = new MaskedTextBox();
        txtFunctional.Location = new Point(12, 12);
        txtFunctional.Mask = "999-000-0000";
        txtFunctional.BeepOnError = true;

        txtFunctional.HidePromptOnLeave = true;

        Text = "Mask Text Box";
        Controls.Add(txtFunctional);
    }
}

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:

public MaskFormat CutCopyMaskFormat { get; set; }

Its members are: ExcludePromptAndLiterals, IncludeLiterals, IncludePrompt, and IncludePromptAndLiterals.