Recipe 1.5. Handling Events

Problem

You want to have some code repeatedly execute.

Solution

Add a listener to the enterFrame event and assign a method as a handler.

Discussion

In ActionScript 2.0 handling the enterFrame event was quite simple. You just had to create a timeline function called onEnterFrame and it was automatically called each time a new frame began. In ActionScript 3.0, you have much more control over the various events in a .swf, but a little more work is required to access them.

If you are familiar with the EventDispatcher class from ActionScript 2.0, you should be right at home with ActionScript 3.0's method of handling events. In fact, EventDispatcher has graduated from being an externally defined class to being the base class for all interactive objects, such as sprites.

To respond to the enterFrame event, you have to tell your application to listen for that event and specify which method you want to be called when the event occurs. This is done with the addEventListener method, which is defined as follows:

addEventListener(type:String, listener:Function)

There are additional parameters you can look up in the help files, but this is the minimum implementation.

The type parameter is the type of event you want to listen to. In this case, it would be the string, "enterFrame". However, using string literals like that opens your code to errors that the compiler cannot catch. If you accidentally typed "enterFrane", for example, your application would simply listen for an "enterFrane" event. To guard against this, it is recommended that you use the static properties of the Event class. You should already have the Event class imported, so you can call the addEventListener method as follows:

addEventListener(Event.ENTER_FRAME, onEnterFrame);

Now if you accidentally typed Event.ENTER_FRANE, the compiler would complain that such a property did not exist.

The second parameter, onEnterFrame, refers to another method in the class. Note, that in ActionScript 3.0, there is no requirement that this method be named onEnterFrame. However, naming event handling methods on plus the event name is a common convention. This method gets passed an instance of the Event class when it is called. Therefore, you'll need to import that class and define the method so it accepts an event object:

import flash.events.Event; private function onEnterFrame(event:Event) { }

The event object contains information regarding the event that may be useful in handling it. Even if you don't use it, you should still set your handler up to accept it. If you are familiar with the ActionScript 2.0 version of EventDispatcher, you'll see a difference in implementation here. In the earlier version, there was an issue with the scope of the function used to handle the event, which often required the use of the Delegate class to correct. In ActionScript 3.0, the scope of the handling method remains the class of which it is a method, so there is no necessity to use Delegate to correct scope issues.

Here is a simple application that draws successive random lines, using all the concepts discussed in this recipe:

package {     import flash.display.Sprite;     import flash.events.Event;          public class ExampleApplication extends Sprite {                  public function ExampleApplication(  ) {             graphics.lineStyle(1, 0, 1);             addEventListener(Event.ENTER_FRAME, onEnterFrame);         }         private function onEnterFrame(event:Event):void {             graphics.lineTo(Math.random(  ) * 400, Math.random(  ) * 400);         }     } }