Packagecom.gskinner.motion
Classpublic class GTweenTimeline
InheritanceGTweenTimeline Inheritance GTween

GTweenTimeline ©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.
GTweenTimeline is a powerful sequencing engine for GTween. It allows you to build a virtual timeline with tweens, actions (callbacks), and labels. It supports all of the features of GTween, so you can repeat, reflect, and pause the timeline. You can even embed timelines within each other. GTweenTimeline adds about 1.2kb above GTween.


Public Properties
 PropertyDefined by
 InheritedautoPlay : Boolean = true
Indicates whether the tween should automatically play when an end value is changed.
GTween
 InheritedcalculatedPosition : Number
The current calculated position of the tween.
GTween
 InheritedcalculatedPositionOld : Number
The previous calculated position of the tween.
GTween
 Inheriteddata : *
Allows you to associate arbitrary data with your tween.
GTween
 InheriteddefaultEase : Function
[static] Specifies the default easing function to use with new tweens.
GTween
 Inheriteddelay : Number
The length of the delay in frames or seconds (depending on .useFrames).
GTween
 Inheritedduration : Number
The length of the tween in frames or seconds (depending on the timingMode).
GTween
 Inheritedease : Function
The easing function to use for calculating the tween.
GTween
 InheritednextTween : GTween
Specifies another GTween instance that will have paused=false set on it when this tween completes.
GTween
 InheritedonChange : Function
Callback for the change event.
GTween
 InheritedonComplete : Function
Callback for the complete event.
GTween
 InheritedonInit : Function
Callback for the init event.
GTween
 InheritedpauseAll : Boolean = false
[static] Setting this to true pauses all tween instances.
GTween
 Inheritedpaused : Boolean
Plays or pauses a tween.
GTween
 InheritedpluginData : Object
Stores data for plugins specific to this instance.
GTween
  position : Number
[write-only]
GTweenTimeline
 InheritedpositionOld : Number
The position of the tween at the previous change.
GTween
 Inheritedproxy : TargetProxy
The proxy object allows you to work with the properties and methods of the target object directly through GTween.
GTween
 Inheritedratio : Number
The eased ratio (generally between 0-1) of the tween at the current position.
GTween
 InheritedratioOld : Number
The eased ratio (generally between 0-1) of the tween at the previous position.
GTween
 Inheritedreflect : Boolean
Indicates whether the tween should use the reflect mode when repeating.
GTween
 InheritedrepeatCount : int = 1
The number of times this tween will run.
GTween
  suppressCallbacks : Boolean
If true, callbacks added with addCallback will not be called.
GTweenTimeline
 InheritedsuppressEvents : Boolean
If true, callbacks such as onInit, onChange, and onComplete will not be called.
GTween
 Inheritedtarget : Object
The target object to tween.
GTween
 InheritedtimeScale : Number = 1
Allows you to scale the passage of time for a tween.
GTween
 InheritedtimeScaleAll : Number = 1
[static] Sets the time scale for all tweens.
GTween
 InheriteduseFrames : Boolean
If true, durations and positions can be set in frames.
GTween
Public Methods
 MethodDefined by
  
GTweenTimeline(target:Object = null, duration:Number = 1, values:Object = null, props:Object = null, pluginData:Object = null, tweens:Array = null)
Constructs a new GTweenTimeline instance.
GTweenTimeline
  
addCallback(labelOrPosition:*, forwardCallback:Function, forwardParameters:Array = null, reverseCallback:Function = null, reverseParameters:Array = null):void
Adds a callback function at the specified position.
GTweenTimeline
  
addLabel(position:Number, label:String):void
Adds a label at the specified position.
GTweenTimeline
  
addTween(position:Number, tween:GTween):void
Adds a tween to the timeline, which will start playing at the specified start position.
GTweenTimeline
  
addTweens(tweens:Array):void
Shortcut method for adding a number of tweens at once.
GTweenTimeline
 Inherited
beginning():void
Jumps the tween to its beginning and pauses it.
GTween
  
