|Exam 70-505: Create and Configure Text Edit Controls on a Windows Form|
The best way to stop users from entering invalid data into an input control is to make it impossible to do so. You can accomplish this by forcing the user to enter the data in a pre-chosen manner.
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.
Mask property of the
MaskedTextBox control allows you to specify whether input characters are letters or numbers, as well as any formatting.
System.Object System.MarshalByRefObject System.ComponentModel.Component System.Windows.Forms.Control System.Windows.Forms.TextBoxBase System.Windows.Forms.MaskedTextBox
AllowPromptAsInput- Indicates whether
PromptCharcan be entered as valid data by the user.
AsciiOnly- Indicates whether the
MaskedTextBoxcontrol 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
Mask- Specifies the input mask to use at run time.
PromptChar- Specifies the character used to represent the absence of user input in
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.
This property allows you to define a string that represents the required format for the input string put into the
MaskedTextBox. The default value is an empty string which allows any input.
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.
| ||Digit, required. This element will accept any single digit between 0 and 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 |
| ||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 |
| || Character, optional. Any non-control character. If the |
| || Alphanumeric, optional. If the |
| || Alphanumeric, optional. If the |
| || Decimal placeholder. The actual display character used will be the decimal symbol appropriate to the format provider, as determined by the control's |
| || Thousands placeholder. The actual display character used will be the thousands placeholder appropriate to the format provider, as determined by the control's |
| || Time separator. The actual display character used will be the time symbol appropriate to the format provider, as determined by the control's |
| || Date separator. The actual display character used will be the date symbol appropriate to the format provider, as determined by the control's |
| || Currency symbol. The actual character displayed will be the currency symbol appropriate to the format provider, as determined by the control's |
| ||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 |
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
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.
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. If 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 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.