Form controls in Apache OpenOffice always featured a simple type of validation for their value. For instance, for a numeric field you can specify minimum an maximum values (ValueMin and ValueMax). However, those validity constraints have some disadvantages:
- They are enforced as soon as the control loses the focus. That is, if you enter a number into a numeric field that is greater than the allowed maximum, then it is automatically corrected to be the maximum.
- They are enforced silently. There is no warning to the user, and no visual feedback at the moment the value is invalid, and not yet corrected. In particular, there is no explanation about why a certain input was (or will be) automatically corrected.
Apache OpenOffice features a mechanism for validating the content of form controls, at the time of user input.
The basic interface for this mechanism is XValidator:
|Methods of com.sun.star.form.validation.XValidator|
|isValid||This is the central method of a validator. It is able to decide, for a given value, whether it is valid or not. Note that there is no notion about the semantics of valid. This is in the responsibility of the concrete service implementing this interface.|
|explainInvalid||Explains, for a given value, why it is considered invalid. The explanation should be human-readable because other components are expected to present it to the user.|
|addValidityConstraintListener||Registers a new validity listener. As a basic idea, a validator can not be stateless: Depending on its current internal state, the validator can consider the very same value as valid or invalid. Such validator components should notify a change in their state, and thus a potential change in the validity of associated XValidatable instances, to all listeners registered with this method. The listeners are encouraged to re-validate whatever data is guarded by the validator.|
|removeValidityConstraintListener||Revokes a previously registered validity listener.|
A validator is to be used with a component that can be validated: XValidatable. This interface allows to set and to get a validator instance.
Until now, nothing has been said about form components. You may also note that nothing has been said about the data that is being validated. Though a value is passed to the isValid method, there is no explanation about where it originates from. In particular, the XValidatable does not specify a means to obtain its value.
This is where com.sun.star.form.validation.XValidatableFormComponent comes in. Note that it derives from XValidatable.
|Methods of com.sun.star.form.validation.XValidatableFormComponent|
|isValid||Determines whether the current value, as represented by the component, is valid. This is a shortcut to calling the validator's isValid method, with the current value of the component.|
|getCurrentValue||Specifies the current value, as represented by the component.
As an example, a TextField would return its text, while a DateField would return its date value.
|addFormComponentValidityListener||Adds a listener to observe the validity of the component. This validity is determined by two aspects: The current value of the component, and the validator's opinion about this value (and thus implicitly by the current validator of the component, which may also change). To be notified of changes in this composed validity, you need to register a XFormComponentValidityListener at the form component.|
|removeFormComponentValidityListener||Revokes a previously registered validity listener.|
Now, the overall picture for services and interfaces concerned with form control validation can be seen in the following figure:
Notice the ValidatableControlModel service: It specifies the basic functionality of form control models, which allow their current value to be validated against an external validator.
In Apache OpenOffice, there is one feature that uses the functionality introduced in this chapter: XML form documents. They are implemented using the interfaces and services from com.sun.star.xforms. In particular, an XForms binding (Binding) is a validator. This way, Apache OpenOffice form controls can be used to enter values for XForms DOM trees, respecting the restrictions imposed on those value as part of the XForms model.
|Content on this page is licensed under the Public Documentation License (PDL).|