In .NET 2.0, there is a new
MaskedTextBox control that allows you to specify a mask that is used to restrict input characters and make the entered text conform to a specific format. One of the features of the control is that you can retrieve the text from it excluding the literal characters when the
TextMaskFormat property is set to
ExcludePromptAndLiterals. The problem with the unmasked text is that if you want to display it outside of the text box control, you need to manually put the mask characters back into it. You could just use a disabled
MaskedTextBox control, but the text is usually harder to read. You could make it read-only, but the text box can still be focused. It also does not solve the problem if you want to display the value as part of a larger string or in a message box. As such, I created the
The control is just a simple
Label control, with a few extra properties that let you specify the mask to apply when you set its text. In addition, it has a static overloaded
Format method that you can use to format text with a mask so that it can be used in other ways without the need of an actual control instance (i.e., format and display the text in a message box). The supplied demo contains the assembly, a help file, and a demo application. See the help file for details on installing the assembly in the Visual Studio .NET tool box. You can also extract the MaskedLabel.cs source file for use in your own projects or control libraries.
Using the Assembly in your Projects
The classes can be found in the assembly EWSoftware.MaskedLabelControl.dll. In order to use the classes, add a reference to it in your project. The help file contains details on how to do this if you need it. In the code modules that use classes from the
EWSoftware.MaskedLabelControl namespace, you will have to add a
using statement (
Imports in VB.NET) for the
To use the
MaskedLabel control, simply drag it from the toolbox, and drop it on your form. The following additional properties are available:
Mask - At a minimum, you need to set this property to define the mask used to format the text. The mask can be anything that the
MaskedTextBox control supports. If no mask is set or the text is not valid for the mask, the text is displayed in its unmasked form.
Culture - This can be set to specify the culture information used by the underlying masked text provider. The current culture is used if one is not specified.
IncludePrompt - If set to
true and the specified text does not completely fill the mask, the formatted text will be filled out to show the prompt character in the unused spaces. If set to
false (the default), the formatted text displays only as much as it has.
PromptChar - This can be set to specify the prompt character to display if the
IncludePrompt property is set to
true. The default is an underscore (_).
Once the mask is defined; setting the control's
Text property will get it to show the text with the mask applied. Reading the
Text property returns the formatted text. The following read-only properties can provide some information about the formatting process should you need it:
MaskedTextProvider - This returns a clone of the masked text provider object based on the control's current settings.
ResultHint - This returns the result hint for the last assignment to the
Text property. If the assigned text could not be properly formatted, this will contain a hint as to why not. Positive values indicate success. Negative values indicate failure.
HintPosition - This returns the result hint position for the last assignment to the
Text property. If the assigned text could not be properly formatted, this will contain the position of the first failure.
UnmaskedText - As its name implies, this returns a copy of the unmasked text that was last assigned to the
Format method allows you to format masked text outside of the control. There are four overloads for the method. The simplest one takes the format string and the unmasked text. Again, the mask can be anything that the
MaskedTextBox control supports. The other three take additional parameters for the prompt character, culture, and result hint information.
string formattedText = MaskedLabel.Format("000-00-0000",
string withPrompt = MaskedLabel.Format("000-00-0000",
string withCulture = MaskedLabel.Format("$0.00",
"123", '\x0', new CultureInfo("fr-FR"));
string badText = MaskedLabel.Format("00/00", "123456",
'\x0', null, out hint, out pos);
How it Works
MaskedTextBox control utilizes the
MaskedTextProvider to handle all of the format related properties and tasks. This makes it quite simple to utilize the same formatting in other controls such as the
MaskedLabel control. To use it, you construct a new instance, specifying the mask and an optional culture. Other properties can be used to set the prompt character and other such options. To obtain a formatted text value, you call its
Set method. This formats the text and returns result information such as whether or not the text was valid for the mask. Using the masked text provider's
ToString method returns the formatted text. Below is the
Format method that illustrates this process.
public static string Format(string mask, string text,
char promptChar, CultureInfo culture,
out MaskedTextResultHint hint, out int hintPosition)
if(text == null)
text = String.Empty;
if(culture == null)
culture = CultureInfo.CurrentCulture;
MaskedTextProvider provider =
new MaskedTextProvider(mask, culture);
if(promptChar != '\x0')
provider.PromptChar = promptChar;
provider.IncludePrompt = true;
provider.Set(text, out hintPosition, out hint);
if(hint > 0)
I have found one limitation with the
MaskedTextProvider. It always formats the text from left to right, filling in positions as it goes. As such, if the mask contains optional characters anywhere but at the end of the mask, you generally do not end up with the formatted value that you would expect. This is most easily shown with a format string such as "990.00". If you specify the text "123", you end up with "123." rather than "1.23". As such, the masked text provider works best when there are no optional characters or where they only appear at the end of the mask.
- 06/26/2006 - Initial release.
Eric Woodruff is an Analyst/Programmer for Spokane County, Washington where he helps develop and support various applications, mainly criminal justice systems, using Windows Forms (C#) and SQL Server as well as some ASP.NET applications.
He is also the author of various open source projects for .NET including:
The Sandcastle Help File Builder
- A front end and project management system that lets you build help file projects using Microsoft's Sandcastle documentation tools. It includes a standalone GUI and a package for Visual Studio integration.
Visual Studio Spell Checker
- A Visual Studio editor extension that checks the spelling of comments, strings, and plain text as you type or interactively with a tool window. This can be installed via the Visual Studio Gallery
Image Map Controls
- Windows Forms and web server controls that implement image maps.
- A complete set of classes that let you have access to all objects, properties, parameter types, and data types as defined by the vCard (RFC 2426), vCalendar, and iCalendar (RFC 2445) specifications. A recurrence engine is also provided that allows you to easily and reliably calculate occurrence dates and times for even the most complex recurrence patterns.
Windows Forms List Controls
- A set of extended .NET Windows Forms list controls. The controls include an auto-complete combo box, a multi-column combo box, a user control dropdown combo box, a radio button list, a check box list, a data navigator control, and a data list control (similar in nature to a continuous details section in Microsoft Access or the DataRepeater from VB6).
For more information see http://www.EWoodruff.us