This documentation is archived and is not being maintained.

Masked Edit Control

Visual Studio .NET 2003

The Masked Edit control provides restricted data input as well as formatted data output. This control supplies visual cues about the type of data being entered or displayed. This is what the control looks like as an icon in the Toolbox:

File Name

MSMASK32.OCX

Class Name

MaskEdBox

Remarks

The Masked Edit control generally behaves as a standard text box control with enhancements for optional masked input and formatted output. If you do not use an input mask, the Masked Edit control behaves much like a standard text box.

If you define an input mask using the Mask property, each character position in the Masked Edit control maps to either a placeholder of a specified type or a literal character. Literal characters, or literals, can 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).

If you attempt to enter a character that conflicts with the input mask, the control generates a ValidationError event. The input mask prevents you from entering invalid characters into the control.

The Masked Edit control has three bound properties: DataChanged, DataField, and DataSource. This means that it can be linked to a data control and display field values for the current record in the recordset. The Masked Edit control can also write out values to the recordset.

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.

To clear the Text property when you have a mask defined, you first need to set the Mask property to an empty string, and then the CtlText property to an empty string:

MaskedEdit1.Mask = ""
MaskedEdit1.Text = ""

When you define an input mask, the Masked Edit control behaves differently from the standard text box. The insertion point automatically skips over literals as you enter data or move the insertion point.

When you insert or delete a character, all nonliteral characters to the right of the insertion point are shifted, as necessary. If shifting these characters leads to a validation error, the insertion or deletion is prevented, and a ValidationError event is triggered.

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" to the left of 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 Masked Edit control also validates the values of the Text property at run time. If you set the Text property so that it conflicts with the input mask, the control generates a run-time error.

You may select text in the same way as for a standard text box control. When selected text is deleted, the control attempts to shift the remaining characters to the left of the selection.

Normally, when a selection in the Masked Edit control is copied onto the Clipboard, the entire selection, including literals, is transferred onto the Clipboard. You can use the ClipMode property to transfer only user-entered data onto the Clipboard — literal characters that are part of the input mask are not copied.

Example

In the example below, medDate is the masked edit control. InitMedDate is a function that could be called from the form Sub New.

Note   If you upgrade code from previous versions of Visual Basic, you will need to update the event declarations, which now include send and event args parameters.
Sub InitMedDate()
    With Me.medDate
        'This box will hold date information.
        .Mask = "##/##/##"
        .Text = "12/01/99"
        'The user likes bold Arial font at double the default.
        'Double the size of the control to fit.
        .FontName = "Arial"
        .FontBold = True
        .FontSize *= 2
        .Height *= 2
        .Width *= 2
    End With
End Sub

Public Sub medDate_Enter(ByVal sender As Object, ByVal e As System.EventArgs) Handles medDate.Enter
    'The user prefers yellow on purple for entering text.
    Me.medDate.BackColor = Color.Purple
    Me.medDate.ForeColor = Color.Yellow
End Sub

Public Sub medDate_Leave(ByVal sender As Object, ByVal e As System.EventArgs) Handles medDate.Leave
    'Set the colors back to the default after leaving the edit box.
    Me.medDate.BackColor = Me.medDate.DefaultBackColor
    Me.medDate.ForeColor = Me.medDate.DefaultForeColor
End Sub

See Also

Properties, Methods, and Events | Masked Edit Control Constants | ValidationError Event

Show: