flare.animate.Transitioner

Package	flare.animate
Class	public class Transitioner
Inheritance	Transitioner Parallel Transition flash.events.EventDispatcher
Implements	IValueProxy

Parallel transition with convenience methods for adding new object tweens, helping to incrementally construct a group of transitions. A Transitioner will automatically generate tweens for any number of items and properties, simplifying the task of creating animated transitions.

For example, the following code creates a 1 second animation for two items. The first item is translated to the point (50,50) and the second item is scaled along the x dimension to twice the normal size.

  var item1:Sprite, item2:Sprite; // assume these are two drawn sprites
  var t:Transitioner = new Transitioner(1); // create 1-second transition
  t.$(item1).x = 50;
  t.$(item1).y = 50;
  t.$(item2).scaleX = 2;
  t.play();

In the code above, the $ method takes an item (this can be any ActionScript object, but is often a DisplayObject instance) and returns an Object which stores the names of the properties to animate and their target values. Behind the scenes, the Transitioner automatically creates Tween objects as needed.

The object returned by the $ method is a proxy object that passes the values to underlying tweens as needed. This same proxy object is reused across calls to the $ method so do not attempt to use multiple return values from the $ method simultaneously. The following example shows what you should not do!

  var o1:Object = t.$(item1);
  var o2:Object = t.$(item2); // o2==o1, now configured for item2
  o1.x = 5; // actually sets the value 5 to item2, NOT item1

A transitioner can also be set to "immediate" mode, either by setting the immediate property to true, or by passing in NaN as the duration value to the constructor. When in immediate mode, a transitioner will NOT generate Tween instances to animate the properties. Instead, the transitioner will set the values of the target objects immediately. For example, when in immediate mode, the $ operator is equivalent to directly setting the property: t.$(item1).x = 50 has exactly the same result at t.x = 50. The static property Transitioner.DEFAULT provides a default instance of an immediate-mode transitioner.

With these features, transitioners provide a highly flexible way to update values in your application. You can write layout and other methods once, using a transitioner to update all the property values. When animation is desired, a standard transitioner can be passed in to your routines. When immediate updates are desired, you can reuse the same code, but just pass in a transitioner in immediate mode instead. Whether or not value updates are animated or immediate then becomes easy to control.

Transitioners also provide optimizations to improve animation performance. However, they are not enabled by default, as the optimizations make some assumptions about how the transitioner will be used. See the optimize property and dispose method for more information.

	Property	Defined by
		autoDuration : Boolean If true, the duration of this sequence is automatically determined by the longest sub-transition.	Parallel
		DEFAULT_EASING : Function [static] Default easing function: a cubic slow-in slow-out.	Transition
		delay : Number The delay between a call to play and the actual start of the transition, in seconds.	Transition
		duration : Number The duration (length) of this Transition, in seconds.	Parallel
		easing : Function Easing function used to pace this Transition.	Transition
		enabled : Boolean = true Flag indicating if step events should be processed.	Transition
		id : String A unique name identifying this schedulable object.	Transition
		immediate : Boolean Immediate mode flag, used to bypass tween generation and perform immediate updates of target object values.	Transitioner
		optimize : Boolean Flag indicating if aggressive optimization should be applied.	Transitioner
		progress : Number Fraction between 0 and 1 indicating the current progress of this transition.	Transition
		reverse : Boolean Indicates if this Transition is running in reverse.	Transition
		running : Boolean Indicates if this Transition is currently running.	Transition
		totalDuration : Number The total duration, including both delay and active duration.	Transition

	Property	Defined by
		_reverse : Boolean = false Flag indicating this Transition is running in reverse.	Transition
		_running : Boolean = false Flag indicating this Transition is currently running.	Transition
		_trans : Array Array of parallel transitions	Parallel

	Method	Defined by
		Transitioner(duration:Number = 1, easing:Function = null, optimize:Boolean = false, id:String = null) Creates a new Transitioner with specified duration.	Transitioner
		_(o:Object):Tween Returns the Tween for the given object, creating a new tween if no tween is yet associated with the object.	Transitioner
		$(o:Object):Object Returns the values object of the Tween for the given object.	Transitioner
		add(t:Transition):void Adds a new sub-transition to this parallel transition.	Parallel
		cancelled():void Informs this transition that it was cancelled by the scheduler.	Transition
		dispose():void Disposes of the internal state of this transitioner.	Transitioner
		endBounds(d:DisplayObject, coords:DisplayObject):Rectangle Computes the approximate bounds of the given object after this transitioner has been run.	Transitioner
		endSize(d:DisplayObject, r:Rectangle = null):Rectangle Computes the approximate size of the given object after this transitioner has been run.	Transitioner
		evaluate(time:Number):Boolean Evaluates the Transition, stepping the transition forward.	Transition
		getDelay(o:Object):Number Gets the delay of the tween for the given object.	Transitioner
		getValue(o:Object, name:String):* Retrieves property values for a target object.	Transitioner
		hasTweenFor(o:Object):Boolean Indicates if the Transitioner contains a Tween for the given object.	Transitioner
		instance(t:*):Transitioner [static] Gets a transitioner instance depending upon the input value.	Transitioner
		pause():void Pauses the transition at its current position.	Transition
		play(reverse:Boolean = false):void Starts running the transition.	Parallel
		remove(t:Transition):Boolean Removes a sub-transition from this parallel transition.	Parallel
		removeChild(dobj:DisplayObject, b:Boolean = true):void Sets the removal status of a display object with this transition.	Transitioner
		reset():void Resets the transition, so that any cached starting values are cleared and reset the next time this transition is played.	Transition
		setDelay(o:Object, delay:Number):void Sets the delay of the tween for the given object.	Transitioner
		setValue(o:Object, name:String, value:*):void Sets property values for a target object.	Transitioner
		stagger(delay:Number = 0.05, reverse:Boolean = false):Parallel Staggers the start of each sub-transition by a given interval.	Parallel
		step(ef:Number):void Steps each sub-transition.	Parallel
		stop():void Stops the transition and completes it.	Transition
		willRemove(d:DisplayObject):Boolean Indicates if a display object is scheduled to be removed from the display list when this transition completes.	Transitioner

	Method	Defined by
		computeDuration():void Computes the duration of this parallel transition.	Parallel
		end():void Ends each sub-transition.	Transitioner
		setup():void Sets up each sub-transition.	Parallel
		start():void Starts each sub-transition.	Parallel

	Constant	Defined by
		DEFAULT : Transitioner [static] The default, immediate-mode transitioner instance.	Transitioner

	Constant	Defined by
		INIT : int = 1 [static] Constant indicating this Transition has been initialized.	Transition
		RUN : int = 2 [static] Constant indicating this Transition is currently running.	Transition
		SETUP : int = 0 [static] Constant indicating this Transition needs initialization.	Transition

