Handling Events

Events are actions that occur while a SWF file is playing. An event such as a mouse click or a keypress is called a user event because it occurs as a result of direct user interaction. An event that Flash Player generates automatically, such as the initial appearance of a movie clip on the Stage, is called a system event because it isn’t generated directly by the user.

For your application to react to events, you must use event handlers—ActionScript code associated with a particular object and event. For example, when a user clicks a button on the Stage, you might advance the playhead to the next frame. Or when an XML file finishes loading over the network, the contents of that file might appear in a text field.

You can handle events in ActionScript in different ways depending on the type of event. The following lists each of the ways to handle events in ActionScript. Not all of the following apply to all event types.

• Using event handler methods
• Using event listeners
• Using button and movie clip event handlers, specifically, the on handler and onClipEvent handler.
• Broadcasting events from component instances

Using button and movie clip event handlers is not recommend, because they require that you attach code to objects. Instead, the best practice is to place code in frame scripts on the Timeline, or in a class file using event handler methods whenever possible.

Note: Using event handlers with the MovieClip.loadMovie method can be unpredictable. If you attach an event handler to a button using on(), or if you create a dynamic handler using an event handler method such as the MovieClip.onPress handler, and then you call loadMovie(), the event handler is not available after the new content is loaded. However, if you use the onClipEvent handler or the on handler to attach an event handler to a movie clip, and then call loadMovie() on that movie clip, the event handler is still available after the new content is loaded.

Event Handler Methods

An event handler method is a method of a class that is invoked when an event occurs on an instance of that class. For example, the MovieClip class defines an onPress event handler that is invoked whenever the mouse is pressed on a movie clip object. Unlike other methods of a class, however, you don’t invoke an event handler directly; Flash Player invokes it automatically when the appropriate event occurs.

The following ActionScript classes are examples of classes that define event handlers: Button, ContextMenu, ContextMenuItem, Key, LoadVars, LocalConnection, Mouse, MovieClip, MovieClipLoader, Selection, SharedObject, Sound, Stage, TextField, XML and XMLSocket. For more information about the event handlers they provide, see the entries for each class in ActionScript 2.0 Language Reference. Note that the word handler is added in the title of each event handler.

By default, event handler methods are undefined: when a particular event occurs, its corresponding event handler is invoked, but your application doesn’t respond further to the event. To have your application respond to the event, you define a function with the function statement and then assign that function to the appropriate event handler. The function you assign to the event handler is then automatically invoked whenever the event occurs.

An event handler consists of three parts: the object to which the event applies the name of the object’s event handler method, the function you assign to the event handler, and your code. The following example shows the basic structure of an event handler:

object.eventMethod = function ():Void {
     // Your code here, responding to event.
 };  

For example, suppose you have a button named next_btn on the Stage. The following code assigns a function to the button’s onPress event handler; this function advances the playhead to the next frame in the current timeline:

next_btn.onPress = function ():Void {
     nextFrame(); 
};  

You can assign a function reference, receive passed parameters to the event handler, assign functions to event handlers, and override methods.

Event Listeners

Event listeners let an object, called a listener object, receive events broadcast by another object, called a broadcaster object. The broadcaster object registers the listener object to receive events generated by the broadcaster. For example, you can register a movie clip object to receive onResize notifications from the Stage, or a button instance could receive onChanged notifications from a text field object. You can register multiple listener objects to receive events from a single broadcaster, and you can register a single listener object to receive events from multiple broadcasters.

The listener-broadcaster model for events, unlike event handler methods, lets you have multiple pieces of code listen to the same event without conflict. Event models that do not use the listener/broadcaster model, such as XML.onLoad(), can be problematic when various pieces of code are listening to the same event; the different pieces of code have conflicts over control of that single XML.onLoad callback function reference. With the listener/broadcaster model, you can easily add listeners to the same event without worrying about code bottlenecks.

Note: The following ActionScript classes can broadcast events: Key, Mouse, MovieClipLoader, Selection, Stage, and TextField.

Event Listener Model

The event model for event listeners is similar to the model for event handlers (see Using event handler methods), with two main differences:

• You assign the event handler to the listener object, not the object that broadcasts the event.
• You call a special method of the broadcaster object, addListener(), which registers the listener object to receive its events.

The following code outlines the event listener model:

var listenerObject:Object = new Object();
 listenerObject.eventName = function(eventObj:Object):Void {

     // Your code here
 };
 broadcasterObject.addListener(listenerObject); 

The code starts with an object, listenerObject, with a property eventName. Your listener object can be any object, such as an existing object, movie clip, or button instance on the Stage, or it can be an instance of any ActionScript class. For example, a custom movie clip could implement the listener methods for Stage listeners. You could even have one object that listens to several types of listeners.

The eventName property is an event that occurs on broadcasterObject, which then broadcasts the event to listenerObject. You can register multiple listeners to one event broadcaster.

You assign a function to the event listener that responds to the event in some way.

Last, you call the addListener() method on the broadcaster object, passing the listener object to the addListener() method.

To unregister a listener object from receiving events, you call the removeEventListener() method of the broadcaster object, passing it the name of the event to remove, and the listener object.

broadcasterObject.removeListener(listenerObject); 

• Using Event Listeners with Component
• Broadcasting Events from Component Instances
• Creating Movie Clips with Button States
• Event Handler Scope
• Scope of the this Keywork
• Using the Delegate Class