calculateDuration():void
Calculates and sets the duration of the timeline based on the tweens and callbacks that have been added to it.
GTweenTimeline
 Inherited
deleteValue(name:String):Boolean
Removes a end value from the tween.
GTween
 Inherited
end():void
Jumps the tween to its end and pauses it.
GTween
 Inherited
getInitValue(name:String):Number
Returns the initial value for the specified property.
GTween
 Inherited
getValue(name:String):Number
Returns the end value for the specified property if one exists.
GTween
 Inherited
getValues():Object
Returns the hash table of all end properties and their values.
GTween
  
goto(labelOrPosition:*):void
Jumps the timeline to the specified label or numeric position without affecting its paused state.
GTweenTimeline
  
gotoAndPlay(labelOrPosition:*):void
Jumps the timeline to the specified label or numeric position and plays it.
GTweenTimeline
  
gotoAndStop(labelOrPosition:*):void
Jumps the timeline to the specified label or numeric position and pauses it.
GTweenTimeline
 Inherited
init():void
Reads all of the initial values from target and calls the onInit callback.
GTween
 Inherited
installPlugin(plugin:Object, propertyNames:Array, highPriority:Boolean = false):void
[static] Installs a plugin for the specified property.
GTween
 Inherited
linearEase(a:Number, b:Number, c:Number, d:Number):Number
[static] The default easing function used by GTween.
GTween
  
removeCallback(labelOrPosition:*):void
Removes the callback at the specified label or position.
GTweenTimeline
  
removeLabel(label:String):void
Removes the specified label.
GTweenTimeline
  
removeTween(tween:GTween):void
Removes the specified tween.
GTweenTimeline
 Inherited
resetValues(values:Object = null):void
Similar to .setValues(), but clears all previous end values before setting the new ones.
GTween
  
resolveLabelOrPosition(labelOrPosition:*):Number
Returns the position for the specified label.
GTweenTimeline
  
setPropertyValue(target:Object, propertyName:String, value:*):void
[static] Sets a property value on a specified target object.
GTweenTimeline
 Inherited
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
 Inherited
setValues(values:Object):void
Shorthand method for making multiple setProperty calls quickly.
GTween
 Inherited
swapValues():void
Swaps the init and end values for the tween, effectively reversing it.
GTween
Property detail
positionproperty
position:Number  [write-only]Implementation
    public function set position(value:Number):void
suppressCallbacksproperty 
public var suppressCallbacks:Boolean

If true, callbacks added with addCallback will not be called. This does not affect event callbacks like onChange, which can be disabled with suppressEvents. This can be handy for preventing large numbers of callbacks from being called when manually changing the position of a timeline (ex. calling .end()).

Constructor detail
GTweenTimeline()constructor
public function GTweenTimeline(target:Object = null, duration:Number = 1, values:Object = null, props:Object = null, pluginData:Object = null, tweens:Array = null)

Constructs a new GTweenTimeline instance. Note that because GTweenTimeline extends GTween, it can be used to tween a target directly, in addition to using its timeline features (for example, to synch tweening an animation with a timeline sequence).

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 10.
 
values:Object (default = null) — 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.
 
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.
 
tweens:Array (default = null) — An array of alternating start positions and tween instances. For example, the following array would add 3 tweens starting at positions 2, 6, and 8: [2, tween1, 6, tween2, 8, tween3]
Method detail
addCallback()method
public function addCallback(labelOrPosition:*, forwardCallback:Function, forwardParameters:Array = null, reverseCallback:Function = null, reverseParameters:Array = null):void

Adds a callback function at the specified position. When the timeline's playhead passes over or lands on the position while playing the callback will be called with the parameters specified. You can also optionally specify a callback and parameters to use if the timeline is playing in reverse (when reflected for example).

You can only have one callback at a specified position. They can be offset by a very small amount though (ex. one at 7, one at 7.0001).

Note that this can be used in conjunction with the static setPropertyValue method to easily set properties on objects in the timeline.

