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, Mouse, MovieClipLoader, Selection, Stage, and TextField. To see which listeners are available for a class, see each class entry in the ActionScript 2.0 Language Reference.

For a sample source file, stagesize.fla, that demonstrates how the Stage.scaleMode property affects the values of Stage.width and Stage.height when the browser window is resized, see the Flash Samples page at www.adobe.com/go/learn_fl_samples. Download and decompress the Samples zip file and navigate to the ActionScript2.0/StageSize folder to access the sample.

Event listener model

The event model for event listeners is similar to the model for event handlers (see About ActionScript and events), with two main differences:

var listenerObject:Object = new Object();
listenerObject.eventName = function(eventObj:Object) {
    // 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 removeListener() method of the broadcaster object, passing it the name of the event to remove, and the listener object.

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 then in the Property inspector, select Input Text from the Text Type pop-up menu and click the Show Border Around Text button.
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 > 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 an object named focusListener that defines an onSetFocus property 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.