Using 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.

The following ActionScript classes can broadcast events: "Key class", "Mouse class", "MovieClipLoader class", "Selection class", "Stage class", and "TextField class". To see which listeners are available for a class, see each class entry.

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.eventName = function(){
   // 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 it the name of the listener object.

To unregister a listener object from receiving events, you call the removeListener() method of the broadcaster object, passing it the name of the listener object.

broadcasterObject.removeListener(listenerObject);

Event listener example

The following example shows how to use the onSetFocus event listener in the Selection class to create a simple focus manager for a group of input text fields. In this case, the border of the text field that receives keyboard focus is enabled (appears), and the border of the text field that does not have focus is disabled.

To create a simple focus manager with event listeners:

Using the Text tool, create a text field on the Stage.
Select the text field and, in the Property inspector, select Input from the Text Type pop-up menu, and select the Show Border Around Text option.
Create another input text field below the first one.
Make sure the Show Border Around Text option is not selected for this text field. You can continue to create input text fields.
Select Frame 1 in the Timeline and open the Actions panel (Window > Development Panels > Actions).
To create an object that listens for focus notification from the Selection class, enter the following code in the Actions panel:
```
// Creates listener object, focusListener
var focusListener:Object = new Object();
// Defines function for listener object
focusListener.onSetFocus = function(oldFocus_txt:TextField, 
newFocus_txt:TextField) {
	oldFocus_txt.border = false;
	newFocus_txt.border = true;
}
```
This code creates a new (generic) ActionScript object named focusListener. This object defines an onSetFocus property for itself and assigns a function to the property. The function takes two parameters: a reference to the text field that does not have focus and one to the text field that has focus. The function sets the border property of the text field that does not have focus to false, and sets the border property of the text field that has focus to true.
To register the focusListener object to receive events from the Selection object, add the following code to the Actions panel:
```
// Registers focusListener with broadcaster
Selection.addListener(focusListener);
```
Test the application (Control > Test Movie), click in the first text field, and press the Tab key to switch focus between fields.

Comments

mousepoint said on Mar 10, 2005 at 3:54 PM :

Generally, when defining an event handler function, how many arguments
can the handler take? How does the event broadcaster know what arguments
to supply?

sebasporto said on Apr 20, 2005 at 10:58 PM :

Here a simple event broadcaster script that can be used with anything not just components

//in _root
mx.events.EventDispatcher.initialize(this);

var eventObj:Object={target:this,type:"sayHello"}
dispatchEvent(eventObj);

//inside the movieclip that will listen:
sayHello=function(){
trace("hello");
}
__root.addEventListener("sayHello",this);

RSS feed | Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/flash/mx2004/main_7_2/00000945.html