Property detail

immediate

property

immediate:Boolean [read-write]

Immediate mode flag, used to bypass tween generation and perform immediate updates of target object values.

Implementation
public function get immediate():Boolean
public function set immediate(value:Boolean):void

optimize

property

optimize:Boolean [read-write]

Flag indicating if aggressive optimization should be applied. This can significantly decrease processing time when large numbers of elements are involved. However, the optimization process makes a few assumptions about how the transitioner will be used. If these assumptions are not met, the animations may exhibit unexpected behaviors.

The assumptions made for optimized transitioners are:

The property values of tweened objects will not change between the time their target values are set and the transition is played. This allows the transitioner to avoid creating tweens when properties have the same starting and ending values, and immediately set values for DisplayObjects that are not visible. However, this means the starting value must stay the same. In particular, this means that optimized transitioners are often inappropriate for use within a Sequence.
The transitioner will only be played once, then discarded. This allows the transitioner to automatically recycle all generated Tween and Interpolator instances, reducing initialization time across transitioners by reusing objects.

Implementation
public function get optimize():Boolean
public function set optimize(value:Boolean):void

Constructor detail

Transitioner

()

constructor

public function Transitioner(duration:Number = 1, easing:Function = null, optimize:Boolean = false, id:String = null)

Creates a new Transitioner with specified duration.

Parameters

	`duration:Number` (default = `1`) — the length of the transition. If this value is NaN, the transitioner will be in immediate mode, in which all changes are immediately applied and no tweens are generated.

	`easing:Function` (default = `null`) — the easing function to use for this transition. If null, the function Easing.none will be used.

	`optimize:Boolean` (default = `false`) — boolean flag indicating if the transitioner should attempt to optimize tween construction. See the documentation for the `optimize` property for mode details.

	`id:String` (default = `null`) — an optional id. If non-null, any other running transition with the same id will be canceled when this transitioner is played.

Method detail

()

method

public function _(o:Object):Tween

Returns the Tween for the given object, creating a new tween if no tween is yet associated with the object. This method returns null if the transitioner is in immediate mode.

Parameters

o:Object — the target object

Returns

Tween — a tween for the input target object, or null if this transitioner is in immediate mode.

()

method

public function $(o:Object):Object

Returns the values object of the Tween for the given object. If no tween is associated with the object, a new one is created. If the transitioner is in immediate mode, then no Tween will be created. Instead, the input object will be returned. This allows value updates to be set immediately, rather than animated by a tween.

Parameters

o:Object — the target object

Returns

Object — the values object for the target object's tween, or the target object itself if this transitioner is in immediate mode.

dispose

()

method

public override function dispose():void

