Event Handing in ActionScript 3.0

By Blue_Chi | Flash CS3 | ActionScript 3.0 | Beginner

Event handling is the process by which any sort of interactivity is created in ActionScript 3.0. This tutorial will teach how to make your movie jump to life, whether it was by reacting to a mouse click, a keyboard stroke, or any event happening in Flash using the Event Handling system of AS3.

Our tutorial is divided into the following sections:

  1. Basic Event Handling Using the .addEventListener() method.
  2. Unregistered Events Listeners using the removeEventListener() method.
  3. Working with Event Targets.

Basic Event Handling Usage

An ActionScript Event is any interaction happening in the Flash environment, whether it was a mouse click, the movement of the timeline to a new frame, the completion of the loading process of an external asset, or any other occurrence. ActionScript can make any object react to any event by using an Event Listener. An event listener is basically a function created with the very specific purpose of reacting to an event. An object can react to an event using an event listener. This is done by using the .addEventListener method. This method simply registers an Event Listener and an Event to an object.

The process described above is written in ActionScript using in the format shown below:

myObject.addEventListener(Event, eventListenerFunction);

Our Event Listener will obviously have to be specified by declaring the function the same way any other function is declared in ActionScript, the only difference is that the listener function must have one argument to represent the event. This event argument can have any identifier as its name, I usually use the letter 'e' for it as shown in the generalized code below:

myObject.addEventListener(Event, eventListenerFunction);

function eventListenerFunction (e:Event):void{
//ActionScript statements to be executed when the event happens.
}

So for example, if we want a graphical object placed on stage to act like a button by reacting to a mouse click over it, we can simply register an event and an event listener to it this way:

myButton.addEventListener(MouseEvent.CLICK, myClickReaction);

function myClickReaction (e:MouseEvent):void{
trace("I was clicked!");
}

The format above is the basic format at which any event can be registered. Depending on the event you are trying to listen to, the object and the event to register for will differ. For example, if you are using the Loader Class to load an external asset at run time, you can perform a specific action only when the asset you are trying to load finishes loading. For this particular purpose you will need to register for the Event.COMPLETE as shown in the example below:

my_loader.contentLoaderInfo.addEventListener(Event.COMPLETE, startListener);

function startListener (e:Event):void{
trace("Loading Completed");
}

You need to study each class on its own to learn about its supported events and how to use those specific events related to it. The easiest way for doing this is by checking the built-in ActionScript Reference.

Unregistering Event Listeners

The earlier heading explained the basic technique for registering an event listener using the .addEventListener() method. However, you must be cautious at how you use this method and only use it for events that you actually expected to happen, otherwise you must always remove any unnecessary event listeners to reduce the processing resources required by the Flash application. This practice can help ensure that your Flash movies do not crash or become unresponsive because of overwhelming event listeners.

To unregister an event you can use the .removeEventListener() method in the same exact way the .addEventListener() method is used. This method requires specifying the object from which the event listener is to be unregistered, the event to stop listening to, and the function that was assigned to this specific event. Here is a generalized code on the usage of this method:

myObject.removeEventListener(Event, eventListenerFunction);

For example, if an event listener function was registered to be triggered on the entry of each new frame on the main timeline we would have registered it this way:

this.removeEventListener(Event.ENTER_FRAME, loading);
The code above is taken from a movie that uses a graphical preloader to play the movie only when it finishes loading. You can see how that movie uses an event listener to track the loading progress of the movie and then unregisters this event when it is no longer needed. Click here to read the AS3 Preloader Tutorial.

Event Targets and Event Propagation

Depending on the event handled, an event would usually occur to a specific object. For example, a click event will happen to a specific button and a load complete event will happen to a specific instance of the loader class. Referring to these objects in basic movies is pretty simple, for example, if we want an object to become hidden when clicked, we can refer to the instance name of the object from within the listener function to hide it this way:

my_btn.addEventListener(MouseEvent.CLICK, hideMe);

function hideMe(e:MouseEvent):void{
my_btn.visible=false;
}

That should work, but sometimes when working in more complex movies you might want to refer to the target of your event without specifying its name, most probably because you want to reuse the same listener function with more than one object. To do that we use the keyword e.currentTarget from within the listener function. For example, the code above could be rewritten this way:

my_btn.addEventListener(MouseEvent.CLICK, hideMe);

function hideMe(e:MouseEvent):void{
e.currentTarget.visible=false;
}

And that will create the same exact previous result. However, we can now reuse this listener function for more than one object without fear of breaking the code because of the smart reference to our event target:

my1_btn.addEventListener(MouseEvent.CLICK, hideMe);
my2_btn.addEventListener(MouseEvent.CLICK, hideMe);


function hideMe(e:MouseEvent):void{
e.currentTarget.visible=false;
}

If you are aware of the Display List system of ActionScript you would realize that some display containers (such as MovieClips) can have other display objects or display object containers inside them as well. It is possible to refer to the children of an object to which an event was registered using the keyword e.target (as opposed to e.currentTarget) to refer directly to these objects. This allows a developer to control any number of objects individually as long as they are hosted within a display object container by referring to them using the e.target keyword. For example, if we have a MovieClip movie that has three buttons, we can hide each of these buttons on its own when individually clicked by registering ONE event listener to ONE object only, which is in this case the display object container, i.e. the menu MovieClip, here is an example:

var myMenu_mc:MovieClip = new MovieClip();

myMenu_mc.addChild(my1_btn);
myMenu_mc.addChild(my2_btn);
myMenu_mc.addChild(my3_btn);

myMenu_mc.addEventListener(MouseEvent.CLICK, hideThisButton);

function hideThisButton(e:MouseEvent):void{
e.target.visible=false;
}

The MovieClip myMenu_mc has three children, these are my1_btn, my2_btn, and my3_btn. The event listener function registered with myMenu_mc refers to e.target instead of e.currentTarget so that it refers to the actual button clicked and not the display object container that hosts them.

This last bit is relatively an advanced technique which might not be apparently helpful to novice ActionScript programmers, but it is one of the best techniques for reducing the amount of code you write. Our upcoming tutorials will show you how to make use of it in practical examples.

This concludes our basic tutorial on how to use the event handling system in ActionScript 3.0. We have not talked about advanced aspects of events handling such as bubbling, garbage collection, and creating custom events. We will hopefully talk about these in an advanced tutorial in the near future.

I hope that you found this tutorial helpful. Feel free to post at the Oman3D Forum if you have any questions or comments.

- End of Tutorial.