/*
Copyright (c) 2006, Geomatics and Cartographic Research Centre, Carleton 
University All rights reserved.

Redistribution and use in source and binary forms, with or without 
modification, are permitted provided that the following conditions are met:

 - Redistributions of source code must retain the above copyright notice, 
   this list of conditions and the following disclaimer.
 - Redistributions in binary form must reproduce the above copyright notice,
   this list of conditions and the following disclaimer in the documentation
   and/or other materials provided with the distribution.
 - Neither the name of the Geomatics and Cartographic Research Centre, 
   Carleton University nor the names of its contributors may be used to 
   endorse or promote products derived from this software without specific 
   prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE 
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
POSSIBILITY OF SUCH DAMAGE.

$Id$
*/
package ca.carleton.gcrc.atlas;

import java.lang.IllegalArgumentException;

/**
 * Interface for allowing an <code>FadeTimerTask</code> element to access and update
 * a variable controlled by the parent or to notify its parent
 * (the object that created the timer task) of various events while it carries out its task.
 * The variable being controlled by the fade timer task is a Number (see the math routines
 * in FadeTimerTask for the current set of implemented Number subclasses).
 * <p>
 * The fade timer task can be used to manage multiple scalar values by associating
 * different timer identifiers with individual scalars so that the variable access and update
 * functions can determine the meaning of a specific function call.
 * <p>
 * See <code>FadeTimerTask</code>.
 * 
 * @author Glenn Brauen
 */
public interface FadeTimerParent<K> {
	/**
	 * The timer task iteration period (in milliseconds).
	 */
	public final int TIMER_PERIOD = 20; // in milliseconds
	
	
	/**
	 * Interface used by the fade timer task to get the current value of the variable
	 * being adjusted by the
	 * fade timer identified by timerId_.
	 * 
	 * @param timerId_ the timer identifier associated with this variable being controlled.
	 * @return the current value of the variable being controlled.
	 */
	public Number getCurrentFadeTimerValue(K timerId_) throws IllegalArgumentException;
	
	/**
	 * Interface used by the timer task to set a new value for the variable being adjusted by
	 * the fade timer identified by timerId_.
	 * 
	 * @param newValue_ new value for the variable.
	 * @param timerId_ identifier for the timer.
	 */
	public void setCurrentFadeTimerValue(Number newValue_, K timerId_) throws IllegalArgumentException;
	
	/**
	 * Interface used by the timer task to notify the parent that the fade timer's operation is done.
	 * The parent can use this as a trigger for application-specific handling that should only occur
	 * after the fade is complete (e.g. unload a sound after it has faded to silence).
	 */
	public void fadeCompleted(K timerId_);
	
	/**
	 * Interface used by the timer task to notify the parent that all fade timers have completed
	 * their operation.  The parent can use this as a trigger to destroy the timer task.
	 */
	public void allFadeTimersFinished();
} // FadeTimerParent