• Spotlight on Controls

User Rating: 5 / 5

MaskedTextBox Control [System.Windows.Forms.MaskedTextBox]

Represents an enhanced text box control that supports a declarative syntax for accepting or rejecting user input.

Default Event: MaskInputRejected

Why use a MaskedTextBox control?

Use the MaskedTextBox to distinguish between proper and improper user input. By using a mask, you can specify the format of the input without custom validation.

Important Properties:

Mask

This property sets the string governing the input for this control. 

Why use the Mask property?

Use the Mask property to limit the textbox’s input to a specific format. You can define your own custom mask or preferably select from a predefined set using the designer. The designer has a useful set of predefined masks such as date time formats, phone numbers, and zip codes.

You can access the predefined mask via the Property Pane:

Or directly in the designer:

If you need to create you own format, please refer to the following table or go to the Mask Property MSDN Help Page for more details.

An example mask for a US phone number is a follows:

(999) 000-0000

In this mask the first three digits are optional and the last seven are required. The parentheses are considered Literals, which means the user cannot altered them.

Resulting MaskedTextBox with Phone Number Mask:

BeepOnError

This property indicates whether the masked text box control raises the system beep for each user key stroke that it rejects.

Values (Default: $False):

$True/ $False

Culture

This property sets the culture information associated with the masked text box.

Set this property if you are specifically targeting a culture that is not the current default (English (United States) for US machines). This effects the format of the date time entries and these changed will be reflected when selecting predefined masks as mentioned above.

MaskCompleted

This property indicates whether all required inputs have been entered into the input mask.

The MaskCompleted property can be useful when it comes to validating the data. See the MaskFull property for an example.

MaskFull

This property indicates whether all required and optional inputs have been entered into the input mask.

This property is similar to MaskCompleted property with the exception that it also encompasses optional inputs specified in the Mask property. To compare these properties and to demonstrate their usefulness when it comes to validating, we will look at validating a phone number. The predefined Mask for a US phone number specifies that the area code (first three digits) is optional and the remaining seven digits are mandatory.

The following examples will help demonstrate the difference between the two properties:

Partially completed phone number:

Phone number without an area code:

Completed phone number:

Text

The property gets or sets the text as it is currently displayed to the user. 

The value returned may include formatting characters specified in the Mask property. See the TextMaskFormat property for more information.

TextMaskFormat

This property determines whether the string returned by the Text property includes literals and/or prompt characters.

Use the TextMaskFormat if you need to modify the format of the string that is returned by the Text property of the MaskedTextBox control.

Values (Default: IncludeLiterals):

The example values displayed are based on he following MaskTextBox:

IncludePrompt
Return text input by the user as well as any instances of the prompt character.

Text: “___5555555″

 

IncludeLiterals
Return text input by the user as well as any literal characters defined in the mask.

Text: “(   ) 555-5555″

 

IncludePromptAndLiterals
Return text input by the user as well as any literal characters defined in the mask and any instances of the prompt character.

Text:  “(___) 555-5555″

 

ExcludePromptAndLiterals
Return only text input by the user.

Text: ”   5555555″

ValidatingType

This property contains the data type used to verify the data input by the user.

You need not set this property normally, since the preset Masks already set this property appropriately. This ensures data types are within the correct range. For example “77/77/7777” is a valid format for a date, but the value is not.

You must set the ValidatingType property to a type, which in PowerShell is defined by the full class name surrounded by brackets. For example, to set the ValidatingType to a DateTime you will need to do the following:

$maskedtextboxBirthDate.ValidatingType = [System.DateTime]

Again you need not set this property if you are using a predefined mask.

Note: The ValidatingType property looks for a static method named “Parse” that must be present in the Type to validate the content. Since the DateTime class has a Parse method, it is compatible:

[System.DateTime]::Parse()

Other Common Types with the Parse static method includes the all the basic value types, such as:

[Int]

 

[Double]

 

[Float]

All enumerators are compatible, such as:

[System.Windows.Forms.DialogResult]

 

[Microsoft.PowerShell.ExecutionPolicy]

Important Methods:

ValidateText

This method converts the user input string to an instance of the validating type.

Use this method to determine if the content of the MaskTextBox is valid. This method requires that a compatible type be set in the ValdiatingType property. If the ValidateText fails it will return a $null value otherwise it will return an object of the corresponding type.

Example:

    if($maskedtextboxBirthDate.ValidatingType -ne $null)
    {
        if($maskedtextboxBirthDate.ValidateText() -eq $null)
        {
            #Validation Failed
        }
        else
        {
            #Validation Successful  
        }
    }

Note: The MaskTextBox will automatically validate the text when it loses focus.

Important Events:

MaskInputRejected

This event occurs when the user’s input or assigned character does not match the corresponding format element of the input mask.

Use this event when you want to react to invalid input:

$maskedtextboxPhone_MaskInputRejected=[System.Windows.Forms.MaskInputRejectedEventHandler]{
#Event Argument: $_ = [System.Windows.Forms.MaskInputRejectedEventArgs]    
    $labelError.Text = "Failed input -Postion ({0}): {1}"  -f $_.Position, $_.RejectionHint.ToString()
}

The event passes a parameter variable $_ . Use this variable to access the following properties:

$_.Position

Returns the position in the mask corresponding to the invalid input character.

 

$_.RejectionHint

Returns an enumerated value [System.ComponentModel.MaskedTextResultHint] that describes why the input character was rejected. Please see the MSDN MaskTextResultHist Help page for more information.

TypeValidationCompleted

This event occurs when MaskedTextBox has finished parsing the current value using the ValidatingType property.

Use this event in order to react to when a type validation fails or succeeds. This event is also fired when the ValdiateText method is called.

$maskedtextboxBirthDate_TypeValidationCompleted=[System.Windows.Forms.TypeValidationEventHandler]{
#Event Argument: $_ = [System.Windows.Forms.TypeValidationEventArgs]
    if($_.IsValidInput -eq $false)
    {
        $_.Cancel = $true #Keep the focus on the control
        $errorprovider1.SetError($maskedtextboxBirthDate, "Invalid Date Format");
    }
    else
    {
        $errorprovider1.SetError($maskedtextboxBirthDate, "");    
    }
}

The TypeValdiationCompleted passes a parameter variable $_. The following are important properties you can access with this variable:

$_.Cancel

This property indicates whether the event should be canceled. Set it to $true to retain the focus on the MaskTextBox.

 

$_.IsValidInput

This property indicates whether the formatted input string was successfully converted to the validating type.

 

$_.ReturnValue

This property returns the object that results from the conversion of the formatted input string.

For an example use of the MaskTextBox, please refer to the samples used in Validating the Form.

• Prev
• Next