gtweeny.as

Actionscript - Great effect libraries for Actionscript Flash/Air

/**
* GTweeny 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>GTweeny ©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>
	* GTweeny is the ultra lightweight younger sibling of GTween. It strips out secondary features
	* to deliver a robust tweening engine in less than 3kb.
	* <br/><br/>
	* It retains events, deterministic positioning, repeat counts, reflect, reverse, autoRotation, autoVisible, pausing, pausing all, jumping to the start or end, sequencing,
	* snapping, jumping to an arbitrary point in the tween, basic sequencing, delays, and interrupt handling.
	*
	* Specifically, the following is not part of GTweeny:<UL>
	* <li> all constants (START, DELAY, TWEEN, END, TIME, FRAME, HYBRID)
	* <li> timingMode (always uses HYBRID)
	* <li> timeInterval
	* <li> setAssignment
	* <li> proxy
	* <li> state
	* <li> getProperties
	* <li> setStartProperties
	* <li> getStartProperties
	* <li> lockStartProperties
	* <li> propertyTarget
	* </UL>
	**/
	
	public class GTweeny extends EventDispatcher {
		
	// static interface:
		/** @private **/
		protected static var activeTweens:Dictionary = new Dictionary(); // keeps active tweens in memory
		
		/** @private **/
		protected static var _ticker:HybridTicker;
		
		/** 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};
		
		/** The currently active Ticker object. **/
		public static function get ticker():HybridTicker {
			if (_ticker) { return _ticker; }
			return _ticker = new HybridTicker();
		}
		
		/** 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 the destination rotation.
		* 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:GTweeny;
		
		/**
		* 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 positionOffset:Number;
		/** @private **/
		protected var _position:Number=0;
		/** @private **/
		protected var _previousPosition:Number;
		/** @private **/
		protected var _tweenPosition:Number=0;
		/** @private **/
		protected var _previousTweenPosition:Number;
		/** @private **/
		protected var _target:Object;
		/** @private **/
		protected var _paused:Boolean=true;
		/** @private **/
		protected var _delay:Number=0;
		/** @private **/
		protected var _reversed:Boolean;
		
	// constructor:
		/**
		* Constructs a new GTween instance.
		*
		* @param target The object whose properties will be tweened. Defaults to null.
		* @param duration The length of the tween in frames or seconds depending on the timingMode. Defaults to 10.
		* @param properties An object containing destination property values. For example, to tween to x=100, y=100, you could pass {x:100, y:100} as the props object.
		* @param tweenProperties An object containing properties to set on this tween. For example, you could pass {ease:myEase} to set the ease property of the new instance. This also provides a shortcut for setting up event listeners. See .setTweenProperties() for more information.
		**/
		public function GTweeny(target:Object=null, duration:Number=10, properties:Object=null, tweenProperties:Object=null) {
			this.target = target;
			this.duration = duration;
			ease = defaultEase || linearEase;
			setProperties(properties);
			setTweenProperties(tweenProperties);
		}
		
	// public getter / setters:
		
		/**
		* Gets and sets the position in the tween in frames or seconds (depending on the timingMode). This value can be any number, and will be resolved to a tweenPosition value
		* prior to being applied to the tweened values. See tweenPosition for more information.
		* <br/><br/>
		* <b>Negative values</b><br/>
		* Values below 0 will always resolve to a tweenPosition of 0. Negative values can be used to set up a delay on the tween, as the tween will have to count up to 0 before initing.
		* <br/><br/>
		* <b>Positive values</b><br/>
		* Positive values are resolved based on the duration, repeat, reflect, and reversed properties.
		**/
		public function get position():Number {
			return _position;
		}
		public function set position(value:Number):void {
			setPosition(value,true);
		}
		
		/**
		* Indicates whether the tween is currently paused. See play() and pause() for more information.
		**/
		public function get paused():Boolean {
			return _paused;
		}
		public function set paused(value:Boolean):void {
			if (value == _paused) { return; }
			_paused = value;
			if (value) {
				ticker.removeEventListener("tick",handleTick);
			} else {
				ticker.addEventListener("tick",handleTick,false,0,true);
				if (repeat != -1 && _position >= duration*(repeat+1)) { position = 0; }
				else { updatePositionOffset(); }
			}
			setGCLock(!value);
		}
		
		/**
		* Returns the calculated absolute position in the tween. This is a deterministic value between 0 and duration calculated
		* from the current position based on the duration, repeat, reflect, and reversed properties.
		* <br/><br/>
		* For example, a tween with a position
		* of 5 on a tween with a duration of 3, and repeat set to true would have a tweenPosition of 2 (2 seconds into the first repeat).
		* The same tween with reflect set to true would have a tweenPosition of 1 (because it would be 2 seconds into the first repeat which is
		* playing backwards). With reflect and reversed set to true it would have a tweenPosition of 2.
		* <br/><br/>
		* Tweens with a position less than 0 will have a tweenPosition of 0. Tweens with a position greater than <code>duration*(repeat+1)</code>
		* (the total length of the tween) will have a tweenPosition equal to duration.
		**/
		public function get tweenPosition():Number {
			return _tweenPosition;
		}
		
		/**
		* The target object to tween. This can be any kind of object.
		**/
		public function get target():Object {
			return _target;
		}
		public function set target(value:Object):void {
			_target = (value === null) ? {} : value;
			inited = false;
		}
		
		/**
		* Indicates whether a tween should run in reverse. In the simplest examples this means that the tween will play from its end values to its start values.
		* See "reflect" for more information on how these two related properties interact. Also see reverse().
		**/
		public function get reversed():Boolean {
			return _reversed;
		}