MaskedTextBox.Mask Property (System.Windows.Forms)

Switch View

Mask Property

Collapse All

Language Filter

This page is specific to

Microsoft Visual Studio 2005/.NET Framework 2.0

Other versions are also available for the following:

.NET Framework Class Library

MaskedTextBox.Mask Property

Note: This property is new in the .NET Framework version 2.0.

Gets or sets the input mask to use at run time.

Namespace: System.Windows.Forms
Assembly: System.Windows.Forms (in system.windows.forms.dll)

Syntax

Visual Basic (Declaration)

<LocalizableAttribute(True)> _
Public Property Mask As String

Visual Basic (Usage)

Dim instance As MaskedTextBox
Dim value As String

value = instance.Mask

instance.Mask = value

[LocalizableAttribute(true)] 
public string Mask { get; set; }

C++

[LocalizableAttribute(true)] 
public:
property String^ Mask {
    String^ get ();
    void set (String^ value);
}

/** @property */
public String get_Mask ()

/** @property */
public void set_Mask (String value)

JScript

public function get Mask () : String

public function set Mask (value : String)

Property Value

A String representing the current mask. The default value is the empty string which allows any input.

Exceptions

Exception type	Condition
ArgumentException	The string supplied to the Mask property is not a valid mask. Invalid masks include masks containing non-printable characters.

Remarks

Mask is the default property for the MaskedTextBox class.

Mask must be a string composed of one or more of the masking elements, as shown in the following table. The masking language used by MaskedTextBox is defined by its associated MaskedTextProvider. The standard provider specifies a masking language based upon the one used by the Masked Edit control in Visual Basic 6.0, and should be very familiar to users migrating from that platform.

Masking element	Description
0	Digit, required. This element will accept any single digit between 0 and 9.
9	Digit or space, optional.
#	Digit or space, optional. If this position is blank in the mask, it will be rendered as a space in the Text property. Plus (+) and minus (-) signs are allowed.
L	Letter, required. Restricts input to the ASCII letters a-z and A-Z. This mask element is equivalent to [a-zA-Z] in regular expressions.
?	Letter, optional. Restricts input to the ASCII letters a-z and A-Z. This mask element is equivalent to [a-zA-Z]? in regular expressions.
&	Character, required. If the AsciiOnly property is set to true, this element behaves like the "L" element.
C	Character, optional. Any non-control character. If the AsciiOnly property is set to true, this element behaves like the "?" element.
A	Alphanumeric, optional. If the AsciiOnly property is set to true, the only characters it will accept are the ASCII letters a-z and A-Z.
a	Alphanumeric, optional. If the AsciiOnly property is set to true, the only characters it will accept are the ASCII letters a-z and A-Z.
.	Decimal placeholder. The actual display character used will be the decimal symbol appropriate to the format provider, as determined by the control's FormatProvider property.
,	Thousands placeholder. The actual display character used will be the thousands placeholder appropriate to the format provider, as determined by the control's FormatProvider property.
:	Time separator. The actual display character used will be the time symbol appropriate to the format provider, as determined by the control's FormatProvider property.
/	Date separator. The actual display character used will be the date symbol appropriate to the format provider, as determined by the control's FormatProvider property.
$	Currency symbol. The actual character displayed will be the currency symbol appropriate to the format provider, as determined by the control's FormatProvider property.
<	Shift down. Converts all characters that follow to lowercase.
>	Shift up. Converts all characters that follow to uppercase.
\|	Disable a previous shift up or shift down.
\	Escape. Escapes a mask character, turning it into a literal. "\\" is the escape sequence for a backslash.
All other characters	Literals. All non-mask elements will appear as themselves within MaskedTextBox. Literals always occupy a static position in the mask at run time, and cannot be moved or deleted by the user.

If you change a mask when MaskedTextBox already contains user input filtered by a previous mask, MaskedTextBox will attempt to migrate that input into the new mask definition. If it fails, it will clear the existing input. Assigning a zero-length string as the mask will preserve any existing data in the control. When used with a zero-length mask, MaskedTextBox behaves like a single-line TextBox control.

The decimal (.), thousandths (,), time (:), date (/), and currency ($) symbols default to displaying those symbols as defined by the application's culture. You can force them to display symbols for another culture by using the FormatProvider property.

Character insertion into the mask at run time is controlled by the InsertKeyMode property. Users can navigate through the mask by using the left and right arrow keys or the mouse cursor, and can skip optional positions in the mask by entering a space.

Important:
MaskedTextBox supports all Unicode characters except for surrogates and vertically combined characters.

The following table shows example masks.

Mask	Behavior
`00/00/0000`	A date (day, numeric month, year) in international date format. The "/" character is a logical date separator, and will appear to the user as the date separator appropriate to the application's current culture.
`00->L<LL-0000`	A date (day, month abbreviation, and year) in United States format in which the three-letter month abbreviation is displayed with an initial uppercase letter followed by two lowercase letters.
`(999)-000-0000`	United States phone number, area code optional. If users do not want to enter the optional characters, they can either enter spaces or place the mouse pointer directly at the position in the mask represented by the first 0.
`$999,999.00`	A currency value in the range of 0 to 999999. The currency, thousandth, and decimal characters will be replaced at run time with their culture-specific equivalents.

Platforms

Windows 98, Windows 2000 SP4, Windows CE, Windows Millennium Edition, Windows Mobile for Pocket PC, Windows Mobile for Smartphone, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see System Requirements.

Version Information

.NET Framework

Supported in: 2.0

Reference

MaskedTextBox Class
MaskedTextBox Members
System.Windows.Forms Namespace
Text
MaskFull
MaskCompleted
MaskChanged
MaskedTextProvider