MaskedTextBox Tutorial: Windows Forms

MaskedTextBox accepts text input of a specific format.

We often require phone numbers to have their area code and also the correct number of digits. To solve this problem, we use the MaskedTextBox control in Windows Forms.

TextBox

Start. To get started, please add a MaskedTextBox control to your Windows Forms program by double-clicking on the icon in the toolbox. Next, try changing the properties of the MaskedTextBox by right-clicking on it and selecting properties.

Importantly, change the Mask property. You can find predefined masks for integer numbers, phone numbers, dates in various formats, Social Security Numbers, time in various formats, and zip codes.

Note: This tutorial shows the MaskedTextBox with the Social Security Number format specified.

Example program for MaskedTextBox: C#

using System.Windows.Forms;

namespace WindowsFormsApplication1
{
    public partial class Form1 : Form
    {
	public Form1()
	{
	    InitializeComponent();
	}

	private void maskedTextBox1_MaskInputRejected(object sender,
	    MaskInputRejectedEventArgs e)
	{
	    // Set the window title text
	    // ... to the MaskInputRejectedEventArgs information.
	    this.Text = "Error: " +
		e.RejectionHint.ToString() +
		"; position: " +
		e.Position.ToString();
	}
    }
}

MaskInputRejected. You can add this by double-clicking on the MaskedTextBox control. Here we change the window text to show the RejectionHint and the Position of the error. This clues in the user as to the nature of the error.

Validation. The MaskedTextBox can do more than simply ensure a format is followed: it can convert the input into a C# type for you as well. In this example, we set the format to the "Short date" mask pattern.

Then: We added the TypeValidationCompleted event handler by going to the event list in Visual Studio.

Example program 2 for MaskedTextBox: C#

using System;
using System.Windows.Forms;

namespace WindowsFormsApplication1
{
    public partial class Form1 : Form
    {
	public Form1()
	{
	    InitializeComponent();
	}

	private void maskedTextBox1_TypeValidationCompleted(object sender,
	    TypeValidationEventArgs e)
	{
	    // This event is raised when the enclosing window is closed.
	    // ... We show a MessageBox that details the DateTime.
	    DateTime value = (DateTime)e.ReturnValue;
	    MessageBox.Show("Validated: " + value.ToLongDateString());
	}
    }
}

To get the validated result, please access the ReturnValue property from the TypeValidationEventArgs. We need to cast this object. The TypeValidationCompleted event handler is triggered when the form is dismissed.

Properties. There are several more properties you can adjust on the MaskedTextBox control. Here we examine most of them in brief to give an overview of which ones might be useful to you. Many are rarely used.

Property

AsciiOnly: The AsciiOnly property enforces that every character entered not be an accented or Unicode-only character.

Tip: This is useful when you require strict data input, as many database systems do not need non-ASCII characters.

CutCopyMaskFormat. Users may want to copy the text from a MaskedTextBox to their clipboards. This property lets you adjust how the text will be copied. It specifies whether the separators are included in the copied text.

HidePromptOnLeave and HideSelection. These two boolean properties determine how the MaskedTextBox is adjusted when the user focuses another control in the form. You could hide some of the prompt characters when they are not needed.

PasswordChar and PromptChar. The MaskedTextBox lets you change the character that appears when a password is entered. It also allows you to change the prompt character. By default, the prompt character is an underscore "_".

UseSystemPasswordChar: Finally, you can use the system-defined password character for when your MaskedTextBox is a password box.

ResetOnPrompt and ResetOnSpace. These two properties are usability features of the MaskedTextBox control. When you have a mask, there will be some prompt characters such as the "/" or "_" values.

And: If your user types either of those characters, and the MaskedTextBox has one of those characters, this is considered valid input.

Summary. The MaskedTextBox control in Windows Forms enforces the range of input that is allowed into the text box. It is ideal for when you want to collect phone numbers, identification numbers, dates or times, or even simple integers.

Note: Implementing these same features is much harder if you use the plain TextBox.

Related Links