70-526 MCTS
MaskedTextBox control
The MaskedTextBox control constrains the format of user input by distinguishing between
proper and improper user input. This class is an enhanced TextBox control that allows a preset
pattern to be declared for accepting or rejecting user input.
The Mask property of the MaskedTextBox control allows you to specify whether
input characters are letters or numbers, as well as any formatting.
Inheritance hierarchy
System.Object
System.MarshalByRefObject
System.ComponentModel.Component
System.Windows.Forms.Control
System.Windows.Forms.TextBoxBase
System.Windows.Forms.MaskedTextBox
Useful properties
AllowPromptAsInput - Indicates whether PromptChar can be entered as valid data by the user.
AsciiOnly - Indicates whether the MaskedTextBox control accepts characters outside of the ASCII character set.
BeepOnError - Indicates whether the masked text box control raises the system beep for each user key stroke that it rejects.
CutCopyMaskFormat - Determines whether literals and prompt characters are copied to the clipboard.
HidePromptOnLeave - Indicates whether the prompt characters in the input mask are hidden when the masked text box loses focus.
InsertKeyMode - Specifies the text insertion mode of the MaskedTextBox control.
Mask - Specifies the input mask to use at run time.
PromptChar - Specifies the character used to represent the absence of user input in MaskedTextBox.
RejectInputOnFirstFailure - Indicates whether the parsing of user input should stop after the first invalid character is reached.
ResetOnPrompt - Determines how an input character that matches the prompt character should be handled.
ResetOnSpace - Determines how a space input character should be handled.
SkipLiterals - Indicates whether the user is allowed to re-enter literal values.
TextMaskFormat - Determines whether literals and prompt characters are included in the formatted string.
The Mask property
This property allows you to define a string that represents the required format that the string must be input into the MaskedTextBox. The default value is an empty string which allows any input.
The Mask is composed of one or more of the masking elements from the table below. The MaskedTextProvider associated with the MaskedTextBox provides the parsing engine for the Mask.
| 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. |
The decimal (.), thousandths (,), time (:), date (/), and currency ($) symbols display those symbols as defined by the culture of the application. These can be forced to another through the use of the FormatProvider property.
Characters are inserted into the mask at run time are controlled by the InsertKeyMode property. Navigation through the mask is done through the left and right arrow keys or the mouse cursor, and optional positions in the mask can be skipped by entering a space.
Example Mask Strings
Some example of mask strings are shown below:
(99999)-0000000 could be used for a UK telephone number. The area code is optional, so the user can either enter spaces within the brackets, or place the mouse pointer directly at the start of the mask represented by the first 0. If the user entered 01805123456, then the displayed text would be (01805)-123456.
00/00/0000 could be used to represent 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. Is the user entered 01041971, then the displayed text would be 01/04/1971 dependant upon the application's current culture.
00->L<LL-0000 could also be used to represent a date (day, month abbreviation, and year) in which the three-letter month abbreviation is displayed with an initial uppercase letter followed by two lowercase letters. If the user entered 01apr1971, then the displayed text would be 01-Apr-1971.
$999,999.00 can be used to represent 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. If a user entered 12345678, then the displayed text would be £123,456.78 in the UK.
Setting masked text graphically
Clicking the smart tag icon 
on a MaskedTextBox
control in the designer causes a small menu to appear.
Clicking on the Set Mask... item causes the Input Mask dialog to appear.
Once you have chosen a mask from the list, entering text/numbers in the preview text box allows you to test out the mask.
MSDN references
Other
| << Previous | Contents | Next >> |