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.client.foundation.widget.input.support.*;
import com.temp.shared.*;
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:
 * <p/>
 * <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>
 * <p/>
 * ** - 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 FormEngineMember, HasName, 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);

    // Callable anytime:

    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:

    /**
     * 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();

    Widget getInputWidget();

    InputWidgetChangeFilter<T> getInput();

    InputWidgetValidator<T> getValidator();

    Widget getLabelLabel();

    Widget getExtendedLabel();

    Widget getExampleLabel();

    Widget getErrorLabel();

    Widget getHelpWidget();
}