package uk.co.wingpath.gui;

/**
* The purpose of this interface is to ensure that the text entered by
* the user is valid (for example, that it's in the proper format) before
* allowing the user to navigate out of the text field.
* <p>To do this, clients create an implementation of <code>Verifier</code>
* and, using <code>WTextField</code>'s <code>setVerifier</code> method,
* attach an instance of their implementation to the <code>WTextField</code>
* whose input they want to validate.
* <p>Before focus is transferred to another Swing component
* that requests it, the verifier's <code>verify</code> method is
* called, with the {@code isChanging} parameter set to {@code false}.
* Focus is transferred only if that method returns a non-null value.
* <p>The verifier is also called with {@code isChanging} set to {@code false}
* if the user presses Enter, or if the
* <code>WTextField</code>'s <code>checkValue</code> method is called.
* <p>The verifier is called with {@code isChanging} set to {@code true} if
* the user changes the value, but has not yet finished editing. This is done
* to enable the verifier to clear any error message it may have displayed.
* The return value from the verifier is ignored in this case.
*/
public interface Verifier
{
    /**
    * Checks whether the value entered by the user is valid.
    * <p>If the value is not valid, the method should display an
    * explanatory error message and return <code>null</code>.
    * <p>If the value is valid, the method should return the value, possibly
    * put into a standard form (e.g. a number might have leading zeros
    * stripped).
    * The method may also store the value for its own purposes (rather than
    * using a value listener to be notified of the new value).
    * @param value the user-entered value to be checked.
    * @param isChanging whether the user is still changing the value.
    * @return the value, if the value is valid, <code>null</code>
    * otherwise.
    */
    String verify (String value, boolean isChanging);
}