package com.temp.client.foundation.widget.input;

import com.google.gwt.user.client.ui.*;
import com.temp.client.foundation.widget.input.fieldsupport.*;
import com.temp.shared.*;
import com.temp.shared.externalization.*;
import com.temp.shared.utils.*;

/**
 * An interface for an Input Field.
 * <p/>
 * Implementation should be able to be used directly or as a widget in a UI Binding file.
 * <p/>
 * It operates in two distinct states:
 * <p/>
 * <li>Builder Mode - Where properties of the final widget are specified (and parts of the widget are NOT accessable)</li>
 * <li>Run Mode - Where the parts of the Widget are accessable (and the specification properties are NOT changeable)</li>
 * <p/>
 * The transition between the states is one way ('Builder' to 'Run') and is a result of the call to 'init'.
 * <p/>
 * An Input Field has the following:
 *
 * <ul>
 * <li>Name</li>
 * <li>Base Value **,</li>
 * <li>Current Value **,</li>
 * <li>Changed State,</li>
 * <li>Errored State,</li>
 * <li>Enabled State,</li>
 * <li>Visibility State, and</li>
 * <li>Following Widgets:</li>
 * <ol>
 * <li>InputWidget</li>
 * <li>LabelLabel</li>
 * <li>ExtendedLabel</li>
 * <li>ExampleLabel</li>
 * <li>ErrorLabel</li>
 * <li>HelpWidget</li>
 * </ol>
 * </ul>
 *
 * ** - These values are "normalized" in both directions (to & from the underlying Input Widget(s)).
 * This means that a value set and then fetched may be different (however a value fetched, then set,
 * then fetched should match the original value fetched)! For String based input fields the normalization
 * is that leading and trailing whitespace is ignored and empty strings and nulls are substituted based
 * on direction ("" -> null when fetching from the underlying input widget, and null -> "" when setting
 * into the underlying input widget).  For non-String based input fields the normalization could appear
 * a bit strange, for example: CheckBox input fields will interpret null as false.
 *
 * @param <T> the data type returned by this InputField
 */
public interface InputField<T> extends HasName,
                                       Enableable,
                                       Visible
{
    interface ChangeListener<T2>
    {
        void changed( InputField<T2> field );
    }

    // Only callable in Builder Mode

    // For HasName - The Name MUST be set before the call to init (transition to run mode)

    InputField<T> name( String name );

    /**
     * The 'Builder' to 'Run' state transition method fully constructs/populates the InputField's Widget / container.
     * <p/>
     * Only callable ONCE and only in Builder Mode!
     *
     * @return this for method chaining
     */
    InputField<T> init( E13nResolver resolver );

    // Callable anytime

    boolean isRunMode();

    InputField<T> add( ChangeListener<T> changeListener );

    boolean remove( ChangeListener<T> changeListener );

    void removeAllChangeListeners();

    ValueValidator<T>[] getValidators();

    InputField<T> add( ValueValidator<T> validator );

    InputField<T> add( ValueValidator<T>... additionalValidators );

    // For Enableable

    InputField<T> enable();

    InputField<T> disable();

    // For Visible

    InputField<T> visible();

    InputField<T> cloak();

    InputField<T> invisible();

    // Only callable in Run Mode

    /**
     * Reset the value as if <code>setCurrentValue( null )</code> has been called.
     */
    void reset();

    /**
     * set the Current value and the "Base" value (the "Base" value is what "change" is determined from).
     * <p/>
     * Note: The value is "normalized" before giving it to the actual Input Widget
     *
     * @param value null OK
     * @return "normalized" round-tripped value (null possible) as if <code>getCurrentValue()</code> was called.
     */
    T setCurrentValue( T value );

    /**
     * Returned the "normalized" Current value.
     *
     * @return null possible
     */
    T getCurrentValue();

    /**
     * Returned the "normalized" Base value.
     *
     * @return null possible
     */
    T getBaseValue();

    /**
     * revert to the "Base" value
     */
    void revert();

    /**
     * Return if the Current Value is different than the Base Value
     */
    boolean isChanged();

    /**
     * Return if the Field has Focus (or null indicating that the Focus state is not tracked)
     */
    Boolean isFocused();

    /**
     * Return if the Current Value is rejected by any of the ValueValidator(s)
     */
    boolean isErrored();

    /**
     * Validate the Current Value, and "manage" the Error Label appropriately.
     * <p/>
     * Error Labels are set to a NBSP & Cloaked when the field is not in Error, and Visible w/ the appropriate E13n data when the field is in Error.
     *
     * @return true if <code>isErrored() == false</code>.
     */
    boolean validate();

    /**
     * Pull the Focus to this Field (return false if the field is "thought" to be currently un-focusable, e.g. Not Visible, Disabled, or has no Focusable components)
     */
    boolean setFocused();

    E13nResolver getE13nResolver();

    Widget getInputWidget();

    InputWidgetChangeFilter<T> getInput();

    InputWidgetValidator<T> getValidator();

    Widget getLabelLabel();

    Widget getExtendedLabel();

    Widget getExampleLabel();

    Widget getErrorLabel();

    Widget getHelpWidget();
}