gtween.as

Actionscript - Great effect libraries for Actionscript Flash/Air

		/** @private **/
		protected var _previousPosition:Number;
		/** @private **/
		protected var _tweenPosition:Number=0;
		/** @private **/
		protected var _previousTweenPosition:Number;
		/** @private **/
		protected var _target:Object;
		/** @private **/
		protected var _propertyTarget:Object;
		/** @private **/
		protected var _paused:Boolean=true;
		/** @private **/
		protected var _proxy:TargetProxy;
		/** @private **/
		protected var _delay:Number=0;
		/** @private **/
		protected var _reversed:Boolean;
		/** @private **/
		protected var _lockStartProperties: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 end 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 GTween(target:Object=null, duration:Number=10, properties:Object=null, tweenProperties:Object=null) {
			ticker = activeTicker;
			this.target = target;
			this.duration = duration;
			ease = defaultEase || linearEase;
			setProperties(properties);
			setTweenProperties(tweenProperties);
		}
		
	// public getter / setters:
		/**
		* The proxy object allows you to work with the properties and methods of the target object directly through GTween.
		* Numeric property assignments will be used by GTween as end values. The proxy will return GTween end values
		* when they are set, or the target's property values if they are not. Delete operations on properties will result in a deleteProperty
		* call. All other property access and method execution through proxy will be passed directly to the target object.
		* <br/><br/>
		* <b>Example 1:</b> Equivalent to calling myGTween.setProperty("scaleY",2.5):<br/>
		* <code>myGTween.proxy.scaleY = 2.5;</code>
		* <br/><br/>
		* <b>Example 2:</b> Gets the current rotation value from the target object (because it hasn't been set yet on the GTween), adds 100 to it, and then
		* calls setProperty on the GTween instance with the appropriate value:<br/>
		* <code>myGTween.proxy.rotation += 100;</code>
		* <br/><br/>
		* <b>Example 3:</b> Sets an end property value (through setProperty) for scaleX, then retrieves it from GTween (because it will always return
		* end values when available):<br/>
		* <code>trace(myGTween.proxy.scaleX); // 1 (value from target, because no end value is set)<br/>
		* myGTween.proxy.scaleX = 2; // set a end value<br/>
		* trace(myGTween.proxy.scaleX); // 2 (end value from GTween)<br/>
		* trace(myGTween.target.scaleX); // 1 (current value from target)</code>
		* <br/><br/>
		* <b>Example 4:</b> Property deletions only affect end properties on GTween, not the target object:<br/>
		* <code>myGTween.proxy.rotation = 50; // set a end value<br/>
		* trace(myGTween.proxy.rotation); // 50 (end value from GTween)<br/>
		* delete(myGTween.proxy.rotation); // delete the end value<br/>
		* trace(myGTween.proxy.rotation); // 0 (current value from target)</code>
		* <br/><br/>
		* <b>Example 5:</b> Non-numeric property access is passed through to the target:<br/>
		* <code>myGTween.proxy.blendMode = "multiply"; // passes value assignment through to the target<br/>
		* trace(myGTween.target.blendMode); // "multiply" (value from target)<br/>
		* trace(myGTween.proxy.blendMode); // "multiply" (value passed through from target)</code>
		* <br/><br/>
		* <b>Example 6:</b> Method calls are passed through to target:<br/>
		* <code>myGTween.proxy.gotoAndStop(30); // gotoAndStop(30) will be called on the target</code>
		**/
		public function get proxy():Object {
			if (_proxy == null) { _proxy = new TargetProxy(this); }
			return _proxy;
		}
		
		/**
		* 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 {
			_propertyTarget = _target = (value === null) ? {} : value;
			inited = false;
		}
		
		/**
		* Returns the object that will have its property tweened. In a standard GTween, this will usually be the same as target, except if an assignmentTarget was set.
		* This also makes it easy for subclasses like GTweenFilter can divert the property target.
		**/
		public function get propertyTarget():Object {
			return _propertyTarget;
		}
		
		/**
		* 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;
		}
		public function set reversed(value:Boolean):void {
			if (value == _reversed) { return; }
			_reversed = value;
			// we force an init so that it jumps to the proper position immediately without flicker.
			if (!inited) { init(); }
			setPosition(_position,true);
		}
		
		/**
		* Returns the current positional state of the tween. This does not indicate if the tween is paused - use the .paused property for this. Possible values are: <code>
		* GTween.START, GTween.DELAY, GTween.TWEEN, GTween.END</code><br/>
		* The beginning state indicates the tween either has not been played. The tween's position will equal -delay.<br/>
		* The delayPhase state indicates that the tween is active (running), but is currently delaying prior to initing. The tween's position is less than 0. Note that it may be paused.<br/>
		* The tweenPhase state indicates that the tween has inited, and is tweening the property values. Note that it may be paused.<br/>
		* The end state indicates that the tween has completed playing. Setting any new properties on the tween will reset it, and set its state to beginning.
		* <br/><br/>
		* New tweens with autoplay set to false start with a state of START. When first played, a tween will have a state of either DELAY (if delay > 0) or TWEEN (if delay == 0).
		* When the delay ends, and tweening begins, the state will change to TWEEN. When the tween reaches its end <code>position == duration*(repeat+1)</code>, the state will be set to END. If you change any end
		* properties on an ended tween, its state will be set back to START.
		**/
		public function get state():String {
			return (_position == -_delay && _paused) ? START : (_position < 0) ? DELAY : (repeat != -1 && _position >= (repeat+1)*duration) ? END : TWEEN;
		}
		
		/**
		* The length of the delay in frames or seconds (depending on the timingMode). The delay occurs before a tween reads initial values or starts playing.
		**/
		public function get delay():Number {
			return _delay;
		}
		public function set delay(value:Number):void {
			if (_position == -_delay) {
				setPosition(-value);
			}
			_delay = value;
		}
		
		/**
		* If set to true, this prevents the tween from reinitializing its start properties automatically (ex. when end properties change).
		* If start properties have not already been initialized, this will also cause the tween to immediate initialize them.
		* Note that this will prevent new start property values from being initialized when invalidating, so it could cause unexpected behaviour
		* if you modify the tween while it is playing.
		**/
		public function get lockStartProperties():Boolean {
			return _lockStartProperties;
		}
		public function set lockStartProperties(value:Boolean):void {
			if (value && !inited) { init(); }
			_lockStartProperties = value;
		}
		
	// public methods:
		
		/**
		* Shorthand method for making multiple setProperty calls quickly. This removes any existing target property values on the tween.
		* <br/><br/>
		* <b>Example:</b> set x and y end values:<br/>
		* <code>myGTween.setProperties({x:200, y:400});</code>
		*
		* @param properties An object containing end property values.
		**/
		public function setProperties(properties:Object):void {
			endValues = {};
			for (var n:String in properties) {
				setProperty(n, properties[n]);
			}
		}
		
		/**
		* Sets the numeric end value for a property on the target object that you would like to tween.
		* For example, if you wanted to tween to a new x position, you could use: myGTween.setProperty("x",400). Non-numeric values are ignored.
		*
		* @param name The name of the property to tween.
		* @param value The numeric end value (the value to tween to).
		**/
		public function setProperty(name:String, value:Number):void {
			if (isNaN(value)) { return; }
			endValues[name] = value;
			if (_lockStartProperties && startValues[name] == null) {
				startValues[name] = _propertyTarget[name];
			}
			invalidate();
		}
		
		/**
		* Returns the end value for the specified property if one exists.
		*
		* @param name The name of the property to return a end value for.
		**/
		public function getProperty(name:String):Number {
			return endValues[name];
		}
		
		/**
		* Removes a end value from the tween. This prevents the GTween instance from tweening the property.
		*
		* @param name The name of the end property to delete.
		**/
		public function deleteProperty(name:String):Boolean {
			return delete(endValues[name]);
		}
		
		/**
		* Returns the hash table of all end properties and their values. This is a copy of the internal hash of values, so modifying
		* the returned object will not affect the tween.
		**/
		public function getProperties():Object {
			return copyObject(endValues);
		}
		
		/**
		* Allows you to manually assign the start property values for a tween. These are the properties that will be applied when the tween
		* is at tween position 0. Normally these are automatically copied from the target object on initialization, or whenever a end value
		* changes. You can also use the lockStartProperties property to ensure your start properties are not reinitialized after you set them.
		*
		* @param properties An object containing start property values.
		**/
		public function setStartProperties(properties:Object):void {
			startValues = copyObject(properties);
			inited = true;
		}
		
		/**
		* Returns the hash table of all start properties and their values. This is a copy of the internal hash of values, so modifying
		* the returned object will not affect the tween.
		**/
		public function getStartProperties():Object {
			return copyObject(startValues);
		}
		
		/**
		* Shortcut method for setting multiple properties on the tween instance quickly. This does not set end values (ie. the value to tween to).
		* This method also provides you with a quick method for adding listeners to specific events, using the special properties:
		* initListener, completeListener, changeListener.
		* <br/><br/>
		* <b>Example:</b> This will set the duration, reflect, and nextTween properties of a tween, and add a listener for the complete event:<br/>
		* <code>myTween.setTweenProperties({duration:4, reflect:true, nextTween:anotherTween, completeListener:completeHandlerFunction});</code>
		**/
		public function setTweenProperties(properties:Object):void {
			if (!properties) { return; }
			
			var positionValue:Number;
			if ("position" in properties) { positionValue = properties.position; delete(properties.position); }
			if ("initListener" in properties) { addEventListener(Event.INIT,properties.initListener,false,0,true); delete(properties.initListener); }
			if ("completeListener" in properties) { addEventListener(Event.COMPLETE,properties.completeListener,false,0,true); delete(properties.completeListener); }
			if ("changeListener" in properties) { addEventListener(Event.CHANGE,properties.changeListener,false,0,true); delete(properties.changeListener); }
			
			for (var n:String in properties) {
				this[n] = properties[n];
			}
			
			if (!isNaN(positionValue)) { position = positionValue; }
		}
		
		/**
		* Toggles the reversed property and inverts the current tween position.