Masked Edit Control

By defining the Mask property, extensive input validation and formatting is available. The Mask property string is composed of literal characters and of tokens and subtokens defining each input field.

A number of different input fields can be defined using tokens (see the Mask property for a complete list). Literal characters can also be added to the Mask. These characters will be displayed by the Masked Edit control, but the user cannot modify these. Only input fields allow data entry.

Both input fields and literal characters are displayed using the font defined using the Font property. Input fields can be underlined using the PromptUnderline property.

Input fields use the colors defined using the BackColor and ForeColor properties. Literal characters are displayed using the color defined using the BackColor and MaskForeColor properties.

Samples
Visual Feedback
FormattedText - Valid Contents

Samples

Telephone Number

This example allows entry of a telephone number. Area codes cannot start with a "0", only the digits 1 through 9 are acceptable in the first position.

private void Form1_Load(object sender, System.EventArgs e)
{
    axSftMask1.Caption.SizePercent = 0;
    axSftMask1.Mask = @"\([M1-9]##\) ###\-####";
}

Social Security Number

This example allows entry of a social security number.

private void Form1_Load(object sender, System.EventArgs e)
{
    axSftMask1.Caption.SizePercent = 0;
    axSftMask1.Mask = @"###\-##\-####";
}

Date and Time

One control is used to enter the date and time of an event. A popup calendar is available.

private void Form1_Load(object sender, System.EventArgs e)
{
    axSftMask1.Caption.SizePercent = 0;
    axSftMask1.Mask = "$D $T";
    axSftMask1.AutoAdvance = true;
    axSftMask1.TabAdvance = true;
    axSftMask1.EditStyle = SftMaskEditStyleConstants.editSftMaskCalendarDropDown;
    axSftMask1.Contents.DateTime = new DateTime(1976, 7, 4, 10, 0, 0);
}

Currency

This example shows entry of a currency value with a popup calculator and up/down buttons (spin buttons). This example uses the UpDownPress event so the application has complete control over the starting delay and the progressive increment.

private void Form1_Load(object sender, System.EventArgs e)
{
    axSftMask1.Caption.SizePercent = 0;
    axSftMask1.Alignment = SftMaskAlignConstants.alignSftMaskRight;
    axSftMask1.Mask = "$^C-,8.2";
    axSftMask1.Label = "|";
    axSftMask1.LabelPosition = SftMaskLabelPositionConstants.labelPositionSftMaskAuto;
    axSftMask1.EditStyle = SftMaskEditStyleConstants.editSftMaskUpDown;
}

private void axSftMask1_UpDownPress(object sender, AxSftMaskLib80._ISftMaskEvents_UpDownPressEvent e)
{
    if (e.counter == 0 || e.counter > 5) {
        double amount;
        if (!double.TryParse(e.field, out amount))
            amount = 0;
        double increment = 0.01;
        if (e.counter > 14) increment = 0.1;
        if (e.counter > 23) increment = 1;
        if (e.counter > 52) increment = 10;
        if (e.up)
            amount = amount + increment;
        else
            amount = amount - increment;
        // if (amount > yourMaximum) amount = yourMaximum;
        // if (amount < -yourMaximum) amount = -yourMaximum;
        e.field = amount.ToString("0.00");
    }
}

Percentage

This example allows entry of a percentage value (0-100) with up/down buttons (spin buttons).

private void Form1_Load(object sender, System.EventArgs e)
{
    axSftMask1.Caption.SizePercent = 0;
    axSftMask1.Alignment = SftMaskAlignConstants.alignSftMaskRight;
    axSftMask1.Mask = "$^3(0,100)";
    axSftMask1.EditStyle = SftMaskEditStyleConstants.editSftMaskUpDown;
    axSftMask1.Label = "%";
    axSftMask1.LabelPosition = SftMaskLabelPositionConstants.labelPositionSftMaskRight;
}

IP Address

This example allows entry of an IP address, consisting of 4 input fields. As the user enters data, the Tab key or "." can be used to move to the next field.

private void Form1_Load(object sender, System.EventArgs e)
{
    axSftMask1.Caption.SizePercent = 0;
    axSftMask1.EditStyle = SftMaskEditStyleConstants.editSftMaskUpDown;
    axSftMask1.Mask = @"$I^03(0,255)\.$I^03(0,255)\.$I^03(0,255)\.$I^03(0,255)";
    axSftMask1.AutoAdvance = true;
    axSftMask1.TabAdvance = true;
}

Visual Feedback - Valid Contents

It is possible to provide visual feedback to the user whether the current data entered is valid. In the following example, a telephone number is to be entered. The control's contents are displayed in red until the entire telephone number has been entered. Once the contents are valid, they are displayed using the default window background and foreground colors.

private void Form1_Load(object sender, System.EventArgs e)
{
    axSftMask1.Caption.SizePercent = 0;
    axSftMask1.Mask = @"\([M1-9]##\) ###\-####";
    axSftMask1.Text = "";
}

private void axSftMask1_Change(object sender, System.EventArgs e)
{
    if (axSftMask1.Contents.Valid) {
        axSftMask1.BackColor = SystemColors.Window;
        axSftMask1.ForeColor = SystemColors.WindowText;
        axSftMask1.MaskForeColor = SystemColors.WindowText;
    } else {
        axSftMask1.BackColor = Color.White;
        axSftMask1.ForeColor = Color.Red;
        axSftMask1.MaskForeColor = Color.Red;
    }
}

For a more noticeable effect, the background colors could also be modified, or even the Font property.

FormattedText - Valid Contents

The FormattedText property is used to specify the control's displayed text while the control does not have the input focus. This could be used for mandatory fields to highlight that the information has not yet been entered. In the following example, a telephone number is to be entered. As long as the control does not have the input focus and the telephone number has not yet been completely entered, the text "Need phone #" is displayed.

If the mouse cursor moves over the control, the input data is displayed, even if the control does not have the input focus.

private void Form1_Load(object sender, System.EventArgs e)
{
    axSftMask1.Caption.SizePercent = 0;
    axSftMask1.Mask = @"\([M1-9]##\) ###\-####";
    axSftMask1.Text = "";
    UpdateFormattedText();
}

private void axSftMask1_Change(object sender, System.EventArgs e)
{
    UpdateFormattedText();
}

private void UpdateFormattedText()
{
    if (axSftMask1.Contents.Valid)
        axSftMask1.FormattedText = "";
    else
        axSftMask1.FormattedText = "Need phone #";
}