View source

class GTweenTimeline

package com.gskinner.motion

extends GTween

Available on all platforms

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.

Static methods

staticsetPropertyValue(target:Any, propertyName:String, value:Any):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

The object to set the property value on.

propertyName

The name of the property to set.

value

The value to assign to the property.

Constructor

@:value({ tweens : null, pluginData : null, props : null, values : null, duration : 1, target : null })new(?target:Any, duration:Float = 1, ?values:Any, ?props:Any, ?pluginData:Any, ?tweens:Array<Any>)

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

The object whose properties will be tweened. Defaults to null.

duration

The length of the tween in frames or seconds depending on the timingMode. Defaults to 10.

values

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

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

An object containing data for installed plugins to use with this tween. See .pluginData for more information.

tweens

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]

Variables

@:value(false)suppressCallbacks:Bool = false

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()).

Methods

@:value({ reverseParameters : null, reverseCallback : null, forwardParameters : null })addCallback(labelOrPosition:Any, forwardCallback:Function, ?forwardParameters:Array<Any>, ?reverseCallback:Function, ?reverseParameters:Array<Any>):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 add multiple callbacks at a specified position, however it is important to note that they will be played in the same order (most recently added first) playing both forwards and in reverse. You can enforce the order they are called in by offsetting the callbacks' positions by a tiny amount (ex. one at 2s, and one at 2.001s).

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

The function to call when playing forwards.

forwardParameters

Optional array of parameters to pass to the callback when it is called when playing forwards.

reverseCallback

The function to call when playing in reverse.

reverseParameters

Optional array of parameters to pass to the callback when it is called when playing in reverse.

addLabel(position:Float, label:String):Void

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

Parameters:

position

The position to add the label at in frames or seconds (as per the timing mode of this tween).

label

The label to add.

addTween(position:Float, 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

The starting position for this tween in frames or seconds (as per the timing mode of this tween).

tween

The GTween instance to add. Note that this can be any subclass of GTween, including another GTweenTimeline.

addTweens(tweens:Array<Any>):Void

Shortcut method for adding a number of tweens at once.

Parameters:

tweens

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():Void

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

goto(labelOrPosition:Any):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(labelOrPosition:Any):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(labelOrPosition:Any):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(labelOrPosition:Any):Void

Removes the callback(s) at the specified label or position.

Parameters:

labelOrPosition

The position of the callback(s) to remove in frames or seconds (as per the timing mode of this tween).

removeLabel(label:String):Void

Removes the specified label.

Parameters:

label

The label to remove.

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

The GTween instance to remove.

resolveLabelOrPosition(labelOrPosition:Any):Float

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.

Inherited Variables

Defined by GTween

@:value(true)autoPlay:Bool = true

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

@:value(Math.NaN)calculatedPosition:Float = Math.NaN

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 repeatCount*duration. This should not be set directly.

@:value(Math.NaN)calculatedPositionOld:Float = Math.NaN

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

data:Dynamic

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.

@:flash.propertydelay:Float

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

dispatchEvents:Bool

Available on flash

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:Float

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: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: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: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: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: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().

@:flash.propertypaused:Bool

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.

pluginData:Dynamic

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.

@:flash.propertyposition:Float

Gets and sets the position of the tween in frames or seconds (depending on .useFrames). This value will be constrained between -delay and repeatCount*duration. 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.

@:value(Math.NaN)positionOld:Float = Math.NaN

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

read onlyproxy:TargetProxy

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.setValue("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 setValue on the GTween instance with the appropriate value:

myGTween.proxy.rotation += 100;

Example 3: Sets an end property value (through setValue) 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: 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)

Note: Unlike the AS3 version of GTween, the Haxe version cannot delete properties or call methods using the proxy.

@:value(Math.NaN)ratio:Float = Math.NaN

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

@:value(Math.NaN)ratioOld:Float = Math.NaN

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

@:value(false)reflect:Bool = false

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.

@:value(1)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.

@:value(false)suppressEvents:Bool = false

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:Dynamic

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.

@:value(1)timeScale:Float = 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.

@:value(false)useFrames:Bool = false

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

Inherited Methods

Defined by GTween

beginning():Void

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

deleteValue(name:String):Bool

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

Parameters:

name

The name of the end property to delete.

end():Void

Jumps the tween to its end and pauses it. This is roughly the same as setting position=repeatCount*duration.

getInitValue(name:String):Float

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

getValue(name:String):Float

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

Parameters:

name

The name of the property to return a end value for.

getValues():Dynamic

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.

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.

@:value({ values : null })resetValues(?values:Dynamic):Void

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

Parameters:

properties

An object containing end property values.

setValue(name:String, value:Float):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

The name of the property to tween.

value

The numeric end value (the value to tween to).

setValues(values:Dynamic):Void

Shorthand method for making multiple setValue 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.setValues({x:200, y:400, rotation:null});

Parameters:

properties

An object containing end property values.

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});