Log In
Home
Support
Demos
Documentation
Blogs
Training
Webinars
[Expand]General Information
[Collapse]WinForms Controls
  Prerequisites
 [Expand]What's Installed
 [Expand]Build an Application
 [Collapse]Controls and Libraries
  [Expand]Forms and User Controls
  [Expand]Messages, Notifications and Dialogs
  [Collapse]Editors and Simple Controls
   [Collapse]Simple Editors
    [Expand]Included Components
    [Expand]Editors Structure
    [Collapse]Editors Features
      Text Editing Overview
     [Expand]Mask Editors Overview
     [Expand]Formatting and Parsing Values
     [Expand]Editor Buttons Overview
     [Expand]Dropdown Editors Overview
      Image Editing Menu
     [Expand]Data Binding Overview
     [Expand]Appearance Customization
     [Collapse]Miscellaneous Features
       Batch Modifications
       Validation
    [Expand]Member Tables
    [Expand]Examples
   [Expand]Lookup Editors
   [Expand]Token Edit Control
   [Expand]Breadcrumb Edit Control
   [Expand]Range Control
   [Expand]Image Slider
    Camera Control
  [Expand]Ribbon, Bars and Menu
  [Expand]Application UI Manager
  [Expand]Docking Library
  [Expand]Data Grid
  [Expand]Vertical Grid
  [Expand]Pivot Grid
  [Expand]Tree List
  [Expand]Chart Control
  [Expand]Diagrams
  [Expand]Gauges
  [Expand]Map Control
  [Expand]Scheduler
  [Expand]Spreadsheet
  [Expand]Rich Text Editor
  [Expand]Spell Checker
  [Expand]Form Layout Managers
  [Expand]Navigation Controls
  [Expand]Printing-Exporting
  [Expand]PDF Viewer
   Reporting
  [Expand]Snap
  [Expand]TreeMap Control
 [Expand]Common Features
  Get More Help
 [Expand]API Reference
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]WPF Controls
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Document Server
[Expand]Reporting
[Expand]Report Server
[Expand]Dashboard
[Expand]eXpressApp Framework
[Expand]CodeRush
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation

Validation

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.

Expanded 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:

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.

Expanded 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:

 

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.

How would you rate this topic?​​​​​​​