GODPAPER | All Packages | All Classes | Index | Frames No Frames |
GTween

Package | com.gskinner.motion
Class | public class GTween
Inheritance | GTween flash.events.EventDispatcher
Subclasses | GTweenTimeline

Public Properties

| Property | Defined By
--- | --- | ---
|  | autoPlay : Boolean = true Indicates whether the tween should automatically play when an end value is changed. | GTween
|  | calculatedPosition : Number The current calculated position of the tween. | GTween
|  | calculatedPositionOld : Number The previous calculated position of the tween. | GTween
|  | data : * Allows you to associate arbitrary data with your tween. | GTween
|  | defaultDispatchEvents : Boolean = false [static] Sets the default value of dispatchEvents for new instances. | GTween
|  | defaultEase : Function [static] Specifies the default easing function to use with new tweens. | GTween
|  | delay : Number The length of the delay in frames or seconds (depending on .useFrames). | GTween
|  | dispatchEvents : Boolean If true, it will dispatch init, change, and complete events in addition to calling the onInit, onChange, and onComplete callbacks. | GTween
|  | duration : Number The length of the tween in frames or seconds (depending on the timingMode). | GTween
|  | ease : Function The easing function to use for calculating the tween. | GTween
|  | nextTween : GTween Specifies another GTween instance that will have paused=false set on it when this tween completes. | GTween
|  | onChange : Function Callback for the change event. | GTween
|  | onComplete : Function Callback for the complete event. | GTween
|  | onInit : Function Callback for the init event. | GTween
|  | pauseAll : Boolean = false [static] Setting this to true pauses all tween instances. | GTween
|  | paused : Boolean Plays or pauses a tween. | GTween
|  | pluginData : Object Stores data for plugins specific to this instance. | GTween
|  | position : Number Gets and sets the position of the tween in frames or seconds (depending on .useFrames). | GTween
|  | positionOld : Number The position of the tween at the previous change. | GTween
|  | proxy : TargetProxy [read-only] The proxy object allows you to work with the properties and methods of the target object directly through GTween. | GTween
|  | ratio : Number The eased ratio (generally between 0-1) of the tween at the current position. | GTween
|  | ratioOld : Number The eased ratio (generally between 0-1) of the tween at the previous position. | GTween
|  | reflect : Boolean Indicates whether the tween should use the reflect mode when repeating. | GTween
|  | repeatCount : int = 1 The number of times this tween will run. | GTween
|  | suppressEvents : Boolean If true, events/callbacks will not be called. | GTween
|  | target : Object The target object to tween. | GTween
|  | timeScale : Number = 1 Allows you to scale the passage of time for a tween. | GTween
|  | timeScaleAll : Number = 1 [static] Sets the time scale for all tweens. | GTween
|  | useFrames : Boolean If true, durations and positions can be set in frames. | GTween
|  | version : Number = 2.01 [static] Indicates the version number for this build. | GTween

Public Methods

| Method | Defined By
--- | --- | ---
|  | GTween(target:Object = null, duration:Number = 1, values:Object = null, props:Object = null, pluginData:Object = null) Constructs a new GTween instance. | GTween
|  | beginning():void Jumps the tween to its beginning and pauses it. | GTween
|  | deleteValue(name:String):Boolean Removes a end value from the tween. | GTween
|  | end():void Jumps the tween to its end and pauses it. | GTween
|  | getInitValue(name:String):Number Returns the initial value for the specified property. | GTween
|  | getValue(name:String):Number Returns the end value for the specified property if one exists. | GTween
|  | getValues():Object Returns the hash table of all end properties and their values. | GTween
|  | init():void Reads all of the initial values from target and calls the onInit callback. | GTween
|  | installPlugin(plugin:Object, propertyNames:Array, highPriority:Boolean = false):void [static] Installs a plugin for the specified property. | GTween
|  | linearEase(a:Number, b:Number, c:Number, d:Number):Number [static] The default easing function used by GTween. | GTween
|  | resetValues(values:Object = null):void Similar to .setValues(), but clears all previous end values before setting the new ones. | GTween
|  | setValue(name:String, value:Number):void Sets the numeric end value for a property on the target object that you would like to tween. | GTween
|  | setValues(values:Object):void Shorthand method for making multiple setProperty calls quickly. | GTween
|  | swapValues():void Swaps the init and end values for the tween, effectively reversing it. | GTween

