Packageflare.animate
Classpublic class Transitioner
InheritanceTransitioner Inheritance Parallel Inheritance Transition Inheritance flash.events.EventDispatcher
ImplementsIValueProxy

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.



Public Properties
 PropertyDefined by
 InheritedautoDuration : Boolean
If true, the duration of this sequence is automatically determined by the longest sub-transition.
Parallel
 InheritedDEFAULT_EASING : Function
[static] Default easing function: a cubic slow-in slow-out.
Transition
 Inheriteddelay : Number
The delay between a call to play and the actual start of the transition, in seconds.
Transition
 Inheritedduration : Number
The duration (length) of this Transition, in seconds.
Parallel
 Inheritedeasing : Function
Easing function used to pace this Transition.
Transition
 Inheritedenabled : Boolean = true
Flag indicating if step events should be processed.
Transition
 Inheritedid : 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
 Inheritedprogress : Number
Fraction between 0 and 1 indicating the current progress of this transition.
Transition
 Inheritedreverse : Boolean
Indicates if this Transition is running in reverse.
Transition
 Inheritedrunning : Boolean
Indicates if this Transition is currently running.
Transition
 InheritedtotalDuration : Number
The total duration, including both delay and active duration.
Transition
Protected Properties
 PropertyDefined by
 Inherited_reverse : Boolean = false
Flag indicating this Transition is running in reverse.
Transition
 Inherited_running : Boolean = false
Flag indicating this Transition is currently running.
Transition
 Inherited_trans : Array
Array of parallel transitions
Parallel
Public Methods
 MethodDefined 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
 Inherited
add(t:Transition):void
Adds a new sub-transition to this parallel transition.
Parallel
 Inherited
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
 Inherited
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
  
[static] Gets a transitioner instance depending upon the input value.
Transitioner
 Inherited
pause():void
Pauses the transition at its current position.
Transition
 Inherited
play(reverse:Boolean = false):void
Starts running the transition.
Parallel
 Inherited
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
 Inherited
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
 Inherited
stagger(delay:Number = 0.05, reverse:Boolean = false):Parallel
Staggers the start of each sub-transition by a given interval.
Parallel
 Inherited
step(ef:Number):void
Steps each sub-transition.
Parallel
 Inherited
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
Protected Methods
 MethodDefined by
 Inherited
Computes the duration of this parallel transition.
Parallel
  
end():void
Ends each sub-transition.
Transitioner
 Inherited
setup():void
Sets up each sub-transition.
Parallel
 Inherited
start():void
Starts each sub-transition.
Parallel
Events
 EventSummaryDefined by
 Inherited  Transition
 Inherited
end
 Transition
 Inherited  Transition
 Inherited  Transition
Public Constants
 ConstantDefined by
  DEFAULT : Transitioner
[static] The default, immediate-mode transitioner instance.
Transitioner
Protected Constants
 ConstantDefined by
 InheritedINIT : int = 1
[static] Constant indicating this Transition has been initialized.
Transition
 InheritedRUN : int = 2
[static] Constant indicating this Transition is currently running.
Transition
 InheritedSETUP : int = 0
[static] Constant indicating this Transition needs initialization.
Transition
Property detail
immediateproperty
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
optimizeproperty 
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:

  1. 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.
  2. 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
DEFAULTconstant
public static const DEFAULT:Transitioner

The default, immediate-mode transitioner instance.