Validation
- 8 minutes to read
The vertical grids (VGridControl and PropertyGridControl) support the validation mechanism that allows the data being entered by end-users to be checked. If the new values violate specific restrictions you can indicate the error(s). You can implement validation rules for individual cells and/or records. Record validation is only supported for the VGridControl.
It’s also possible to implement a validation mechanism for in-place editors. However, this technique is mostly applicable to standalone editors. See the Validation topic for more information.
Validating cells
This method allows you to impose specific restrictions on individual cells. If invalid data is entered you can prevent an end-user from leaving the cell until data is corrected.
When a cell’s value is modified and an end-user tries to leave this cell, the VGridControlBase.ValidatingEditor event fires. You can handle this event to provide your validation criteria. For instance, you can check whether the entered value is greater than a specific value, that it falls within a particular range, belongs to some value list, etc. If the cell’s value meets the custom criteria, set the event’s Valid parameter to true. Otherwise, you can set it to false. The initial value of the Valid parameter is determined by the result of the automatic editor’s validation performed by the in-place editor’s BaseEdit.DoValidate method. Note that if the parameter is set to false, the cell remains focused by default. This forces the end-user to correct the value entered.
The value being validated can be accessed via the event’s Value parameter. If the value does not meet your criteria, you can correct the value manually right within your VGridControlBase.ValidatingEditor event handler. For this purpose, you should assign the desired value to the Value parameter. Set the Valid parameter to true to allow focus to be moved from the cell. Or you can set the parameter to false in order to further process the issue via the VGridControlBase.InvalidValueException event (see below).
The VGridControlBase.ValidatingEditor event is not raised if changing cell values via code.
If the Valid parameter is set to false, the grid will display an error icon (
) within the cell. When hovering over the error icon a descriptive hint (“Invalid Value”) is displayed. To provide a custom error description, assign the desired string to the event’s ErrorText parameter.
If you need to prevent error icons from being displayed within cells or you need to display a message box instead of the error icons, you can handle the VGridControlBase.InvalidValueException event. This event fires in all cases when the entered (or assigned via code) value cannot be accepted by the control or underlying data source.
In some cases you may want to display error icons for several cells at once. This lets you indicate that the current cell value conflicts with other cells and the end-user has to correct values in one or more of these cells. To display an error icon for a cell, call the VGridControlBase.SetRowError method. The string to be displayed within the error tooltip is passed to this method as a parameter.
The VGridControlBase.PostEditor and VGridControlBase.CloseEditor methods allow you to initiate validation for the currently active editor. You can get that editor using the VGridControlBase.ActiveEditor property. If validation is a success, these methods will save the current value to the bound data source.
Example - Validating cells
The following example prohibits assignment of invalid values to “Department Budget” child rows. The cell’s value should be no greater than 100,000. The VGridControlBase.ValidatingEditor event is handled to check the entered value’s validity. The VGridControlBase.InvalidValueException event is handled to display an exception message box if an invalid value is assigned. In this instance, the VGridControlBase.HideEditor method is called to discard the changes made and destroy the cell’s editor.
using DevExpress.XtraVerticalGrid;
using DevExpress.XtraEditors.Controls;
private void vGridControl1_ValidatingEditor(object sender,
BaseContainerValidateEditorEventArgs e) {
VGridControl vGrid = sender as VGridControl;
if (vGrid.FocusedRow.Name == "rowAnatomy" ||
vGrid.FocusedRow.Name == "rowBusiness" ||
vGrid.FocusedRow.Name == "rowDesign" ||
vGrid.FocusedRow.Name == "History")
if (Convert.ToInt32(e.Value) > 100000) e.Valid = false;
}
private void vGridControl1_InvalidValueException(object sender,
InvalidValueExceptionEventArgs e) {
VGridControl vGrid = sender as VGridControl;
e.ExceptionMode = ExceptionMode.DisplayError;
e.WindowCaption = "Input Error";
e.ErrorText = "The value should be less than 100000";
// Destroying the editor and discarding the wrong changes made within the edited cell
vGrid.HideEditor();
}
Validating records
In the VGridControl, you can implement the validation procedure for entire records (not for individual cells). In this case, an end-user is not able to move away from the current record unless the data is correct but it’s possible to freely move focus between cells within the record.
To check the validity of data in records, handle the VGridControlBase.ValidateRecord event. This event fires when the current record has been modified and it’s about to be saved to the underlying data source. For instance, this takes place when an end-user makes an attempt to move focus to another record or when the VGridControlBase.UpdateFocusedRecord method is called.
The event’s RecordIndex parameter allows you to identify the record being processed. To obtain cell values, you can use the VGridControlBase.GetCellValue method. After cell values have been obtained, you can verify whether the values meet your validity criteria. If a record fails validation, set the event’s Valid parameter to false. Otherwise, leave the Valid parameter set to true.
By default, if the Valid parameter is set to false, the grid displays an error message box:
Clicking the Yes button returns focus to the record. This allows the end-user to correct the record’s values. If the No button is clicked, the record’s changes are discarded and focus can be moved away from the record. Note that the rollback only occurs if objects that represent records implement the IEditableObject interface.
It is possible to provide an additional error description via the event’s ErrorText parameter. The string assigned to this parameter will be displayed in the error message box followed by the “Do you want to correct the value?” string.
Sometimes you may want to indicate the cells contain invalid data to the end-user. For that purpose, call the VGridControlBase.SetRowError method with the column and error description as parameters. As a result, the corresponding cell displays an error icon (). Pointing to the icon invokes a hint with the specified error description.
If the Valid parameter is set to false, the VGridControlBase.InvalidRecordException event is raised after your VGridControlBase.ValidateRecord event handler has been completed. The VGridControlBase.InvalidRecordException event allows you to override the default error presentation (displaying the error message box). It provides an ExceptionMode parameter which can be used to specify how to respond to the error.
The VGridControlBase.InvalidRecordException event also occurs when the validated record cannot be saved to the bound data source due to database restrictions. In this case, an exception is usually raised by the data source.
Example - Validating records
Assume that the vertical grid contains two rows: “OrderDate” and “RequiredDate”. The value in the first row must be less than the value in the second one. So we need to validate their values in a record when it is about to be saved to the data source. For this purpose, the VGridControlBase.ValidateRecord event is handled.
If the record fails validation, we set errors for the rows with corresponding descriptions using the VGridControlBase.SetRowError method. The descriptions will be displayed when the mouse cursor hovers over the error icons.
The VGridControlBase.InvalidRecordException event is handled in order to suppress displaying the default error message box.
The following image shows a vertical grid after a record fails validation.
using DevExpress.XtraVerticalGrid.Events;
private void vGridControl1_ValidateRecord(object sender, ValidateRecordEventArgs e) {
VGridControl vGrid = sender as VGridControl;
// Get the value of the first row.
DateTime value1 = Convert.ToDateTime(vGrid.GetCellValue(editorRow2,
e.RecordIndex));
// Get the value of the second row.
DateTime value2 = Convert.ToDateTime(vGrid.GetCellValue(editorRow3,
e.RecordIndex));
if (value1 >= value2) {
e.Valid = false;
// Set errors with specific descriptions for the rows.
vGrid.SetRowError(editorRow2.Properties,
"The value must be less than Required Date");
vGrid.SetRowError(editorRow3.Properties,
"The value must be greater than Order Date");
}
}
private void vGridControl1_InvalidRecordException(object sender,
InvalidRecordExceptionEventArgs e) {
// Suppress displaying the error message box.
e.ExceptionMode = DevExpress.XtraEditors.Controls.ExceptionMode.NoAction;
}