Packagestarling.animation
Classpublic class Juggler
InheritanceJuggler Inheritance Object
Implements IAnimatable

The Juggler takes objects that implement IAnimatable (like Tweens) and executes them.

A juggler is a simple object. It does no more than saving a list of objects implementing "IAnimatable" and advancing their time if it is told to do so (by calling its own "advanceTime"-method). When an animation is completed, it throws it away.

There is a default juggler available at the Starling class:

      var juggler:Juggler = Starling.juggler;
      

You can create juggler objects yourself, just as well. That way, you can group your game into logical components that handle their animations independently. All you have to do is call the "advanceTime" method on your custom juggler once per frame.

Another handy feature of the juggler is the "delayCall"-method. Use it to execute a function at a later time. Different to conventional approaches, the method will only be called when the juggler is advanced, giving you perfect control over the call.

      juggler.delayCall(object.removeFromParent, 1.0);
      juggler.delayCall(object.addChild, 2.0, theChild);
      juggler.delayCall(function():void { rotation += 0.1; }, 3.0);
      

See also

Tween
DelayedCall


Public Properties
 PropertyDefined By
  elapsedTime : Number
[read-only] The total life time of the juggler (in seconds).
Juggler
Protected Properties
 PropertyDefined By
  objects : Vector.<IAnimatable>
[read-only] The actual vector that contains all objects that are currently being animated.
Juggler
Public Methods
 MethodDefined By
  
Create an empty juggler.
Juggler
  
add(object:IAnimatable):uint
Adds an object to the juggler.
Juggler
  
advanceTime(time:Number):void
Advances all objects by a certain time (in seconds).
Juggler
  
contains(object:IAnimatable):Boolean
Determines if an object has been added to the juggler.
Juggler
  
containsDelayedCalls(callback:Function):Boolean
Figures out if the juggler contains one or more delayed calls with a certain callback.
Juggler
  
containsTweens(target:Object):Boolean
Figures out if the juggler contains one or more tweens with a certain target.
Juggler
  
delayCall(call:Function, delay:Number, ... args):uint
Delays the execution of a function until delay seconds have passed.
Juggler
  
purge():void
Removes all objects at once.
Juggler
  
remove(object:IAnimatable):uint
Removes an object from the juggler.
Juggler
  
removeByID(objectID:uint):uint
Removes an object from the juggler, identified by the unique numeric identifier you received when adding it.
Juggler
  
removeDelayedCalls(callback:Function):void
Removes all delayed and repeated calls with a certain callback.
Juggler
  
removeTweens(target:Object):void
Removes all tweens with a certain target.
Juggler
  
repeatCall(call:Function, interval:Number, repeatCount:int = 0, ... args):uint
Runs a function at a specified interval (in seconds).
Juggler
  
tween(target:Object, time:Number, properties:Object):uint
Utilizes a tween to animate the target object over time seconds.
Juggler
Property Detail
elapsedTimeproperty
elapsedTime:Number  [read-only]

The total life time of the juggler (in seconds).


Implementation
    public function get elapsedTime():Number
objectsproperty 
objects:Vector.<IAnimatable>  [read-only]

The actual vector that contains all objects that are currently being animated.


Implementation
    protected function get objects():Vector.<IAnimatable>
Constructor Detail
Juggler()Constructor
public function Juggler()

Create an empty juggler.

Method Detail
add()method
public function add(object:IAnimatable):uint

Adds an object to the juggler.

Parameters

object:IAnimatable

Returns
uint — Unique numeric identifier for the animation. This identifier may be used to remove the object via removeByID().
advanceTime()method 
public function advanceTime(time:Number):void

Advances all objects by a certain time (in seconds).

Parameters

time:Number

contains()method 
public function contains(object:IAnimatable):Boolean

Determines if an object has been added to the juggler.

Parameters

object:IAnimatable

Returns
Boolean
containsDelayedCalls()method 
public function containsDelayedCalls(callback:Function):Boolean

Figures out if the juggler contains one or more delayed calls with a certain callback.

Parameters

callback:Function

Returns
Boolean
containsTweens()method 
public function containsTweens(target:Object):Boolean

Figures out if the juggler contains one or more tweens with a certain target.

Parameters

target:Object

Returns
Boolean
delayCall()method 
public function delayCall(call:Function, delay:Number, ... args):uint

Delays the execution of a function until delay seconds have passed. This method provides a convenient alternative for creating and adding a DelayedCall manually.

Parameters

call:Function
 
delay:Number
 
... args

Returns
uint — Unique numeric identifier for the delayed call. This identifier may be used to remove the object via removeByID().
purge()method 
public function purge():void

Removes all objects at once.

remove()method 
public function remove(object:IAnimatable):uint

Removes an object from the juggler.

Parameters

object:IAnimatable

Returns
uint — The (now meaningless) unique numeric identifier for the animation, or zero if the object was not found.
removeByID()method 
public function removeByID(objectID:uint):uint

Removes an object from the juggler, identified by the unique numeric identifier you received when adding it.

It's not uncommon that an animatable object is added to a juggler repeatedly, e.g. when using an object-pool. Thus, when using the remove method, you might accidentally remove an object that has changed its context. By using removeByID instead, you can be sure to avoid that, since the objectID will always be unique.

Parameters

objectID:uint

Returns
uint — if successful, the passed objectID; if the object was not found, zero.
removeDelayedCalls()method 
public function removeDelayedCalls(callback:Function):void

Removes all delayed and repeated calls with a certain callback.

Parameters

callback:Function

removeTweens()method 
public function removeTweens(target:Object):void

Removes all tweens with a certain target.

Parameters

target:Object

repeatCall()method 
public function repeatCall(call:Function, interval:Number, repeatCount:int = 0, ... args):uint

Runs a function at a specified interval (in seconds). A 'repeatCount' of zero means that it runs indefinitely.

Parameters

call:Function
 
interval:Number
 
repeatCount:int (default = 0)
 
... args

Returns
uint — Unique numeric identifier for the delayed call. This identifier may be used to remove the object via removeByID().
tween()method 
public function tween(target:Object, time:Number, properties:Object):uint

Utilizes a tween to animate the target object over time seconds. Internally, this method uses a tween instance (taken from an object pool) that is added to the juggler right away. This method provides a convenient alternative for creating and adding a tween manually.

Fill 'properties' with key-value pairs that describe both the tween and the animation target. Here is an example:

          juggler.tween(object, 2.0, {
              transition: Transitions.EASE_IN_OUT,
              delay: 20, // -> tween.delay = 20
              x: 50      // -> tween.animate("x", 50)
          });
          

To cancel the tween, call 'Juggler.removeTweens' with the same target, or pass the returned 'IAnimatable' instance to 'Juggler.remove()'. Do not use the returned IAnimatable otherwise; it is taken from a pool and will be reused.

Note that some property types may be animated in a special way:

Parameters

target:Object
 
time:Number
 
properties:Object

Returns
uint