package uk.co.wingpath.gui;

import javax.swing.*;
import javax.swing.event.*;
import javax.swing.text.*;
import java.awt.*;
import java.awt.event.*;
import java.util.*;
import uk.co.wingpath.event.*;
import uk.co.wingpath.event.Event;

/**
* This interface must be implemented by any text component using a
* {@link MirrorField} to provide alternative editing of the component value.
* <p>A {@code MirroredField} may be in one of three states with respect to
* the mirror:
* <ul>
*   <li>The mirrored field is not associated with the mirror.
*   The text component should call
*   {@link MirrorField#setMirrored MirrorField.setMirrored} when the user
*   selects the text component in order to associate itself with the mirror.
*   <li>The text component is handling the editing, with changes copied to the
*   mirror field by calling
*   {@link MirrorField#displayValue MirrorField.displayValue}.
*   <li>The mirror field is handling the editing. The mirror will call the
*   methods defined by this interface to notify the mirrored field of changes
*   made by the user.
* </ul>
* <p>Editing using the mirror is finished when the mirror loses focus or the
* user presses Enter, Tab or Escape. If the user presses Escape, the mirror
* will call {@link #resetValue resetValue}, otherwise the mirror will call
* {@link #saveValue saveValue}. The text component is no longer
* associated with the mirror after resetValue or saveValue has been
* called, although if the user switches focus back to the text component
* it may re-associate itself.
*/
public interface MirroredField
{
    /**
    * Called by the mirror when the user ends the edit by moving focus away
    * from the mirror, or by pressing Enter or Tab.
    * @param val the final value entered by the user.
    * The value will have been checked for validity (by calling the verifier
    * obtained by calling {@link #getVerifier getVerifier}), and it should be
    * saved by the mirrored field.
    */
    void saveValue (String val);

    /**
    * Called by the mirror when the user has ended an edit by pressing Enter,
    * Tab or Escape (i.e. not by moving the focus elsewhere).
    */
    void restoreFocus ();

    /**
    * Called by the mirror when the user ends the edit by pressing the
    * Escape key.
    * The mirrored field should restore its original value, and also return it.
    * @return the original value.
    */
    String resetValue ();

    /**
    * Gets the verifier for the field being edited.
    * @return the verifier, or null if there is no verifier for the field.
    */
    Verifier getVerifier ();

    /**
    * Gets the label to be used for the mirror field.
    * @return the mirror label.
    */
    String getMirrorLabel ();
}