Property Detail

autoPlay | property

`public var autoPlay:Boolean = true`

Indicates whether the tween should automatically play when an end value is changed.

calculatedPosition | property |

`public var calculatedPosition:Number`

The current calculated position of the tween. This is a deterministic value between 0 and duration calculated from the current position based on the duration, repeatCount, and reflect properties. This is always a value between 0 and duration, whereas `.position` can range between -delay and repeatCounturation. This should not be set directly.

calculatedPositionOld | property |

`public var calculatedPositionOld:Number`

The previous calculated position of the tween. See `.calculatedPosition` for more information. This should not be set directly.

data | property |

`public var data:*`

Allows you to associate arbitrary data with your tween. For example, you might use this to reference specific data when handling event callbacks from tweens.

defaultDispatchEvents | property |

`public static var defaultDispatchEvents:Boolean = false`

Sets the default value of dispatchEvents for new instances.

defaultEase | property |

`public static var defaultEase:Function`

Specifies the default easing function to use with new tweens. Set to GTween.linearEase by default.

delay | property |

`delay:Number`

The length of the delay in frames or seconds (depending on `.useFrames`). The delay occurs before a tween reads initial values or starts playing.

Implementation
`public function get delay():Number`
`public function set delay(value:Number):void`

dispatchEvents | property |

`public var dispatchEvents:Boolean`

If true, it will dispatch init, change, and complete events in addition to calling the onInit, onChange, and onComplete callbacks. Callbacks provide significantly better performance, whereas events are more standardized and flexible (allowing multiple listeners, for example). By default this will use the value of defaultDispatchEvents.

duration | property |

`public var duration:Number`

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.

ease | property |

`public var ease:Function`

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 `defaultTween`. Setting this to null will cause GTween to throw null reference errors.

nextTween | property |

`public var nextTween:GTween`

Specifies another GTween instance that will have `paused=false` set on it when this tween completes. This happens immediately before onComplete is called.

onChange | property |

`public var onChange:Function`

Callback for the change event. Any function assigned to this callback will be called each frame while the tween is active with a single parameter containing a reference to the tween.

onComplete | property |

`public var onComplete:Function`

Callback for the complete event. Any function assigned to this callback will be called when the tween finishes with a single parameter containing a reference to the tween. Ex. ``

    myTween.onComplete = myFunction;
    		function myFunction(tween:GTween):void {
    		trace("tween completed");
    		}

onInit | property |

`public var onInit:Function`

Callback for the init event. Any function assigned to this callback will be called when the tween inits with a single parameter containing a reference to the tween. Init is usually triggered when a tween finishes its delay period and becomes active, but it can also be triggered by other features that require the tween to read the initial values, like calling `.swapValues()`.

pauseAll | property |

`public static var pauseAll:Boolean = false`

Setting this to true pauses all tween instances. This does not affect individual tweens' .paused property.

paused | property |

`paused:Boolean`

Plays or pauses a tween. You can still change the position value externally on a paused tween, but it will not be updated automatically. While paused is false, the tween is also prevented from being garbage collected while it is active. This is achieved in one of two ways: 1. If the target object is an IEventDispatcher, then the tween will subscribe to a dummy event using a hard reference. This allows the tween to be garbage collected if its target is also collected, and there are no other external references to it. 2. If the target object is not an IEventDispatcher, then the tween is placed in a global list, to prevent collection until it is paused or completes. Note that pausing all tweens via the GTween.pauseAll static property will not free the tweens for collection.

Implementation
`public function get paused():Boolean`
`public function set paused(value:Boolean):void`

pluginData | property |

`public var pluginData:Object`

Stores data for plugins specific to this instance. Some plugins may allow you to set properties on this object that they use. Check the documentation for your plugin to see if any properties are supported. Most plugins also support a property on this object in the form PluginNameEnabled to enable or disable the plugin for this tween (ex. BlurEnabled for BlurPlugin). Many plugins will also store internal data in this object.

position | property |

`position:Number`

