package uk.co.wingpath.gui;

/**
* The purpose of this interface is to ensure that the text entered by
* the user in a table cell is valid (for example, that it's in the proper
* format) before allowing the user to navigate out of the table cell.
* <p>To do this, clients create an implementation of <code>TableVerifier</code>
* and, using <code>WCellEditor</code>'s <code>setVerifier</code> method,
* attach an instance of their implementation to the <code>WCellEditor</code>
* whose input they want to validate.
* <p>Before the user is allowed to move out of the table cell,
* the verifier's <code>verify</code> method is
* called, with the {@code isChanging} parameter set to {@code false}.
* The move is allowed only if that method returns a non-null value.
* <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 TableVerifier
{
    /**
    * 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).
    * @param value the user-entered value to be checked.
    * @param row the table row of the cell being edited.
    * @param col the table column of the cell being edited.
    * @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, int row, int col, boolean isChanging);
}