lineargo.as

jquery插件

/**
 * Copyright (c) 2007 Moses Gunesch
 * 
 * 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 org.goasap.items {
	import flash.utils.getTimer;
	
	import org.goasap.GoEngine;
	import org.goasap.errors.EasingFormatError;
	import org.goasap.events.GoEvent;
	import org.goasap.interfaces.IPlayable;
	import org.goasap.managers.LinearGoRepeater;	

	/**
	 * Dispatched during an animation's first update after the delay 
	 * has completed, if one was set. Any number of callbacks may also be 
	 * associated with this event using <code>addCallback</code>.
	 * @eventType org.goasap.events.START
	 */
	[Event(name="START", type="org.goasap.events.GoEvent")]

	/**
	 * Dispatched on the animation's update pulse. Any number of callbacks
	 * may also be associated with this event using <code>addCallback</code>.
	 * @eventType org.goasap.events.UPDATE
	 */
	[Event(name="UPDATE", type="org.goasap.events.GoEvent")]

	/**
	 * Dispatched when pause() is called successfully.  Any number of callbacks
	 * may also be associated with this event using <code>addCallback</code>.
	 * @eventType org.goasap.events.PAUSE
	 */
	[Event(name="PAUSE", type="org.goasap.events.GoEvent")]

	/**
	 * Dispatched when resume() is called successfully. Any number of callbacks
	 * may also be associated with this event using <code>addCallback</code>.
	 * @eventType org.goasap.events.RESUME
	 */
	[Event(name="RESUME", type="org.goasap.events.GoEvent")]

	/**
	 * Dispatched at the end of each cycle if the tween has more than one.
	 * Any number of callbacks may also be associated with this event using 
	 * <code>addCallback</code>.
	 * @eventType org.goasap.events.CYCLE
	 */
	[Event(name="CYCLE", type="org.goasap.events.GoEvent")]

	/**
	 * Dispatched if an animation is manually stopped. Any number of callbacks
	 * may also be associated with this event using <code>addCallback</code>.
	 * @eventType org.goasap.events.STOP
	 */
	[Event(name="STOP", type="org.goasap.events.GoEvent")]

	/**
	 * Dispatched on an animation's final update, just after the last update event.
	 * Any number of callbacks may also be associated with this event using 
	 * <code>addCallback</code>.
	 * @eventType org.goasap.events.COMPLETE
	 */
	[Event(name="COMPLETE", type="org.goasap.events.GoEvent")]

	/**
	 * LinearGo extends the base class GoItem to define a playable A-to-B animation. 
	 * 
	 * <p><b>LinearGo: A very simple tween</b></p>
	 * 
	 * <p>A LinearGo instance is a playable object that animates a single number. It dispatches events 
	 * and callbacks associated with the animation's start, update and completion. Instances can be used 
	 * directly, or easily subclassed to build custom tweening APIs. LinearGo extends GoItem, which 
	 * provides basic settings shared by physics and tween items. These include play-state contants and 
	 * a <code>state</code> property, <code>pulseInterval</code>, and the two common animation options 
	 * <code>useRounding</code> and <code>useRelative</code>.</p>
	 * 
	 * <p>The tween can be customized using the instance properties <code>duration</code>, <code>easing</code> 
	 * and <code>delay</code>. The number crunched by a LinearGo is readable in its <code>position</code> 
	 * property. This number always starts at 0 and completes at 1, regardless of the tween's duration 
	 * or easing (those parameters are factored in to produce accurate fractional in-between values).  
	 * As the tween runs, you can use <code>position</code> as a multiplier to animate virtually anything: 
	 * motion, alpha, a sound level, the values in a ColorTransform, BitmapFilter, a 3D scene, and so on.
	 * Note that at times position may be less than 0 or greater than 1 depending on the easing function.</p>
	 * 
	 * <p>The START event occurs just before the first update (after the delay). UPDATE is fired once on 
	 * <i>every</i> update pulse, and COMPLETE just after the final update. The STOP event is fired by LinearGo 
	 * only if a tween is stopped before it completes. Additional events are fired on PAUSE, RESUME and at
	 * the end of each CYCLE if the tween plays more than one cycle. Besides standard events, you can store 
	 * callback functions (method-closures) using <code>addCallback</code>. Any number of callbacks can be 
	 * associated with each GoEvent type. This alternative to the standard event model was included in 
	 * LinearGo since it's a common feature of many modern tweening APIs, and very slightly more efficient 
	 * than standard events.</p>
	 * 
	 * <p>LinearGo can play multiple back-and-forth tween cycles or repeat forward-play any number of times.
	 * This functionality is handled by the LinearGo's <code>repeater</code> instance, which has settings for
	 * alternate easing on reverse-cycles, infinite cycling, plus <code>currentCycle</code> and <code>done</code> 
	 * state properties.</p>
	 * 
	 * <p><b>Subclassing to create custom tweens</b></p>
	 * 
	 * <p><i>Important: Store your custom tween classes in a package bearing your own classpath, not in the core 
	 * package! This will help avoid confusion with other authors' work.</i></p>
	 * 
	 * <p>It's possible to build virtually any tweening API over LinearGo because all of the specifics are left 
	 * up to you: target objects, tweenable properties, tween values — and importantly, the datatypes of all of these.</p>
	 * 
	 * <p>A basic subclass can be created in three steps: Gathering target & property information, subclassing the 
	 * <code>start</code> method to set up the tween, and finally subclassing the <code>onUpdate</code> method 
	 * to affect the tween. The first step, gathering tween target and property information, can be done by writing 
	 * getter/setter properties, customizing the constructor, or both. Consider various options such as allowing for 
	 * single vs. multiple target objects, open vs. specific tween properties, and so on. The next step, subclassing 
	 * <code>start</code>, involves figuring the tween's amount of change and implementing a standard Go convention, 
	 * <code>useRelative</code>. This option should enable the user to declare tween values as relative to existing 
	 * values instead of as fixed absolutes. In the final step, you subclass <code>onUpdate</code> to apply the tween, 
	 * using the <code>_position</code> calculated by this base class:</p>
	 * 
	 * <pre>target[ propName ] = super.correctValue(start + change * _position);</pre>
	 * 
	 * <p>The helper method <code>correctValue</code> is provided in the superclass GoItem, to clean up NaN values 
	 * and apply rounding when <code>useRounding</code> is activated. That's it — events and callbacks are 
	 * dispatched by LinearGo, so subclasses can remain simple.</p>
	 * 
	 * <p>An optional fourth step will make your custom tween compatible with Go managers. To do this, implement 
	 * the IManageable interface. (OverlapMonitor prevents different tween instances from handling the same 
	 * property at once; you can build other managers as well.)</p>
	 * 
	 * {In the game of Go a black or white stone is called a go-ishi.}
	 * 
	 * @author Moses Gunesch
	 */
	public class LinearGo extends GoItem implements IPlayable
	{
		// -== Settable Class Defaults ==-
		
		/**
		 * Class default for the instance property delay.
		 * @default 0
		 * @see #delay
		 */
		public static var defaultDelay : Number = 0;
		
		/**
		 * Class default for the instance property duration.
		 * @default 1
		 * @see #duration
		 */
		public static var defaultDuration : Number = 1;
		
		/**
		 * Class default for the instance property easing.
		 * Note that this property is left null until the first LinearGo
		 * is instantiated, at which time it is set to Quintic.easeOut.
		 * @default fl.motion.easing.Quintic.easeOut
		 * @see #easing
		 */
		public static var defaultEasing:Function;
		
		/**
		 * Normal default easing, this is Quintic.easeOut.
		 * (The two default easings in this class are included because there's
		 * currently no single easing classpath shared between Flash & Flex.)
		 */
		public static function easeOut(t:Number, b:Number, c:Number, d:Number) : Number {
			return c * ((t = t / d - 1) * t * t * t * t + 1) + b;
		};
		
		// -== Class Methods ==-
		
		/**
		 * An alternative default easing with no acceleration.
		 * (The two default easings in this class are included because there's
		 * currently no single easing classpath shared between Flash & Flex.)
		 */
		public static function easeNone(t:Number, b:Number, c:Number, d:Number) : Number {
			return c * t / d + b;
		};
		
		/**
		 * A quick one-time setup command that lets you turn on useFrames mode
		 * as a default for all new tweens and adjust some related settings.
		 * (Note that useFrames mode is normally only used for specialty situations.)
		 * 
		 * @param defaultToFramesMode		Sets an internal default so all new LinearGo instances
		 * 									will be set to use framecounts for their delay and duration. 
		 * 									Also sets GoItem.defaultPulseInterval to enterframe which is 
		 * 									most normal for frame-based updates.
		 * @param useZeroBasedFrameIndex	Normally currentFrame reads 1 on first update, like the Flash
		 * 									timeline starts at Frame 1. Set this option to use a zero-based 
		 * 									index on all tweens instead.
		 * @see #useFrames
		 * @see #currentFrame
		 */
		public static function setupUseFramesMode( defaultToFramesMode: Boolean = true,
								   				   useZeroBasedFrameIndex: Boolean=false):void {
			GoItem.defaultPulseInterval = GoEngine.ENTER_FRAME;
			_useFramesMode = defaultToFramesMode;
			if (useZeroBasedFrameIndex) { _framesBase = 0; }
		}

		// -== Pulic Properties ==-
		
		/**
		 * Number of seconds after start() call that the LinearGo begins processing.
		 * <p>If not set manually, the class default defaultDelay is adopted.</p>
		 * @see #defaultDelay
		 */
		public function get delay():Number {
			return _delay;
		}
		public function set delay(seconds:Number):void {
			if (_state==STOPPED && seconds >= 0) {
				_delay = seconds;
			}
		}
		
		/**
		 * Number of seconds the LinearGo takes to process.
		 * <p>If not set manually, the class default defaultDuration is adopted.</p>
		 * @see #defaultDuration
		 */
		public function get duration():Number {
			return _duration;
		}
		public function set duration(seconds:Number):void {
			if (_state==STOPPED && seconds >= 0) {
				_duration = seconds;
			}
		}
		
		/**
		 * Any standard easing-equation function such as the ones found in
		 * the Flash package fl.motion.easing or the flex package mx.effects.easing.
		 * 
		 * <p>If not set manually, the class default defaultEasing is adopted. An error
		 * is thrown if the function does not follow the typical format. For easings 
		 * that accept more than four parameters use <code>extraEasingParams</code>.
		 * </p>
		 * 
		 * @see #defaultEasing
		 * @see #extraEasingParams
		 */
		public function get easing():Function {
			return _easing;
		}
		public function set easing(type:Function):void {
			if (_state==STOPPED) {
				try {
					if (type(1,1,1,1) is Number) {
						_easing = type;
						return;
					}
				} catch (e:Error) {}
				throw new EasingFormatError();
			}
		}
		
		/**
		 * Additional parameters to pass to easing functions that accept more than four.
		 * @see #easing
		 */
		public function get extraEasingParams() : Array {
			return _extraEaseParams;
		}
		public function set extraEasingParams(params:Array):void {
			if (_state==STOPPED && params is Array && params.length>0) {
				_extraEaseParams = params;
			}