Validates form fields (TextBox or DataGridView controls) by attributes you define on them, manifesting with both an individual error indication and a disabling of a designated common form submittal (ok) button.
For a list of all members of this type, see Validator Members.
System.Object
Validator
Thread Safety
Public static (Shared in Visual Basic) members of this type are safe for multithreaded operations. Instance members are not guaranteed to be thread-safe.
Remarks
Tired of writing custom validation code for every input field in your applications? This class provides a generic validation engine that can automate many validation scenarios. Besides the description here, I have also published an article discussing the practical uses of this tool -- Exploring Secrets of Windows Form Validation -- available on the DevX online magazine.
A validation error may be displayed in either an individual Label component unique to each control, or by using the standard ErrorProvider component. The latter has the advantage that you do not have to create and associate a Label component with each validating component, but the disadvantage that you must use the mouse to see the validation error.
In order to validate a control, you add it to a Validator instance, then call one of the Validate methods inside either the TextChanged or Validating event handler. MSDN documentation suggests the Validating event handler is the appropriate place. Note that the handler will be called only when focus leaves a control. So if you want finer control (as in every keystroke) then TextChanged is a better choice.
In addition to adding the control to the Validator, you must attach attributes to the control that specify just what you want to validate. This is done using the Tag property. You specify a list of 1 or more attributes from those below that you want to validate. All of the ones you specify will be evaluated, but only one error will be reported at a time.
Each singular Control (e.g. TextBox) must have a validation attribute list (stored on the Tag property) in the following format:
<attr1>=<value1>;<attr2>=<value2>;...;<attrN>=<valueN>The available attributes are:
-
- maxLen
- field must contain no more than the specified number of characters
-
- minLen
- field must contain at least the specified number of characters
-
- maxVal
- field must contain a number that is no larger than the specified value
-
- minVal
- field must contain a number that is no smaller than the specified value
-
- pattern
- field must match the specified regular expression
A collective control, such as a DataGridView, uses the same list of attributes, but the Tag definition is more complex. Each column in the DataGridView requires its own attribute list. The format is:
[<column1>]<attrList1>;[<column2>]<attrList2>;...[<columnN>]<attrListN>;where each
columnX is the name of a column and each attrListX is a complete validation attribute list as defined above.
The table below illustrates some sample validation attribute lists. Except for pattern, the attribute meanings should be clear. The pattern attribute is a regular expression (see .NET Framework Regular Expressions) providing a powerful, flexible mechanism for matching almost any input.
| Pattern | Description |
|---|---|
| maxLen=10 | value may be no more than 10 characters |
| minVal=0 | value may not be negative |
| minVal=0;maxVal=100 | value must be between 0 and 100 inclusive |
| minLen=1 | value must be non-empty |
| pattern=. | value must be non-empty |
| minLen=5;maxLen=5 | value must contain exactly 5 characters |
| pattern=.{5} | value must contain exactly 5 characters |
| pattern=^\S+$ | value may not contain spaces |
| pattern=^-?(?:\d*\.?\d+|\d+\.)$ | value must be a number |
| pattern=^\d{3}-\d{3}-\d{4}$ | value must be a canonical US phone number |
| pattern=^\w[\w\.]*\@\w+\.\w[\w\.]*$ | value must be an e-mail address |
Usage:
In the Load event handler for your Form include:
validator = new Validator(okButton); validator.Add(xyzTextBox, xyzErrLabel); validator.Add(otherTextBox, otherErrLabel); . . . // Add additional controls to be validated. validator.ValidateAll();Then in the TextChanged event handler for each TextBox, add this:
validator.Validate((TextBox)sender);This current version only handles TextBox and DataGridView controls; more controls may be added in the future.
Since CleanCode 0.9.07.
Example
For a DataGridView with columns (Cmd, Item, MatchExpr, Format), this Tag property:
[Cmd]pattern=^\w;[Item]pattern=^\w+$;[MatchExpr]pattern=\(.*\);[Format]pattern=\{\d.*\}
specifies (coarsely speaking) that Cmd values must begin with a number or letter, Item values must contain letters and numbers but no spaces, MatchExpr values must contain a set of parentheses, and Format values must have at least 1 digit within a set of braces. Requirements
Namespace: CleanCode.Forms
Assembly: CleanCode (in CleanCode.dll)
See Also
Validator Members | CleanCode.Forms Namespace