Validation

• Oct 29, 2020
• 4 minutes to read

When creating applications which allow users to input values it’s important to check the validity of the entered values. The editors in the XtraEditors library provide automatic and manual input validation facilities.

Automatic and Manual Validation

User input is automatically controlled by the editor when using the mask functionality. Masks let you specify the pattern used to input values and an end-user cannot enter text which is not permitted by the mask. Thus in masked mode the entered values always match the edit masks.

In some cases, however, you may want to provide manual validation control (limit the range of valid values, implement a conditional validation mechanism, etc). For this purpose the RepositoryItem.Validating event should be handled. This event lets you check the value entered before it is accepted. If the value entered doesn’t meet your restrictions or is of the wrong type, you can indicate that the current value has failed validation.

The RepositoryItem.Validating event is raised when an end-user attempts to accept the edited value. This occurs in the following cases:

• the editor is about to lose focus;
• the end-user has pressed the ENTER key. The RepositoryItemTextEdit.ValidateOnEnterKey property should be set to true to allow this.

To indicate that the edit value has failed validation set the event’s Cancel parameter to true.

When using masks in editors the entered value is automatically checked against the mask first. In specific cases the value may fail validation. For instance, when the editor’s MaskProperties.IgnoreMaskBlank property is set to false and the value has only been partially entered (not all the placeholders in the mask are filled) the value will fail validation when an end-user tries to leave the editor. The RepositoryItem.Validating event will be fired as a result and its Cancel parameter is set to true by default.

Note: the validation events do not fire if the editor’s CausesValidation property is set to false.

Responding to Validation Failure

By default when the editor fails validation an error icon with a tooltip is displayed. The editor remains focused thus forcing end-users to correct the entered value:

To implement a custom response to invalid values being entered the BaseEdit.InvalidValue event should be handled. For instance, you can suppress the default behavior of an error icon and tooltip being displayed and display a custom message instead or revert to the old value, etc.

To specify the type of response to supply for invalid values use the event’s ExceptionEventArgs.ExceptionMode parameter:

ExceptionMode Value	Description
DisplayError	Displays a tooltip with an error description specified by the ExceptionEventArgs.ErrorText parameter. Use the ErrorText parameter to change the default error description (“Invalid Value”).
Ignore	Discards new data and reverts to an old value. Note In standalone editors, because of the .NET binding mechanism, the Ignore value doesn’t work correctly. In container controls, the Ignore value works as expected.
NoAction	Suppresses displaying the tooltip or throwing an exception. The value remains unchanged.
ThrowException	Throws an exception specified by the ExceptionEventArgs.Exception property.

In the following example a custom validation algorithm is implemented via the RepositoryItem.Validating event. Assume that a date editor should accept values that belong to the current month only. All other values are invalid.

When the editor fails validation a message box with custom error text will be invoked:

C#

using DevExpress.XtraEditors.Controls;

private void dateEdit1_Validating(object sender, System.ComponentModel.CancelEventArgs e) {
   DateTime currentValue = (sender as DateEdit).DateTime;
   if(currentValue.Month != DateTime.Today.Month || currentValue.Year != DateTime.Today.Year)
      e.Cancel = true;
}

private void dateEdit1_InvalidValue(object sender, InvalidValueExceptionEventArgs e) {
   e.ExceptionMode = DevExpress.XtraEditors.Controls.ExceptionMode.NoAction;
   MessageBox.Show("Enter a date within the current month.", "Error");
}

VB.NET

Imports DevExpress.XtraEditors.Controls

Private Sub DateEdit1_Validating(ByVal sender As Object, _
ByVal e As System.ComponentModel.CancelEventArgs) Handles DateEdit1.Validating
   Dim currentValue As DateTime = CType(sender, DevExpress.XtraEditors.DateEdit).DateTime
   If Not (currentValue.Month = DateTime.Today.Month And _
     currentValue.Year = DateTime.Today.Year) Then e.Cancel = True
End Sub

Private Sub DateEdit1_InvalidValue(ByVal sender As Object, _
ByVal e As InvalidValueExceptionEventArgs) Handles DateEdit1.InvalidValue
   e.ExceptionMode = DevExpress.XtraEditors.Controls.ExceptionMode.NoAction
   MessageBox.Show("Enter a date within the current month.", "Error")
End Sub

 

You can also show editor errors using the BaseEdit.ErrorText property. If an error occurs, set this property to a string that describes the error. The editor will display an error icon. Pointing to that icon displays a hint with the error message specified. Note: you need to reset the BaseEdit.ErrorText property if validation is successful. This will hide the error icon.