Gets and sets the position of the tween in frames or seconds (depending on `.useFrames`). This value will be constrained between -delay and repeatCounturation. It will be resolved to a `calculatedPosition` before being applied. Negative values Values below 0 will always resolve to a calculatedPosition 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. Positive values Positive values are resolved based on the duration, repeatCount, and reflect properties.

Implementation
`public function get position():Number`
`public function set position(value:Number):void`

positionOld | property |

`public var positionOld:Number`

The position of the tween at the previous change. This should not be set directly.

proxy | property |

`proxy:TargetProxy` [read-only]

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. Example 1: Equivalent to calling myGTween.setProperty("scaleY",2.5): `myGTween.proxy.scaleY = 2.5;` Example 2: 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: `myGTween.proxy.rotation += 100;` Example 3: Sets an end property value (through setProperty) for scaleX, then retrieves it from GTween (because it will always return end values when available): `trace(myGTween.proxy.scaleX); // 1 (value from target, because no end value is set) myGTween.proxy.scaleX = 2; // set a end value trace(myGTween.proxy.scaleX); // 2 (end value from GTween) trace(myGTween.target.scaleX); // 1 (current value from target)` Example 4: Property deletions only affect end properties on GTween, not the target object: `myGTween.proxy.rotation = 50; // set an end value trace(myGTween.proxy.rotation); // 50 (end value from GTween) delete(myGTween.proxy.rotation); // delete the end value trace(myGTween.proxy.rotation); // 0 (current value from target)` Example 5: Non-numeric property access is passed through to the target: `myGTween.proxy.blendMode = "multiply"; // passes value assignment through to the target trace(myGTween.target.blendMode); // "multiply" (value from target) trace(myGTween.proxy.blendMode); // "multiply" (value passed through proxy from target)` Example 6: Method calls are passed through to target: `myGTween.proxy.gotoAndStop(30); // gotoAndStop(30) will be called on the target`

Implementation
`public function get proxy():TargetProxy`

ratio | property |

`public var ratio:Number`

The eased ratio (generally between 0-1) of the tween at the current position. This should not be set directly.

ratioOld | property |

`public var ratioOld:Number`

The eased ratio (generally between 0-1) of the tween at the previous position. This should not be set directly.

reflect | property |

`public var reflect:Boolean`

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.

repeatCount | property |

`public var repeatCount:int = 1`

The number of times this tween will run. If 1, the tween will only run once. If 2 or more, the tween will repeat that many times. If 0, the tween will repeat forever.

suppressEvents | property |

`public var suppressEvents:Boolean`

If true, events/callbacks will not be called. As well as allowing for more control over events, and providing flexibility for extension, this results in a slight performance increase, particularly if useCallbacks is false.

target | property |

`public var target:Object`

The target object to tween. This can be any kind of object. You can retarget a tween at any time, but changing the target in mid-tween may result in unusual behaviour.

timeScale | property |

`public var timeScale:Number = 1`

Allows you to scale the passage of time for a tween. For example, a tween with a duration of 5 seconds, and a timeScale of 2 will complete in 2.5 seconds. With a timeScale of 0.5 the same tween would complete in 10 seconds.

timeScaleAll | property |

`public static var timeScaleAll:Number = 1`

Sets the time scale for all tweens. For example to run all tweens at half speed, you can set timeScaleAll to 0.5. It is multiplied against each tweens timeScale. For example a tween with timeScale=2 will play back at normal speed if timeScaleAll is set to 0.5.

useFrames | property |

`public var useFrames:Boolean`

If true, durations and positions can be set in frames. If false, they are specified in seconds.

version | property |

`public static var version:Number = 2.01`

Indicates the version number for this build. The numeric value will always increase with the version number for easy comparison (ex. GTween.version >= 2.12). Currently, it incorporates the major version as the integer value, and the two digit build number as the decimal value. For example, the fourth build of version 3 would have version=3.04.

Constructor Detail

GTween | () | Constructor

`public function GTween(target:Object = null, duration:Number = 1, values:Object = null, props:Object = null, pluginData:Object = null)`

Constructs a new GTween instance.

Parameters

