/*******************************************************************************
 * Copyright (c) 2005, 2006 IBM Corporation and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 * Port to the D programming language:
 *     Frank Benoit <benoit@tionex.de>
 *******************************************************************************/

module dwtx.core.commands.State;

import dwtx.core.commands.common.EventManager;
import dwtx.core.internal.commands.util.Util;
import dwtx.core.commands.IStateListener;

import dwt.dwthelper.utils;

/**
 * <p>
 * A piece of state information that can be shared between objects, and might be
 * persisted between sessions. This can be used for commands that toggle between
 * two states and wish to pass this state information between different
 * handlers.
 * </p>
 * <p>
 * This state object can either be used as a single state object shared between
 * several commands, or one state object per command -- depending on the needs
 * of the application.
 * </p>
 * <p>
 * Clients may instantiate or extend this class.
 * </p>
 *
 * @since 3.2
 */
public class State : EventManager {

    /**
     * The identifier of the state; may be <code>null</code> if it has not
     * been initialized.
     */
    private String id;

    /**
     * The value held by this state; may be anything at all.
     */
    private Object value;

    /**
     * Adds a listener to changes for this state.
     *
     * @param listener
     *            The listener to add; must not be <code>null</code>.
     */
    public void addListener(IStateListener listener) {
        addListenerObject(cast(Object)listener);
    }

    /**
     * Disposes of this state. This allows the state to unregister itself with
     * any managers or as a listener.
     */
    public void dispose() {
        // The default implementation does nothing.
    }

    /**
     * Notifies listeners to this state that it has changed in some way.
     *
     * @param oldValue
     *            The old value; may be anything.
     */
    protected final void fireStateChanged(Object oldValue) {
        final Object[] listeners = getListeners();
        for (int i = 0; i < listeners.length; i++) {
            IStateListener listener = cast(IStateListener) listeners[i];
            listener.handleStateChange(this, oldValue);
        }
    }

    /**
     * Returns the identifier for this state.
     *
     * @return The id; may be <code>null</code>.
     */
    public final String getId() {
        return id;
    }

    /**
     * The current value associated with this state. This can be any type of
     * object, but implementations will usually restrict this value to a
     * particular type.
     *
     * @return The current value; may be anything.
     */

    public Object getValue() {
        return value;
    }

    /**
     * Removes a listener to changes from this state.
     *
     * @param listener
     *            The listener to remove; must not be <code>null</code>.
     */

    public void removeListener(IStateListener listener) {
        removeListenerObject(cast(Object)listener);
    }

    /**
     * Sets the identifier for this object.  This method should only be called
     * by the command framework.  Clients should not call this method.
     *
     * @param id
     *            The id; must not be <code>null</code>.
     */
    public void setId(String id) {
        this.id = id;
    }

    /**
     * Sets the value for this state object.
     *
     * @param value
     *            The value to set; may be anything.
     */
    public void setValue(Object value) {
        if (!Util.equals(this.value, value)) {
            final Object oldValue = this.value;
            this.value = value;
            fireStateChanged(oldValue);
        }
    }
}