|Visual Basic (Declaration)|
Public Class ValidationSettings Inherits Infragistics.Shared.SubObjectBase
public class ValidationSettings : Infragistics.Shared.SubObjectBase
The ValidationSettings class enacapsulates the validation functionality extended by the UltraValidator component. An instance of the class is extended to all controls on the same form as the associated UltraValidator, with the exception of Infragistics controls that support hosting embeddable editors. It is also extended to controls that are not typically associated with validation, such as a Panel control, since it is possible to derive these controls and add validation capabilities to them.
The Enabled property can be used to switch validation support on or off. The property is true by default, although no validation occurs for the associated control until one or more properties (besides Enabled) are explicitly set by the end developer.
Various kinds of validation can be realized through the ValidationSettings object, the simplest example being enforcement of a non-empty value for a control. This is accomplished by setting the IsRequired property to true; when a validation session is triggered, the current value of the property referenced by the ValidationPropertyName property is evaluated to determine whether it is logically empty, with the definition of "empty" being defined by the value of the EmptyValueCriteria property. For example, assume a ValidationSettings instance has been extended to a TextBox control, and the IsRequired property has been set to true. If the end user clears the text and tabs out of the control, the following sequence of events take place:
- The value of the Text property is obtained; since the ValidationPropertyName was left at its default value, it resolves to 'Text.
- The EmptyValueCriteria is used to determine whether the value of that property is considered empty; Since EmptyValueCriteria resolves to 'NullOrEmptyString' in lieu of an explicit setting, the value is determined to be empty.
- The Validating event fires, reporting the validation.
- Provided that no listener of the Validating event has set the IsValid property of the event arguments to true, the Action property is used to determine the course of action for a failed validation; in lieu of an explicit setting, the value resolves to 'Image'.
- The ValidationError event fires, reporting that the validation has failed.
- Provided that no listener of the ValidationError event has changed the notification action, an error image is displayed alongside the outer right edge of the TextBox.
- Since the RetainFocusOnError property was left at its default value of false, focus is allowed to shift to the next control in the tab order, but the error image remains until validity is reevaluated during the next validation session
Since validation criteria must often go beyond the simple case of merely enforcing non-emply values, the Condition property is exposed to provide the ability to customize the validation criteria. The property is of type ICondition, an existing Infragistics interface that has been used previously to implement row filtering in the UltraGrid control. Several concrete implementations exist in the Infragistics.Win namespace. The RangeCondition class can be used for basic range validation, i.e., to require that a value lies within the range determined by a MinimumValue and MaximumValue. The ContainedInListCondition class can be used to determine whether a value matches a value in a List, ideally suited for using a ValueList to define a universe of valid values. The OperatorCondition class, which defines many of the conditions used by UltraGrid's row filtering feature, can be used to implement a wide variety of validations, such as simple logical comparisons like 'equal', 'greater than', and 'less than', or more advanced ones like Regex or "wildcard" comparisons. The ConditionGroup class, which implements the IList interface, allows any number of ICondition implementations to be specified as the validation criteria, and also exposes a property which determines whether all conditions must pass or only one. Since the end developer might require validation criteria that is not covered by any of the above mentioned implementations, a custom interface implementation can be specified, and the interface itself only requires that one single method be implemented.
The properties which determine how the end user is notified of a failed validation are grouped under the NotificationSettings property; the custom object returned by that property exposes properties that make it easy to, for example, show an error image or MessageBox.
The ValidationTrigger property determines what event initiates a validation session. The default value, 'OnValidating', causes validation to happen in response to the control's Validating event (or, in the case where the entity being validated is an embeddable editor, the BeforeExitEditMode event). Validation can also be triggered by a change in the value of the property referenced by the ValidationPropertyName, when using the 'OnPropertyValueChanged' setting. Validation in response to user interaction can be suppressed altogether using the 'Programmatic' setting; in that case, validation is initiated only when the end developer explicitly calls the Validate method.
Validation functionality can be easily extended to an Infragistics control that hosts externally provided embeddable editors. This is accomplished by setting properties of the ValidationSettings instance extended to an editor provider control such as an UltraTextEditor or UltraComboEditor, and then assigning a reference to that editor provider control to (for example) an UltraGridColumn's EditorControl property. Cells in that column would then be validated in much the same way as the standalone provider control. Note that it is not recommended to use an editor provider control to both provide an editor, and also be used as a visible control with its own input capabilities.
An ErrorAppearance property is exposed to provide a way to visually depict that an embeddable editor value is currently invalid as defined by this instance's validation criteria. This appearance stands apart from the ValidationTrigger in that it is applied at all times when the value is invalid, and not switched on and off in response to the trigger. Note that the ErrorAppearance is only used by Infragistics editors, and is not applicable to non-Infragistics controls.
The ValidationGroup property makes it possible to arrange controls into logical groups for the purpose of temporarily disabling validation for the members of that group, or to programmatically trigger validation of each member.