This post covers new components that will be included in next version of DotNetBar for Windows Forms 8.1 that we are wrapping up right now. Today I will cover the all new SuperValidator component.

DotNetBar SuperValidator is the component set that helps you implement validation of user input in your WinForms applications without writing any code for most common validation scenarios. Here is screen-shot that shows simple validation performed on the form using SuperValidator and Highlighter controls included with DotNetBar:

1 – Super Validator control in action

To start using validations components, first drop the SuperValidator component from VS.NET toolbox onto your form:

2 – SuperValidator Component in VS.NET Toolbox

3 – SuperValidator added to VS.NET Form

Notice that when SuperValidator component is added to the form it automatically creates two supporting components:

• ErrorProvider component to display the error state and tooltip message next to each input field
• Highlighter component to visually highlight input field with error using distinctive border

SuperValidator can work with any of these components set or without any of them at all if you are planning to report validation results some other way.

Choosing when to perform validation

Next step is to choose the way SuperValidator performs validation. That is done by setting ValidationType property as shown in image below:

4 – ValidationType property setting

ValidationType values explained:

• Manual – You perform validation by calling SuperValidator.Validate method.
• ValidatingEventPerControl – For each control that is being validated the SuperValidator will handle its Validating event and perform validation. If validation fails it will use ErrorProvider and Highlighter that are set to indicate the error as well as cancel the focus move if CancelValidatingOnControl property is set to true (default value)
• ValidatingEventOnContainer – Validating event will be handled on ContainerControl, by default the parent form, to perform validation. If validation fails all failures will be reported using ErrorProvider and Highlighter, if set. The Cancel event argument in Validating event for container will be set to false as well if validation fails.

Assigning Validation To Controls

SuperValidator control adds Validator1, Validator2 and Validator3 properties to each control on the form as shown in image below:

5 – SuperValidator Properties

These properties allow you to define 3 level validation for each control. Validation starts with Validator1, Validator2 and finally Validator3. You can assign one of these properties or all of them if you need to perform multi-level validation. For example you can require the input for text-box and enforce the format to be an email by assigning Validation1 and Validation2 properties.

Select control you want to assign validation to and change its Validator1 property to choose desired validation type.

6 – Select control to set validation for

7 – Choosing validation for input text-box

In this example we will choose “Required Field Validator” which will ensure that text-box has value.

Next, expand the Validator1 property to set validation properties:

8 – Changing Validation Properties

Here is explanation for each property on validator in the order they are displayed in screen-shot above:

• DisplayError – Indicates whether failed validation is reported or not. The failed validation will still be available programmatically through LastFailedValidationResults collection.
• Enabled – Indicates whether validation is enabled.
• ErrorMessage – Is the message that is displayed through error provider to indicate to end-user what the problem is.
• HighlightColor – Specifies the highlight color that Highlighter component, if set, will use to highlight the control when validation fails.
• IsEmptyStringValid – For controls that support Null/Nothing values this property indicates whether an empty string is considered valid value.
• OptionalValidationGroup – Indicates the name of the group that validation belongs to. Groups are used to validate multiple controls as a single entity and allows you to for example require input in any of the controls in a group but not all of them.
• ValuePropertyName – Indicates the property name that holds control value. SuperValidator usually guesses correctly the property name (for example Text on TextBox) but in case you are using custom control with unusual property name that holds value of the control you can set it here.

Regular Expression Validation

In previous example you’ve seen required field validator. SuperValidator also provides validation based on the Regular Expressions. You can read more about regular expressions in MSDN starting at following URL: http://msdn.microsoft.com/en-us/library/hs600312%28VS.80%29.aspx

When Regular Expression Validator is assigned to input field it looks like this in property grid:

9 – Regular Expression Validator

Here is description for the properties that are specific to this validator:

• EmptyValueIsValid – Indicates whether validator will allow empty input values.
• ValidationExpression – Specifies the regular expression to use for control’s value validation. You can type your own regular expression or use drop-down button to choose one of the pre-defined expressions included with control.

Comparison Validation

SuperValidator component includes Comparison Validation that allows you to compare values of two input fields or to compare input field value to a predefined value you set. You can use this for example to ensure that password entered matches the confirmation password on input form or to ensure that numeric input value is greater than number you specify. Here is an example of input form that uses comparison validation to ensure that two password fields are the same:

10 – Comparison validation example form

These are properties set on confirmation password text-box that have comparison validator assigned:

11 – Comparison Validator properties

Here is description for properties that are specific to comparison validator:

