Flash CS3 Documentation

Using ActionScript 2.0 Components > Handling Component Events > Using listeners to handle events > Using listener objects

Using listener objects

To use a listener object, you can either use the this keyword to specify the current object as the listener, use an object that already exists in your application, or create a new object.

• Use this in most situations.

  It's often easiest to use the current object (this) as a listener, because its scope contains the components that need to react when the event is broadcast.

• Use an existing object if it is convenient.

  For example, in a Flash Form Application, you may want to use a form as a listener object if that form contains the components that react to the event. Place the code on a frame of the form's timeline.

• Use a new listener object if many components are broadcasting an event (for example, the click event) and you want only certain listener objects to respond.

If you use the this object, define a function with the same name as the event you want to handle; the syntax is as follows:

function eventName(evtObj:Object){
    // your code here
};

If you want to use a new listener object, you must create the object, define a property with the same name as the events, and assign the property to a callback function that executes when the event is broadcast, as follows:

var listenerObject:Object = new Object();
listenerObject.eventName = function(evtObj:Object){
    // your code here
};

If you want to use an existing object, use the same syntax as a new listener object, without creating the new object, as shown here:

existingObject.eventName = function(evtObj:Object){
    // your code here
};

Finally, you call the addEventListener() method from the component instance that broadcasts the event. The addEventListener() method takes two parameters: a string indicating the name of the event and a reference to the listener object.

componentInstance.addEventListener("eventName", listenerObject);

Here is the whole code segment, which you can copy and paste. Be sure to replace any code in italics with actual values; you can use listenerObject and evtObj or any other legal identifiers, but you must change eventName to the name of the event.

var listenerObject:Object = new Object();
listenerObject.eventName = function(evtObj:Object){
    // code placed here executes
    // when the event is triggered
};
componentInstance.addEventListener("eventName", listenerObject);

The following code segment uses the this keyword as the listener object:

function eventName(evtObj:Object){
    // code placed here executes
    // when the event is triggered
}
componentInstance.addEventListener("eventName", this);

You can call addEventListener() from any component instance; it is mixed in to every component from the EventDispatcher class. (A "mix-in" is a class that provides specific features that augment the behavior of another class.) For more information, see EventDispatcher.addEventListener() in the ActionScript 2.0 Components Language Reference.

For information about the events a component broadcasts, see the component's entry in the ActionScript 2.0 Components Language Reference. For example, Button component events are listed in the Button component section (or Help > ActionScript 2.0 Components Language Reference > Button component > Button class > Event summary for the Button class).

To register a listener object in a Flash (FLA) file:

1. In Flash, select File > New and create a new Flash document.
2. Drag a Button component to the Stage from the Components panel.
3. In the Property inspector, enter the instance name myButton.
4. Drag a TextInput component to the Stage from the Components panel.
5. In the Property inspector, enter the instance name myText.
6. Select Frame 1 in the Timeline.
7. Select Window > Actions.
8. In the Actions panel, enter the following code:

   var myButton:mx.controls.Button;
   var myText:mx.controls.TextInput;
   
   function click(evt){
       myText.text = evt.target;
   }
   
   myButton.addEventListener("click", this);
   

   The target property of the event object, evt, is a reference to the instance broadcasting the event. This code displays the value of the target property in the TextInput component.

To register a listener object in a class (AS) file:

1. Open the file TipCalculator.fla from the location specified in Working with Components.
2. Open the file TipCalculator.as from the location specified in Working with Components.
3. In the FLA file, select form1 and view the class name, TipCalculator, in the Property inspector.

   This is the link between the form and the class file. All the code for this application is in the TipCalculator.as file. The form assumes the properties and behaviors defined by the class assigned to it.

4. In the AS file, scroll to line 25, public function onLoad():Void.

   The onLoad() function executes when the form loads into Flash Player. In the body of the function, the subtotal TextInput instance and the three RadioButton instances, percentRadio15, percentRadio18, and percentRadio20, call the addEventListener() method to register a listener with an event.

5. Look at line 27, subtotal.addEventListener("change", this).

   When you call addEventListener(), you must pass it two parameters. The first is a string indicating the name of the event that is broadcast--in this case, "change". The second is a reference to either an object or a function that handles the event. In this case, the parameter is the keyword this, which refers to an instance of the class file (an object). Flash then looks on the object for a function with the name of the event.

6. Look at line 63, public function change(event:Object):Void.

   This is the function that executes when the subtotal TextInput instance changes.

7. Select TipCalculator.fla and select Control > Test Movie to test the file.

Flash CS3