Disposes of the internal state of this transitioner. Contained tweens and their interpolators will be collected and recycled for future reuse, improving initialization times for subsequent transitioners. This method is automatically called at the end of the transition if the optimize flag is true. Otherwise, this method can be invoked manually when a transitioner is no longer needed.

end

()

method

protected override function end():void

Ends each sub-transition.

endBounds

()

method

public function endBounds(d:DisplayObject, coords:DisplayObject):Rectangle

Computes the approximate bounds of the given object after this transitioner has been run. This calculation is performed by applying the final scaleX, scaleY, size, x, and y values of the object.

Parameters

	`d:DisplayObject` — the display object to compute the size for

	`coords:DisplayObject` — the target coordinate space for the bounds

Returns

Rectangle — a rectangle whose width and height properties contain the end size values.

endSize

()

method

public function endSize(d:DisplayObject, r:Rectangle = null):Rectangle

Computes the approximate size of the given object after this transitioner has been run. This calculation is performed by applying the final scaleX, scaleY, and size values of the object.

Parameters

	`d:DisplayObject` — the display object to compute the size for

	`r:Rectangle` (default = `null`) — a rectangle for storing the results

Returns

Rectangle — a rectangle whose width and height properties contain the end size values.

getDelay

()

method

public function getDelay(o:Object):Number

Gets the delay of the tween for the given object. If the transitioner is in immediate mode or no tween has been created for the input object, this method returns zero.

Parameters

o:Object — the object to get the delay for

Returns

Number — the delay of the tween, or zero if there is no tween

getValue

()

method

public function getValue(o:Object, name:String):*

Retrieves property values for a target object. This method has the same effect as accessing a property using the object returned by the $ method.

If the transitioner is in immediate mode, the property name will be parsed and the value retrieved diretly from the target object. If the transitioner is not in immediate mode, this method will first try to lookup the value in the tween values for the target object. If this does not succeed, the property value will be retrieved directly from the target object itself as in the immediate mode case.

Parameters

	`o:Object` — the target object

	`name:String` — the property name string

Returns

* — the property value for the target object, either from the target object's tween values, or, failing that, the object itself.

hasTweenFor

()

method

public function hasTweenFor(o:Object):Boolean

Indicates if the Transitioner contains a Tween for the given object.

Parameters

o:Object — the object to test for

Returns

Boolean — true if there is a Tween for the object, false otherwise

instance

()

method

public static function instance(t:*):Transitioner

Gets a transitioner instance depending upon the input value.

Parameters

t:* — input determining the transitioner instance to return. If the input is a transitioner, it is simply returned. If the input is a number, a new Transitioner with duration set to the input value is returned, unless the number is less than zero, in which case the default immediate-mode transitioner is returned. If the input is null, Transitioner.DEFAULT is returned.

Returns

Transitioner — a Transitioner instance determined by the input

removeChild

()

method

public function removeChild(dobj:DisplayObject, b:Boolean = true):void

Sets the removal status of a display object with this transition. If true, the display object will be removed from its parent in the display list when the transition completes. If this transitioner is in immediate mode, any removals are performed immediately.

Parameters

	`dobj:DisplayObject` — a display object

	`b:Boolean` (default = `true`) — true to remove the display object from the display list at the end of the transition (the default). If false, the removal status will be updated so that the display object will not be removed (not applicable in immediate mode).

setDelay

()

method

public function setDelay(o:Object, delay:Number):void

Sets the delay of the tween for the given object. If the transitioner is in immediate mode, this method has no effect.

Parameters

	`o:Object` — the object to set the delay for

	`delay:Number` — the delay, in seconds

setValue

()

method

public function setValue(o:Object, name:String, value:*):void

Sets property values for a target object. This method has the same effect as setting a property on the object returned by the $ method.

If the transitioner is in immediate mode, the property name will be parsed and the value set at the end of the property chain. If the transitioner is not in immediate mode, the property name and values will simply be added to a Tween. If no Tween is associated with the input object, a new one will be created.

Parameters

	`o:Object` — the target object

	`name:String` — the property name string

	`value:*` — the property value to set

willRemove

()

method

public function willRemove(d:DisplayObject):Boolean

Indicates if a display object is scheduled to be removed from the display list when this transition completes. This method always returns false if this transitioner is in immediate mode.

Parameters

d:DisplayObject — a display object

Returns

Boolean — true if the display object will be removed from the display list at the end of this transition, false otherwise. This method always returns false if the transitioner is in immediate mode.

Constant detail

DEFAULT

constant

public static const DEFAULT:Transitioner

The default, immediate-mode transitioner instance.

Flare API Documention	All Packages \| All Classes \| Index \| Frames No Frames
Class Transitioner	Properties \| Methods \| Events \| Constants