• ControlToCompare – Specifies the control to compare the input value to. In the example above we will compare the confirmation password text box to the password text box.
• ControlToCompareValuePropertyName – Is the name of property that holds control value. Usually it is not necessary to set unless you want to use specific property as value property.
• Operator – Specifies the operator that is used for comparison. Following image shows available operators:
  
• ValueToCompare – Specifies the value to compare input value to using specified Operator. You would set this property if you want to use comparison operator to ensure certain value is entered in input control. Note that this value is used for comparison only if ControlToCompare property is not set.

Range Validation

Range validator allows you to ensure that input value is in certain range. Here are properties available on range validator:

Here is description for properties that are specific to range validator:

• MaximumValue – Indicates maximum value.
• MinimumValue – Indicates minimum value.

Custom Validation

When none of available validation options fit the bill you can use custom validator and write your own validation code. When you assign the custom validation to a control here is what you see:

12 – Custom validator

Next step is to attach event handler for ValidateValue event on custom validator. First, select CustomValidator instance in VS.NET property grid using the combo-box on top of the property grid:

With CustomValidator component selected, switch to the event view:

And double-click the ValidateValue event to create event handler:

Here is example code for ValidateValue event handler:

C#:

private void customValidator1_ValidateValue(object sender, DevComponents.DotNetBar.Validator.ValidateValueEventArgs e) {

if (e.ControlToValidate.Text == “DotNetBar”)
e.IsValid = true;
else
e.IsValid = false;
}

VB:

Private Sub customValidator1_ValidateValue(ByVal sender As System.Object, ByVal e As DevComponents.DotNetBar.Validator.ValidateValueEventArgs) Handles customValidator1.ValidateValue
    If e.ControlToValidate.Text = "DotNetBar"  Then				
       e.IsValid = True
    Else
        e.IsValid = False
    End	If
End  Sub

This example validation simply checks whether value entered is “DotNetBar” and validates control input if it is.

Working with SuperValidator from Code

When working with SuperValidator using VS.NET designer all settings that you make are actually translated into the code that you can find in InitializeComponent() method of your form. The easiest way to find out how to do something from code is to setup the control the way you want it using designer and then explore InitializeComponent() method.

Here is simple setup for SuperValidator control:

C#:

SuperValidator superValidator1 = new SuperValidator();
superValidator1.ContainerControl = myParentForm;
superValidator1.ErrorProvider = myErrorProvider1;
superValidator1.Highlighter = myHighlighter1;
superValidator1.ValidationType = DevComponents.DotNetBar.Validator.eValidationType.ValidatingEventOnContainer;

VB:

Dim superValidator1 As DevComponents.DotNetBar.Validator.SuperValidator
superValidator1 = New DevComponents.DotNetBar.Validator.SuperValidator
superValidator1.ContainerControl = myParentForm
superValidator1.ErrorProvider = myErrorProvider1
superValidator1.Highlighter = myHighlighter1
superValidator1.ValidationType = DevComponents.DotNetBar.Validator.eValidationType.ValidatingEventOnContainer

Assigning validation to a control on the form is done using following code:

C#:

RequiredFieldValidator requiredFieldValidator1 = new RequiredFieldValidator();
requiredFieldValidator1.ErrorMessage = "Please enter First Name.";
requiredFieldValidator1.HighlightColor = DevComponents.DotNetBar.Validator.eHighlightColor.Red;
superValidator1.SetValidator1(textBoxX1,requiredFieldValidator1);

VB:

Dim requiredFieldValidator1 As RequiredFieldValidator
requiredFieldValidator1 = New RequiredFieldValidator()
requiredFieldValidator1.ErrorMessage = "Please enter First Name."
requiredFieldValidator1.HighlightColor = DevComponents.DotNetBar.Validator.eHighlightColor.Red
superValidator1.SetValidator1(textBoxX1,requiredFieldValidator1)

To remove validator from control you would use following code:

C#:

superValidator1.SetValidator1(textBoxX1, null);

VB:

superValidator1.SetValidator1(textBoxX1, Nothing)

Handling Cancel button on the form

If you have dialog form with validation attached to the controls and validation type is set to per-control or container, to be able to close the form as response to Cancel button being clicked you would simply disable validator by setting Enabled property to false:

superValidator1.Enabled = false

Then you can close your form as usual using Close method.

Custom Error Providers

If you wish to use custom error provider to display validation errors in your application you can do so by implementing IErrorProvider interface. You assign your custom error provider to CustomErrorProvider property.

I hope this gives you a good overview of the new SuperValidator component. Stay tuned for more…