Parameters
labelOrPosition:* — The position or label to add the callback at in frames or seconds (as per the timing mode of this tween).
 
forwardCallback:Function — The function to call when playing forwards.
 
forwardParameters:Array (default = null) — Optional array of parameters to pass to the callback when it is called when playing forwards.
 
reverseCallback:Function (default = null) — The function to call when playing in reverse.
 
reverseParameters:Array (default = null) — Optional array of parameters to pass to the callback when it is called when playing in reverse.
addLabel()method 
public function addLabel(position:Number, label:String):void

Adds a label at the specified position. You can use gotoAndPlay or gotoAndStop to jump to labels.

Parameters
position:Number — The position to add the label at in frames or seconds (as per the timing mode of this tween).
 
label:String — The label to add.
addTween()method 
public function addTween(position:Number, tween:GTween):void

Adds a tween to the timeline, which will start playing at the specified start position. The tween will play synchronized with the timeline, with all of its behaviours intact (ex. repeat, reflect) except for delay (which is accomplished with the position parameter instead).

Parameters
position:Number — The starting position for this tween in frames or seconds (as per the timing mode of this tween).
 
tween:GTween — The GTween instance to add. Note that this can be any subclass of GTween, including another GTweenTimeline.
addTweens()method 
public function addTweens(tweens:Array):void

Shortcut method for adding a number of tweens at once.

Parameters
tweens:Array — An array of alternating positions and tween instances. For example, the following array would add 3 tweens starting at positions 2, 6, and 8: [2, tween1, 6, tween2, 8, tween3]
calculateDuration()method 
public function calculateDuration():void

Calculates and sets the duration of the timeline based on the tweens and callbacks that have been added to it.

goto()method 
public function goto(labelOrPosition:*):void

Jumps the timeline to the specified label or numeric position without affecting its paused state.

Parameters
labelOrPosition:* — The label name or numeric position in frames or seconds (as per the timing mode of this tween) to jump to.
gotoAndPlay()method 
public function gotoAndPlay(labelOrPosition:*):void

Jumps the timeline to the specified label or numeric position and plays it.

Parameters
labelOrPosition:* — The label name or numeric position in frames or seconds (as per the timing mode of this tween) to jump to.
gotoAndStop()method 
public function gotoAndStop(labelOrPosition:*):void

Jumps the timeline to the specified label or numeric position and pauses it.

Parameters
labelOrPosition:* — The label name or numeric position in frames or seconds (as per the timing mode of this tween) to jump to.
removeCallback()method 
public function removeCallback(labelOrPosition:*):void

Removes the callback at the specified label or position.

Parameters
labelOrPosition:* — The position of the callback to remove in frames or seconds (as per the timing mode of this tween).
removeLabel()method 
public function removeLabel(label:String):void

Removes the specified label.

Parameters
label:String — The label to remove.
removeTween()method 
public function removeTween(tween:GTween):void

Removes the specified tween. Note that this will remove all instances of the tween if has been added multiple times to the timeline.

Parameters
tween:GTween — The GTween instance to remove.
resolveLabelOrPosition()method 
public function resolveLabelOrPosition(labelOrPosition:*):Number

Returns the position for the specified label. If a numeric position is specified, it is returned unchanged.

Parameters
labelOrPosition:* — The label name or numeric position in frames or seconds (as per the timing mode of this tween) to resolve.

Returns
Number
setPropertyValue()method 
public static function setPropertyValue(target:Object, propertyName:String, value:*):void

Sets a property value on a specified target object. This is provided to make it easy to set properties in a GTweenTimeline using addCallback. For example, to set the visible property to true on a movieclip "foo" at 3 seconds into the timeline, you could use the following code:
myTimeline.addCallback(3,GTweenTimeline.setPropertyValue,[foo,"visible",true]);

Parameters
target:Object — The object to set the property value on.
 
propertyName:String — The name of the property to set.
 
value:* — The value to assign to the property.