MaskedTextBox Class
Assembly: System.Windows.Forms (in system.windows.forms.dll)
'Declaration <ClassInterfaceAttribute(ClassInterfaceType.AutoDispatch)> _ <ComVisibleAttribute(True)> _ Public Class MaskedTextBox Inherits TextBoxBase 'Usage Dim instance As MaskedTextBox
/** @attribute ClassInterfaceAttribute(ClassInterfaceType.AutoDispatch) */ /** @attribute ComVisibleAttribute(true) */ public class MaskedTextBox extends TextBoxBase
ClassInterfaceAttribute(ClassInterfaceType.AutoDispatch) ComVisibleAttribute(true) public class MaskedTextBox extends TextBoxBase
The MaskedTextBox class is an enhanced TextBox control that supports a declarative syntax for accepting or rejecting user input. Using the Mask property, you can specify the following input without writing any custom validation logic in your application:
-
Required input characters.
-
Optional input characters.
-
The type of input expected at a given position in the mask; for example, a digit, or an alphabetic or alphanumeric character.
-
Mask literals, or characters that should appear directly in the MaskedTextBox; for example, the hyphens (-) in a phone number, or the currency symbol in a price.
-
Special processing for input characters; for example, to convert alphabetic characters to uppercase.
When a MaskedTextBox control is displayed at run time, it represents the mask as a series of prompt characters and optional literal characters. Each editable mask position, representing a required or optional input, is shown with a single prompt character. For example, the number sign (#) is often used as a placeholder for a numeric character input. You can use the PromptChar property to specify a custom prompt character. The HidePromptOnLeave property determines if the user sees the prompt characters when the control loses input focus.
As the user types input into the masked text box, valid input characters replace their respective prompt characters in a sequential fashion. If the user types an invalid input character, no replacement occurs, but instead a beep is issued if the BeepOnError property is set to true, and the MaskInputRejected event is raised. You can provide your own custom error logic by handing this event.
When the current insertion point is at a literal character, the user has a number of options:
-
If a character other than the prompt character is typed, the literal will automatically be skipped and the input character will be applied to the next editable position, represented by the next prompt character.
-
If the prompt character is typed and the AllowPromptAsInput property is true, the input will overtype the prompt character and insertion point will be moved to the next position in the mask.
-
As is always the case, the arrow keys can be used to navigate to a previous or subsequent position.
You can use the MaskFull property to verify whether or not the user has entered all of the required input. The Text property will always retrieve the user's input formatted according to the mask and the TextMaskFormat property.
The MaskedTextBox control actually defers all mask processing to the System.ComponentModel.MaskedTextProvider class specified by the MaskedTextProvider property. This standard provider supports all Unicode characters except for surrogates and vertically combined characters; however, the AsciiOnly property can be used to restrict input to the characters sets a-z, A-Z, and 0-9.
Masks do not necessarily guarantee that a user's input will represent a valid value for a given type; for example, -9 could be entered for an age in years. You can verify that a user's input represents a valid value by assigning an instance of that value's type to the ValidatingType property. You can detect whether the user removes focus from MaskedTextBox when it contains an invalid value by monitoring for the TypeValidationCompleted event. If type validation succeeds, the object representing the value will be available through the ReturnValue property of the TypeValidationEventArgs parameter.
As with the TextBox control, several common keyboard shortcuts do not work with MaskedTextBox. In particular, CTRL-R (right justify text), CTRL-L (left justify text), and CTRL-L (center text) have no effect.
Compatibility with Visual Basic 6.0
MaskedTextBox was designed to retain most of the functionality of the Masked Edit control in Visual Basic 6.0. The following table lists common properties on the Masked Edit control and gives their equivalents on MaskedTextBox.
| Masked Edit control (Visual Basic 6.0) property | Equivalent MaskedTextBox (.NET Framework) property |
|---|---|
| AllowPrompt property | AllowPromptAsInput |
| AutoTab property | None |
| ClipMode property | |
| ClipText property | Text (when TextMaskFormat is set to ExcludePromptAndLiterals) |
| Format property | None |
| FormattedText property | Text (when TextMaskFormat is set to IncludePromptAndLiterals) |
| Mask property | Mask |
| PromptChar property | PromptChar |
| PromptInclude property | |
| ValidationError event | MaskInputRejected |
Caution |
|---|
| The MaskedTextBox control does not support multiline configuration or undo functionality. However, while the members associated with these features have been retained for compatibility with the TextBoxBase base class, their implementations perform no actions. |
The following code example initializes the MaskedTextBox to accept a date, and uses both the MaskInputRejected and TypeValidationCompleted events to alert the user to invalid input.
Private Sub MaskedTextBox1_MaskInputRejected(ByVal sender As System.Object, ByVal e As System.Windows.Forms.MaskInputRejectedEventArgs) Handles MaskedTextBox1.MaskInputRejected If (Me.MaskedTextBox1.MaskFull) Then ToolTip1.ToolTipTitle = "Input Rejected - Too Much Data" ToolTip1.Show("You cannot enter any more data into the date field. Delete some characters in order to insert more data.", Me.MaskedTextBox1, Me.MaskedTextBox1.Location.X, Me.MaskedTextBox1.Location.Y, 5000) ElseIf (e.Position = Me.MaskedTextBox1.Mask.Length) Then ToolTip1.ToolTipTitle = "Input Rejected - End of Field" ToolTip1.Show("You cannot add extra characters to the end of this date field.", Me.MaskedTextBox1, Me.MaskedTextBox1.Location.X, Me.MaskedTextBox1.Location.Y, 5000) Else ToolTip1.ToolTipTitle = "Input Rejected" ToolTip1.Show("You can only add numeric characters (0-9) into this date field.", Me.MaskedTextBox1, Me.MaskedTextBox1.Location.X, Me.MaskedTextBox1.Location.Y, 5000) End If End Sub Private Sub Form1_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load Me.ToolTip1.IsBalloon = True Me.MaskedTextBox1.Mask = "00/00/0000" End Sub Private Sub MaskedTextBox1_KeyDown(ByVal sender As Object, ByVal e As KeyEventArgs) Handles MaskedTextBox1.KeyDown ' The balloon tip is visible for five seconds; if the user types any data before it disappears, collapse it ourselves. Me.ToolTip1.Hide(Me.MaskedTextBox1) End Sub
System.MarshalByRefObject
System.ComponentModel.Component
System.Windows.Forms.Control
System.Windows.Forms.TextBoxBase
System.Windows.Forms.MaskedTextBox
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.
Caution