Macromedia Flash 8 Bible

What a Typical Listener Looks Like

Just about any object in a Flash movie can be a listener. You can add custom methods to MovieClip objects, for example, or you can create an instance of the Object class that exists only in ActionScript. To create a generic object, use the following syntax:

var oListener:Object = new Object();

or

var oListener:Object = {};

Once you have created an object that behaves as a listener, you can create methods for the listener geared toward the behavior of the component it observes. For example, if you wanted to do something when a Button component instance is clicked, you can add a click() method (or handler) to the listener object.

oListener.click = function(oEvent:Object):Void {
   trace("---listener received an event broadcast");
};

In this simple example, a trace() message is sent to the Output panel. You could add further actions to the click() method, performing more tasks necessary for your Flash movie.

Letting the Component Know Who its Listeners Are

Once a listener has a method to invoke, you need to assign the listener object (or its method) to the component that will be broadcasting events. For our previous example, you could assign the listener to a Button component instance named cbt by using the following code:

cbt.addEventListener("click", oListener);

or

cbt.addEventListener("click", oListener.click);

The addEventListener() method takes two parameters: the event being broadcast and the listener object (or method). Each component has its unique event names. The Button component, used in this example, has a click event, which is broadcast to all listeners when the user clicks the Button component instance.

Most components also broadcast additional information to the listeners, passed as parameters to the listener's method. All of the UI components pass an event information object to their listeners. The exact properties of this object vary from one component to the next, but some are consistent. In the following listener method, the oEvent parameter from the Button instance contains several properties, including oEvent.target, which is a reference to the Button instance.

oListener.click = function(oEvent:Object):Void {
   trace(oEvent.target + " was clicked.");
   trace("The broadcasted event was  "+ oEvent.type);
};

The type property, as you can see in the example code, can tell the listener what type of event was broadcast to it. In this way, you can create one method for a listener and have it handle different event types with specific code.

We'll show you how to create a simple example that demonstrates how a listener works:

1. Create a new Flash document, and save it as button_listener.fla.

2. Rename Layer 1 to cbt. This layer will hold an instance of the Button component.

3. Open the Components panel (Ctrl+F7 or z+F7) and drag an instance of the Button component from the User Interface set to the Stage.

4. Select the new instance, and in the Property inspector, name the instance cbt. Click the Parameters tab and assign a new label to the button, such as My Button.

5. Create a new layer named actions, and place it at the top of the layer stack.

6. Select frame 1 of the actions layer, and open the Actions panel (F9, or Option+F9 on Mac). Add the following code to the Script pane:

   var cbt:mx.controls.Button;
   
   var oListener:Object = new Object();
   oListener.click = function(oEvent:Object):Void {
      for(var i in oEvent){
         trace(i + "= "+ oEvent[i]);
      }
   };
   
   cbt.addEventListener("click", oListener);
   
   

7. Save your document, and test it (Ctrl+Enter or z+Enter). When you click the cbt instance, you should see the following text in the Output panel:

   target = _level0.cbt
   type = click
   

   This output illustrates the two properties of the oEvent object broadcasted by the Button component. The event's name is "click" and the target property is a reference to the object broadcasting the event, cbt (_level0.cbt).