CAAT.Actor

Life cycle

An actor by default is shown in the Scene as soon as the Scene is showing, and lasts forever. But the life cycle can be limited to certain range of time on the Scene timeline. By calling the method setFrameTime( start_time, duration ) an actors lifecycle can be controlled.

While the Scene time is less than actor's start_time or the Scene time is bigger than actor's start_time+duration, the Actor is considered to be out of frame time. Otherwise the Actor is considered to be in frame time and will be processed, have beaviors applied and probably be drawn on screen.

When the Scene time is greater than Actor.start_time+Actor.duration, besides out of frame time, the actor is considered to be expired. This is a readonly property by calling the method isExpired(). An Actor will only be set as Expired once. During this expiration setting, an Actor will notify its registered life cycle listeners. One of these listeners could for instance reset the Actor's frame time to let the Actor be again in frame time.

An actor's destroy operation can be delegated to CAAT by flagging an actor as discardable by calling the method setDiscardable(true). By default an Actor is non discardable. This means that at the end of a Director's frame cycle, that is, when finished processing and rendering a frame, every Actor that is expired, and flagged as discardable, will be thrown away from the scene and properly destroyed. This means that the Actor won't be drawn again since it is not present at Scene's Actor list anymore. The destroyed actor will also be removed from its parent. Upon destruction, the Actor will notify its listeners about this fact by calling the listener life cycle.

Life cycle listener

An Actor has some methods to expose its lifecycle to third party interested entities.

The actor methods addListener( actor_life_cycle_listener ), removeListener( actor_life_cycle_listener ) and fireEvent( event_type, time ) control an actor's lifecycle notification

The developer has only control over the add/remove methods, and it is the Director/Scene animation cycle that will notify the life cycle changes to interested parties for us by calling actor's fireEvent method.

The Actor life cycle listener must be an object with a method of the form

{ actorLifeCycleEvent : function( actor_ref, event_type, time) { } }

This method will receive on its parameters:

• actor_ref: A reference to the actor that is notifying its life cycle events. It is necessary since the developer can reuse the same listener for different Actors, and surely would like to know which of them is notifying about the event
• event_type: Event type. It must be one of these string values: expired, destroyed. The minimum action a life cycle Actor listener must perform is remove himself as listener, so that all references to the destroyed Actor are removed and the garbage collector could do its job properly.
• time: the Scene time at which the Actor has been destroyed.

Here's some sample code featuring life cycle listener. It is a green-colored pulsating rectangle. This Actor is in frame time since the Scene started, and will last for two seconds. After these two seconds, the life cycle listener is notified about Actor expiration, which will stablish again Actor's lifecycle to start again one second after notification and lasting for two more seconds.

                 // Initialize director.
                 var _director_2= new CAAT.Director().initialize(
                         400,
                         100,
                         document.getElementById('_c2'));

                 // create scene.
                 var _scene_2=    _director_2.createScene();

                 // create a simple actor. will last for two seconds on Scene.
                 var _pulsating_actor_2= new CAAT.Actor().
                         create().
                         setBounds(10,10,80,80).
                         setFillStyle('#00ff00').
                         setFrameTime(0,2000);

                 // add a life cycle listener to the actor.
                 _pulsating_actor_2.addListener( {
                     actorLifeCycleEvent : function( actor, event_type, time ) {

                         // on expiration notification,
                         if ( event_type==='expired' ) {
                             // just make the Actor sleep for 1 second.
                             // After waking up, last for 2 seconds.
                             actor.setFrameTime( time+1000, 2000 );
                         }
                     }
                 } );

                 // don't forget to add the actor to the scene.
                 _scene_2.addChild( _pulsating_actor_2 );

                 // set 20 fps animation
                 CAAT.loop(20);