| `target:Object` (default = `null`)`` — The object whose properties will be tweened. Defaults to null.
| `duration:Number` (default = `1`)`` — The length of the tween in frames or seconds depending on the timingMode. Defaults to 1.
| `values:Object` (default = `null`)`` — An object containing end property values. For example, to tween to x=100, y=100, you could pass {x:100, y:100} as the values object.
| `props:Object` (default = `null`)`` — 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. It also supports a single special property "swapValues" that will cause `.swapValues` to be called after the values specified in the values parameter are set.
| `pluginData:Object` (default = `null`)`` — An object containing data for installed plugins to use with this tween. See `.pluginData` for more information.

Method Detail

beginning | () | method

`public function beginning():void`

Jumps the tween to its beginning and pauses it. This is the same as setting `position=0` and `paused=true`.

deleteValue | () | method |

`public function deleteValue(name:String):Boolean`

Removes a end value from the tween. This prevents the GTween instance from tweening the property.

Parameters

| `name:String` — The name of the end property to delete.

Returns

| `Boolean`

end | () | method |

`public function end():void`

Jumps the tween to its end and pauses it. This is roughly the same as setting `position=repeatCounturation`.

getInitValue | () | method |

`public function getInitValue(name:String):Number`

Returns the initial value for the specified property. Note that the value will not be available until the tween inits.

Parameters

| `name:String`

Returns

| `Number`

getValue | () | method |

`public function getValue(name:String):Number`

Returns the end value for the specified property if one exists.

Parameters

| `name:String` — The name of the property to return a end value for.

Returns

| `Number`

getValues | () | method |

`public function getValues():Object`

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.

Returns

| `Object`

init | () | method |

`public function init():void`

Reads all of the initial values from target and calls the onInit callback. This is called automatically when a tween becomes active (finishes delaying) and when `.swapValues()` is called. It would rarely be used directly but is exposed for possible use by plugin developers or power users.

installPlugin | () | method |

`public static function installPlugin(plugin:Object, propertyNames:Array, highPriority:Boolean = false):void`

Installs a plugin for the specified property. Plugins with high priority will always be called before other plugins for the same property. This method is primarily used by plugin developers. Plugins are normally installed by calling the install method on them, such as BlurPlugin.install(). Plugins can register to be associated with a specific property name, or to be called for all tweens by registering for the " property name. The latter will be called after all properties are inited or tweened for a particular GTween instance.

Parameters

| `plugin:Object` — The plugin object to register. The plugin should conform to the IGTweenPlugin interface.
| `propertyNames:Array` — An array of property names to operate on (ex. "rotation"), or " to register the plugin to be called for every GTween instance.
| `highPriority:Boolean` (default = `false`)`` — If true, the plugin will be added to the start of the plugin list for the specified property name, if false it will be added to the end.

linearEase | () | method |

`public static function linearEase(a:Number, b:Number, c:Number, d:Number):Number`

The default easing function used by GTween.

Parameters

| `a:Number`
| `b:Number`
| `c:Number`
| `d:Number`

Returns

| `Number`

resetValues | () | method |

`public function resetValues(values:Object = null):void`

Similar to `.setValues()`, but clears all previous end values before setting the new ones.

Parameters

| `values:Object` (default = `null`)`` — An object containing end property values.

setValue | () | method |

`public function setValue(name:String, value:Number):void`

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.setValue("x",400).

Parameters

| `name:String` — The name of the property to tween.
| `value:Number` — The numeric end value (the value to tween to).

setValues | () | method |

`public function setValues(values:Object):void`

Shorthand method for making multiple setProperty calls quickly. This adds the specified properties to the values list. Passing a property with a value of null will delete that value from the list. Example: set x and y end values, delete rotation: `myGTween.setProperties({x:200, y:400, rotation:null});`

Parameters

| `values:Object` — An object containing end property values.

swapValues | () | method |

`public function swapValues():void`

Swaps the init and end values for the tween, effectively reversing it. This should generally only be called before the tween starts playing. This will force the tween to init if it hasn't already done so, which may result in an onInit call. It will also force a render (so the target immediately jumps to the new values immediately) which will result in the onChange callback being called. You can also use the special "swapValues" property on the props parameter of the GTween constructor to call swapValues() after the values are set. The following example would tween the target from 100,100 to its current position: `new GTween(ball, 2, {x:100, y:100}, {swapValues:true});`

Thu Jan 16 2014, 01:11 PM +08:00