gtween.as

Actionscript - Great effect libraries for Actionscript Flash/Air

/** GDS:
- reversed tweens don't reinit after delay (because they've already shifted to their end position)
- reversed needs to be set after all properties, because it immediately sets position to avoid flickering.
- rewrite ticker logic to make it more publicly accessible?
- add clone back in?
- finish prep for player 10.
**/

/**
* GTween by Grant Skinner. Aug 15, 2008
* Visit www.gskinner.com/blog for documentation, updates and more free code.
*
*
* Copyright (c) 2008 Grant Skinner
* 
* Permission is hereby granted, free of charge, to any person
* obtaining a copy of this software and associated documentation
* files (the "Software"), to deal in the Software without
* restriction, including without limitation the rights to use,
* copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the
* Software is furnished to do so, subject to the following
* conditions:
* 
* The above copyright notice and this permission notice shall be
* included in all copies or substantial portions of the Software.
* 
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
* OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
* WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
* OTHER DEALINGS IN THE SOFTWARE.
**/

package com.gskinner.motion {
	
	import flash.events.Event;
	import flash.events.EventDispatcher;
	import flash.events.IEventDispatcher;
	import flash.utils.Dictionary;
	
	
	/**
	* This event is dispatched each time the tween updates properties on its target.
	* It will be dispatched each "tick" during the TWEEN.
	*
	* @eventType flash.events.Event
	**/
	[Event(name="change", type="flash.events.Event")]
	/**
	* Dispatched when a tween copies its initial properties and starts tweening. In tweens with a delay of 0, this event will
	* fire immediately when it starts playing. In tweens with a delay set, this will fire when the delay state is ended, and the tween state is entered.
	*
	* @eventType flash.events.Event
	**/
	[Event(name="init", type="flash.events.Event")]
	/**
	* Dispatched when a tween ends (its position equals its duration).
	*
	* @eventType flash.events.Event
	**/
	[Event(name="complete", type="flash.events.Event")]
	
	/**
	* <b>GTween ©2008 Grant Skinner, gskinner.com. Visit www.gskinner.com/libraries/gtween/ for documentation, updates and more free code. Licensed under the MIT license - see the source file header for more information.</b>
	* <hr>
	* GTween is a light-weight instance oriented tween engine. This means that you instantiate tweens for specific purposes, and then reuse, update or discard them.
	* This is different than centralized tween engines where you "register" tweens with a global object. This provides a more familiar and useful interface
	* for object oriented programmers.
	* <br/><br/>
	* In addition to a more traditional setProperty/setProperties tweening interface, GTween also provides a unique proxy interface to tween and access properties of target objects
	* in a more dynamic fashion. This allows you to work with properties directly, and mostly ignore the details of the tween. The proxy "stands in"
	* for your object when working with tweened properties. For example, you can modify end values (the value you are tweening to), in the middle of a tween.
	* You can also access them dynamically, like so:
	* <br/><br/>
	* <code>mySpriteTween.proxy.rotation += 50;</code>
	* <br/><br/>
	* Assuming no end value has been set for rotation previously, the above example will get the current rotation from the target, add 50 to it, set it as the end
	* value for rotation, and start the tween. If the tween has already started, it will adjust for the new values. This is a hugely powerful feature that
	* requires a bit of exploring to completely understand. See the documentation for the "proxy" property for more information.
	* <br/><br/>
	* For a light-weight engine (<4.5kb), GTween boasts a number of advanced features:<UL>
	* <LI> three timing modes: frame based, time based, and hybrid
	* <LI> works with any numeric properties on any object (not just display objects)
	* <LI> sequenced tweens using .nextTween
	* <LI> pause and resume individual tweens or all tweens
	* <LI> jump directly to the end or beginning of a tween with .end() or .beginning()
	* <LI> jump to any arbitrary point in the tween with .position
	* <LI> auto hide for alpha tweens, sets visible to false when alpha is 0 or less with .autoVisible set to true
	* <LI> smart tweening for rotation (rotates in the shortest direction) with .autoRotation and .rotationProperties
	* <LI> property snapping (rounding) with .snapping and .snappingProperties
	* <LI> complete, init, and change events
	* <LI> smart garbage collector interactions (prevents collection while active, allows collection if target is collected)
	* <LI> uses any standard ActionScript tween functions
	* <LI> support for tweening objects like colorTransform and matrix that need to be reassigned to a property
	* <LI> easy to set up in a single line of code
	* <LI> can repeat or reflect a tween specified number of times
	* <LI> .reverse() method will reverse a linear tween seamlessly, respecting repeat and reflect
	* <LI> deterministic, so setting a position on a tween will (almost) always result in predictable results
	* <LI> very powerful sequencing capabilities in conjunction with GTweenTimeline.
	* </UL>
	* Also see GTweenFilter and GTweenTimeline for more advanced functionality, or GTweensy for a more lightweight engine.
	*
	* <hr/>
	* <b>Beta 5 updates (Feb 1, 2009):</b><br/>
	* Beta 5 constitutes a major rewrite of GTween. Much of the API has been changed, and it is recommended that you read the API documents
	* to familiarize yourself with the new capabilities. The following list might not be exhaustive.
	* <ul>
	* <li> low level rewrite of positioning logic, to make position handling fully deterministic
	* <li> removed .clone();
	* <li> removed .useSetSize and related functionality
	* <li> removed activate event
	* <li> removed .addProgressPoint functionality (use GTweenTimeline with .addCallback instead)
	* <li> removed .addChild and related functionality (use GTweenTimeline with .addTween instead)
	* <li> removed .assignmentTarget and .assignmentProperty in favour of .setAssignment()
	* <li> removed .autoReverse property, use repeat and reflect instead
	* <li> renamed BEGINNING, DELAY_PHASE, and TWEEN_PHASE to START, DELAY, and TWEEN respectively
	* <li> renamed .useSmartRotation to .autoRotation
	* <li> renamed .autoHide to .autoVisible
	* <li> renamed .useSnapping to .snapping
	* <li> added .repeat property, which lets you specify the number of times the tween should repeat
	* <li> added .reflect, which causes the tween to play backwards when it repeats
	* <li> added .reversed property, which causes the tween to play backwards
	* <li> added .getProperties(), which returns a hash table of end values
	* <li> added .setStartProperties(), allows you to manually specify the start values
	* <li> added .getStartProperties(), which returns the start values
	* <li> added .lockStartProperties, which prevents start values from re-initing
	* <li> added .tweenPosition, which provides a calculate position between 0 and duration
	* <li> added .setPosition, which allows you to specify whether to suppress events when manually setting position
	* <li> the .state property is now calculated on demand
	* <li> reduced size to under 4.5kb for GTween
	* </ul>
	**/
	
	public class GTween extends EventDispatcher {
		
	// static interface:
		/** @private **/
		protected static var _timingMode:String;
		/** @private **/
		protected static var _timeInterval:uint = 40;
		/** @private **/
		protected static var _activeTicker:ITicker;
		/** @private **/
		protected static var activeTweens:Dictionary = new Dictionary(); // keeps active tweens in memory
	
		/** Constant for the TIME timingMode. **/
		public static const TIME:String = "time";
		/** Constant for the FRAME timingMode. **/
		public static const FRAME:String = "frame";
		/** Constant for the HYBRID timingMode. **/
		public static const HYBRID:String = "hybrid";
		/** Constant for the START state. **/
		public static const START:String = "start";
		/** Constant for the DELAY state. **/
		public static const DELAY:String = "delay";
		/** Constant for the TWEEN state. **/
		public static const TWEEN:String = "tween";
		/** Constant for the END state. **/
		public static const END:String = "end";
		
		/** Setting this to true pauses all tween instances. This does not affect individual tweens' .paused property. **/
		public static var pauseAll:Boolean=false;
		
		/** Specifies the default easing function to use with new tweens. If null, GTween.linearEase will be used. **/
		public static var defaultEase:Function;
		
		/** A hash table specifying properties that should be affected by autoRotation. **/
		public static var rotationProperties:Object = {rotation:true,rotationX:true,rotationY:true,rotationZ:true};
		
		/** A hash table specifying properties that should have their value rounded (snapped) before being applied. This can be toggled for each tween instance basis with the .snapping property. **/
		public static var snappingProperties:Object = {x:true,y:true};
		
		/**
		* Indicates how GTween should deal with timing. This can be set to GTween.TIME, GTween.FRAME, or GTween.HYBRID.
		* <br/><br/>
		* In frame mode, GTween will update once every frame, and all positional values are specified in frames (duration, position, delay, etc).
		* <br/><br/>
		* In time mode, updates will occur at an interval specified by the timeInterval property, independent of the frame rate, and all positional values are
		* specified in seconds.
		* <br/><br/>
		* In hybrid mode, all updates occur on a frame, but all positional values are specified in seconds. Each frame the tween will calculate it's position based on the elapsed time.
		* This offers lower CPU usage, and a more familiar time-based interface, but can result in choppy animations in high CPU situations.
		* <br/><br/>
		* The hybrid mode generally provides the smoothest results. The frame mode makes it easy to synch tweens with timeline animations.
		* You can change modes at any time, but existing tweens will continue to use the mode that was active when they were created.
		**/
		public static function get timingMode():String {
			return _timingMode;
		}
		public static function set timingMode(value:String):void {
			value = (value == FRAME || value == TIME) ? value : HYBRID;
			if (value == _timingMode) { return; }
			_timingMode = value;
			if (_timingMode == TIME) {
				_activeTicker = new TimeTicker();
				(_activeTicker as TimeTicker).interval = _timeInterval/1000;
			} else if (_timingMode == FRAME) {
				_activeTicker = new FrameTicker();
			} else {
				_activeTicker = new HybridTicker();
			}
		}
		
		/**
		* Sets the time in milliseconds between updates when timingMode is set to GTween.TIME ("time"). Setting this to a lower number
		* will generally result in smoother animations but higher CPU usage. Defaults to 40ms (~25 updates per second).
		**/
		public static function get timeInterval():uint {
			return _timeInterval;
		}
		public static function set timeInterval(value:uint):void {
			_timeInterval = value;
			if (_activeTicker is TimeTicker) { (_activeTicker as TimeTicker).interval = _timeInterval/1000; }
		}
		
		/** The currently active Ticker object. **/
		public static function get activeTicker():ITicker {
			if (_timingMode == null) { timingMode = HYBRID; }
			return _activeTicker;
		}
		
		/** The default easing function used by GTween. **/
		public static function linearEase(t:Number, b:Number, c:Number, d:Number):Number {
			return t;
		}
	// END static interface.
	
	
	// public properties:
		/**
		* Indicates whether the tween should automatically play when an end value is changed.
		**/
		public var autoPlay:Boolean = true;
		
		/**
		* When true, the tween will always rotate in the shortest direction to reach an end rotation value.
		* For example, rotating from 355 degress to 5 degrees will rotate 10 degrees clockwise with .autoRotation set to true.
		* It would rotate 350 degrees counter-clockwise with .autoRotation set to false. This affects all properties specified
		* in the static .rotationProperties hash table.
		**/
		public var autoRotation:Boolean = false;
		
		/**
		* Indicates whether the target's visible property should automatically be set to false when its alpha value is tweened to 0 or less.
		* Only affects objects with a visible property.
		**/
		public var autoVisible:Boolean = true;
		
		/**
		* Allows you to associate arbitrary data with your tween. For example, you might use this to reference specific data when handling events from tweens.
		**/
		public var data:*;
		
		/**
		* The length of the tween in frames or seconds (depending on the timingMode). Setting this will also update any child transitions
		* that have synchDuration set to true.
		**/
		public var duration:Number=1;
		
		/**
		* The easing function to use for calculating the tween. This can be any standard tween function, such as the tween functions in fl.motion.easing.* that come with Flash CS3.
		* New tweens will have this set to the defaultTween. Setting this to null will cause GTween to throw null reference errors.
		**/
		public var ease:Function=linearEase;
		
		/**
		* Specifies another GTween instance that will have paused=false called on it when this tween completes.
		**/
		public var nextTween:GTween;
		
		/**
		* Indicates whether the tween should use the reflect mode when repeating. If reflect is set to true, then the tween will play backwards on every other repeat.
		* This has similar effects to reversed, but the properties are exclusive of one another.
		* For instance, with reversed set to false, reflected set to true, and a repeat of 1, the tween will play from start to end, then repeat and reflect to play from end to start.
		* If in the previous example reversed was instead set to true, the tween would play from end to start, then repeat and reflect to play from start to end.
		* Finally, with reversed set to false, reflected set to false, and a repeat of 1, the tween will play from start to end, then repeat from start to end
		**/
		public var reflect:Boolean=false;
		
		/**
		* The number of times this tween will repeat. If 0, the tween will only run once. If 1 or more, the tween will repeat that many times. If -1, the tween will repeat forever.
		**/
		public var repeat:int=0;
		
		/**
		* If set to true, tweened values specified by snappingProperties will be rounded (snapped) before they are assigned to the target.
		**/
		public var snapping:Boolean = false;
		
		
	// private properties:
		/** @private **/
		protected var startValues:Object;
		/** @private **/
		protected var endValues:Object;
		/** @private **/
		protected var inited:Boolean;
		/** @private **/
		protected var inTick:Boolean;
		/** @private **/
		protected var ticker:ITicker;
		/** @private **/
		protected var positionOffset:Number;
		/** @private **/
		protected var assignmentTarget:Object;
		/** @private **/
		protected var assignmentProperty:String;
		/** @private **/
		protected var _position:Number=0;