Visual Basic Concepts
Using the MaskedEdit Control
The MaskedEdit control is used to prompt users for data input using a mask pattern. You can also use it to prompt for dates, currency, and time, or to convert input data to all upper- or lowercase letters. For example, to prompt the user to enter a phone number, you can create the following input mask: "(___) - ___ - ____". If you don't use an input mask, the MaskedEdit control behaves much like a standard text box.
When you define an input mask using the Mask property, each character position in the MaskedEdit control maps to a placeholder of a specified type, or to a literal character. Literal characters, or literals, give visual cues about the type of data being used. For example, the parentheses surrounding the area code of a telephone number are literals: (206).
The input mask prevents users from entering invalid characters into the control. If the user attempts to enter a character that conflicts with the input mask, the control generates a ValidationError event.
The MaskedEdit control is a bound control and can be used with a data control to display or update field values in a data set.
Possible Uses
To prompt for date/time, number, or currency information.
To prompt for custom mask formats such as a telephone number or any other input that follows a pattern.
To format the display and printing of mask input data.
To work with a data control to display and update field values in a data set.
The Mask Property
The Mask property determines the type of information that is input into the MaskedEdit control. The Mask property uses characters such as the pound sign (#), backslash (\), comma (,), and ampersand (&) as placeholders that define the type of input. The following table lists all the characters you can use to set the Mask property:
| Mask character |
Description |
| # | Digit placeholder. |
| . | Decimal placeholder. The actual character used is the one specified as the decimal placeholder in your international settings. This character is treated as a literal for masking purposes. |
| , | Thousands separator. The actual character used is the one specified as the thousands separator in your international settings. This character is treated as a literal for masking purposes. |
| : | Time separator. The actual character used is the one specified as the time separator in your international settings. This character is treated as a literal for masking purposes. |
| / | Date separator. The actual character used is the one specified as the date separator in your international settings. This character is treated as a literal for masking purposes. |
| \ | Treat the next character in the mask string as a literal. This allows you to include the '#', '&', 'A', and '?' characters in the mask. This character is treated as a literal for masking purposes. |
| & | Character placeholder. Valid values for this placeholder are ANSI characters in the following ranges: 32-126 and 128-255. |
| > | Convert all the characters that follow to uppercase. |
| < | Convert all the characters that follow to lowercase. |
| A | Alphanumeric character placeholder (entry required). For example: a z, A Z, or 0 9. |
| a | Alphanumeric character placeholder (entry optional). |
| 9 | Digit placeholder (entry optional). For example: 0 9. |
| C | Character or space placeholder (entry optional). |
| ? | Letter placeholder. For example: a z or A Z. |
| Literal | All other symbols are displayed as literals; that is, as themselves. |
To create an input mask, you combine mask characters with literal characters. Literal characters are characters which rather than representing some data type or format, are used as themselves. For example, to create an input mask for a phone number you define the Mask property as follows:
MaskEdBox1.Mask = (###) - ### - ####
The pound sign (a digit placeholder) is used with the left and right parentheses and the hyphen (literal characters). At run time, the MaskedEdit control would look like the following:
A MaskedEdit control with a phone number mask
.gif)
When you define an input mask, the insertion point automatically skips over literals as you enter data or move the insertion point.
The Text and ClipText Properties
All data entered in the MaskedEdit control is contained in and can be retrieved from the Text property. This is a run time only property and includes all the literal and prompt characters of the input mask. For instance, retrieving data from the Text property of the example above returns the string "(555) - 555 - 5555" – the phone number that was entered.
The ClipText property also returns data entered in the MaskedEdit control, but without the literal and prompt characters. Using the example above, retrieving data from the ClipText property returns the string "5555555555". The ClipText property is available only at run time.
Defining the Input Character
By default, all mask characters are underlined. This indicates to the user that the character is a placeholder for data input. When the user enters a valid character, the underline disappears. If you want the underline to remain, you can set the FontUnderline property of the MaskedEdit control to True.
You can also change the underline input character to a different character by using the PromptChar property. For example, to change the underline (_) character to the asterisk (*) character, you simply redefine the value of the PromptChar property:
MaskEdBox1.PromptChar = "*"
Using Mask Characters as Literals
If you want to use a mask character as a literal, you can precede the mask character with a backslash (\). For example, if you want the pound sign (#) to display, you set the mask as follows:
MaskEdBox1.Mask = "\##"
This would produce a mask that displays a pound sign (#) followed by a blank space for entering a number.
The Format Property
You can modify how the MaskedEdit control is displayed and printed using the Format property. The Format property provides you with standard formats for displaying number, currency, and date/time information.
The following table lists the standard formats you can use with the Format property:
| Data type | Value | Description |
| Number | (Default) Empty string | General Numeric format. Displays as entered. |
| Number | $#,##0.00;($#,##0.00) | Currency format. Uses thousands separator; displays negative numbers enclosed in parentheses. |
| Number | 0 | Fixed number format. Displays at least one digit. |
| Number | #,##0 | Commas format. Uses commas as thousands separator. |
| Number | 0% | Percent format. Multiplies value by 100 and appends a percent sign. |
| Number | 0.00E+00 | Scientific format. Uses standard scientific notation. |
| Date/Time | (Default) c | General Date and Time format. Displays date, time, or both. |
| Date/Time | dddddd | Long Date format. Same as the Long Date setting in the International section of the Microsoft Windows Control Panel. Example: Tuesday, May 26, 1992. |
| Date/Time | dd-mmm-yy | Medium Date format. Example: 26-May-92. |
| Date/Time | ddddd | Short Date format. Same as the Short Date setting in the International section of the Microsoft Windows Control Panel. Example: 5/26/92. |
| Date/Time | ttttt | Long Time format. Same as the Time setting in the International section of the Microsoft Windows Control Panel. Example: 05:36:17 A.M. |
| Date/Time | hh:mm A.M./P.M. | Medium Time format. Example: 05:36 A.M. |
| Date/Time | hh:mm | Short Time format. Example: 05:36. |
You use the Format property with the Mask property. For example, to create a mask that prompts for a Short Date input that displays in the Long Date format, you set the Mask and Format properties as follows:
MaskEdBox1.Mask = "##-##-##"
MaskEdBox1.Format = "dddddd"
When the user enters the date in the short format (06-27-96, for instance), the MaskedEdit control verifies that the entered data is valid, and then, when the focus passes to the next control, it is displayed as "Thursday, June 27, 1996".
Note To automatically shift the focus to the next control when the data has been verified as valid, set the AutoTab property of the MaskedEdit control to True.
The Format property also allows you to specify custom formatting using the same format expressions defined by the Visual Basic Format function.
For More Information See "Format Function" or "Format Property (MaskedEdit control)."
Setting Properties at Design Time
You can set the property values at design time using the MaskedEdit control Property Pages. Click the Custom option in the Properties window of the MaskedEdit control to bring up the Property Pages dialog box, as shown below:
Setting the Mask property at design time
.gif)
You enter the mask and format patterns as in the run time examples above. The Format drop down list allows you to select any of the predefined standard formats shown above. This dialog box also allows you to easily set such properties as PromptChar, ClipMode, and MaxLength.
A MaskedEdit field can have a maximum of 64 characters (the valid range is 1 to 64 characters). This includes literal characters as well as mask characters. You can set this value using the MaxLength property. At design time, this property is set automatically to the number of characters in the pattern when you enter a mask pattern.
The ClipMode property specifies whether or not literal characters are included when doing a cut or copy command. By default, when a selection in the MaskedEdit control is copied to the Clipboard, the entire selection, including the literals, is transferred. To limit the copy operation to only the data entered by the user, set the ClipMode property to True.
The ValidationError Event
The ValidationError event occurs when the MaskedEdit control receives invalid input, as determined by the input mask. For example, if you've defined an input mask that prompts for numbers, a ValidationError event will occur if the user attempts to enter a letter. Unless you write an event handler to respond to the ValidationError event, the MaskedEdit control will simply remain at the current insertion point — nothing will happen.
Mask characters are validated as they are entered and the insertion point is shifted to the right. When a character is entered or deleted out of sequence (when a digit is inserted or deleted after the phone number has been entered, for example), all nonliteral characters shift either to the right or left. When the shift occurs, if an invalid character replaces the position of a valid character, the ValidationError event is triggered.
For example, suppose the Mask property is defined as "?###", and the current value of the Text property is "A12." If you attempt to insert the letter "B" before the letter "A," the "A" would shift to the right. Since the second value of the input mask requires a number, the letter "A" would cause the control to generate a ValidationError event.
The MaskedEdit control also validates the values of the Text property at run time. If the Text property settings conflict with the input mask, the control generates a run-time error.
You can select text in the same way you would with a standard text box control. When selected text is deleted, the control attempts to shift the remaining characters to the right of the selection. However, any remaining character that might cause a validation error during this shift is deleted, and no ValidationError event is generated.
For More Information See "ValidationError Event."
Using MaskedEdit as a Bound Control
The MaskedEdit control is a bound control. This means that it can be linked to a data control and display field values for the current record in a data set. The MaskedEdit control can also write out values to a data set.
Note When the value of the field referenced by the DataField property is read, it is converted to a Text property string, if possible. If the recordset is updatable, the string is converted to the data type of the field.
The MaskedEdit control has three bound properties: DataChanged, DataField, and DataSource.
For More Information See "Using the ADO Data Control" in "Using Visual Basic's Standard Controls" in the Programmer's Guide for information on using bound controls.