MaskedTextBox and MaskedTextBox.ValidatingType
(As with VS 2005 Cool Feature No. 8, the MaskedTextBox control is a feature that fits into my "'Bout Freakin Time" list. I'm very happy to see this control as part of the standard Winforms Controls in .NET 2.0.)
Masked Text Boxes are an important part of a developers toolbox. They allow easy to use, quick data validation on the UI. This provides a couple of benefits: 1) The USER of the application knows what format the input is supposed to be in. 2) The developer of the application can make a more comfortable assumption that the data input is going to be valid.
Lets build of my previous SSN example, and apply this class to the MaskedTextBox, while specifically showing off the ValidatingType feature. Start by creating a simple WinForms project, and dropping two controls onto it: 1) the MaskedTextBox, 2) A plain old text box (mostly used for the "cool feature" portion of this article, but also instigates some needed functionality of the masked text box)
Once we have these controls in place, we want to setup the Masked box's "Mask" property. This is where the actual format of the input is specified. For a list of all Mask options, see MSDN Library's "Mask" property help page. For this example, we'll use the standard SSN mask of "999-99-9999". This mask ensures that only digits are entered into the 9 spaces of the SSN, and also provides a literal definition of the two hyphens in the format of the SSN.
After setting the Mask property, our MaskedTextBox will now properly validate the input of an SSN on our form - no additional code is required. The Masked TextBox also includes a good variety of predefined. To select a pre-defined mask, click on the elipses to the right of the Mask property, and you will be presented with the following form:
From here, you can select a pre-defined mask, or select "<custom>" and enter your own mask. They have even provided a "Preview" MaskedTextBox to try your mask out. Also note on this form, the "Validating Type" column, and the "Use ValidatingType" checkbox. This new ValidatingType feature allows a developer to not only validate the format of the input, but also automatically convert the valid input into an object of their choice. Many of the built in masks have validating types, such as "Int32" and "DateTime". The custom maks does not list a validating type, due to the unkown input that custom allows. However, we can use the validating type in our code.
If you look back at VS 2005 Cool Feature No. 8, you'll see the "Parse" method mentioned at the bottom of the article. As noted in that article, one valid reason for maintaining a "Parse" method on your object, is to implement the ValidatingType feature of the MaskedTextBox. Personally, I believe this was a mistake on Microsoft's part. I would have rather seen them use the "CType" operator overloading, rather than a naming convention of this sort (the method name can't be included in an Interface, because it is required to be static).
MSDN For Visual Studio says this about the ValidatingType and Parse method:
Masks do not in themselves guarantee that a user's input will represent a valid value for a given type. The following C# code shows a mask:
| |
|
maskedTextBox1.Mask = "99/99/9999"; |
The following Visual Basic code shows a mask:
MaskedTextBox1.Mask = "99/99/9999"
This mask can demand that the user enter eight digits, but cannot verify that the user enters month, date, and year values in the correct range; "12/20/2003" and "70/90/0000" are equally valid as far as the mask is concerned.
You can use ValidatingType to verify whether the data entered by the user falls within the correct range—in the previously mentioned case, by assigning it an instance of the DateTime type. The current text in the control will be validated either when the user leaves the control. You can determine whether or not the data fails validation by monitoring for the TypeValidationCompleted event. MaskedTextBox will only perform the check against ValidatingType if MaskCompleted is true.
If you want to use your own custom data types with ValidatingType, you must implement a static Parse method that takes a string as a parameter. This method must be implemented with one or both of the following signatures:
public static Object Parse(string)
public static Object Parse(string, IFormatProvider)
By implementing the "Parse(string)" method on the SSN object, we have provided the ability to use our SSN object as a ValidatingType for the MaskedTextBox control
Being the good OOP developers that we are, we're simply forwarding the Parse call to the CType overload and converting from a string to an SSN object.
To implement the SSN object as a ValidatingType, set the MaskedTextBox's "ValidatingType" property to the SSN type, as noted in our Form's code, in the "Form_Load" event. This tells the MaskedTextBox that we want to not only validate our input's format, but also validate that it will properly work with our object.
Note the use of the "TypeValidationCompleted" event in this code, as well. This event provides us with all of the information we need about our masked input, including whether or not the actual input is valid, and if it is, a reference to the object created by the Parse method. In this instance, we are checking to see if the input is valid, and if it is, obtaining an SSN object to use, and then setting the Text value of the other TextBox on our form, to the .ToString() method of the SSN object.
There is actually another purpose for the second TextBox on the form, however. According to MSDN For Visual Studio, the TypeValidationCompleted event will not fire until after the MaskedTextBox has lost focus on the form. This means that there is a limited number of ways to produce the desired event, all of which involve moving the focus away from our MaskedTextBox control. To provide an easy way to do this, adding a second TextBox to the form allows us to either click on the second text box directly, or simply hit the "Tab" button, to focus on the second text box. Once focus is on the second text box, the TypeValidationCompleted event will fire, and our code will execute.
Placing a Breakpoint on the "CType" and "Parse" methods of the SSN object will allow you to see when each of these methods is called, and watch the code in action. The end result is an excellent object design. It uses the CType operator overload and the Parse method for using the MaskedTextBox.ValidatingType feature. This has allowed us to write a fully functional data input validation form that includes instantiating an actual object from our input, in only 5 lines of executing code. I'd say that's worth the price of admission.