package alecmce.anim
{
	import org.osflash.signals.ISignal;

	/**
	 * Describes an Animation in general terms.
	 */
	public interface Anim
	{

		/**
		 * attempt to play the animation (equivalent to setting speed = 1)
		 *
		 * @return Whether play is successful. It will fail if the Anim is already atEnd
		 */
		function play():Boolean;

		/**
		 * stop playing the animation
		 */
		function stop():void;

		/**
		 * attempt to play the animation in reverse (equivalent to speed = -1)
		 *
		 * @return Whether reverse is successful. It will fail if the Anim is already atStart
		 */
		function reverse():Boolean;

		/**
		 * @return the current speed of the animation
		 */
		function get speed():Number;

		/**
		 * set the speed of the animation. Speed is understood to be the change
		 * of proportion per frame
		 *
		 * @param value A value between -1 and 1
		 */
		function set speed(value:Number):void;

		/*
		 * @return the position of the animation between start and end as a proportion
		 */
		function get proportion():Number;

		/**
		 * set the position of the animation between start and end as a proportion
		 *
		 * @param value A value between 0 and 1
		 */
		function set proportion(value:Number):void;

		/**
		 * @return A signal which dispatches the Anim instance when the animation reaches
		 * the end of the animation (when proportion == 1)
		 */
		function get atEnd():ISignal;

		/**
		 * @return A signal which dispatches the Anim instance when the animation reaches
		 * the start of the animation (when proportion == 0)
		 */
		function get atStart():ISignal;

	}
}