Recipe 12.10 Listening for Events

12.10.1 Problem

You want to perform an action in response to an event, such as when the Stage is resized, a text field's contents are scrolled, the mouse button is clicked, or a key is pressed.

12.10.2 Solution

Create a listener object that defines an appropriate listener event handler and add it as a listener using addListener( ).

12.10.3 Discussion

ActionScript's listener events allow one or more objects to respond to events that occur for other objects. A listener object (an object that has been added as a listener) is notified when one of the supported listener events occurs. For example, the built-in Key, Mouse, Selection, and Stage objects generate one or more listener events, as do instances of the TextField class, as shown in Table 12-1.

Table 12-1. Listener events for built-in objects and instances

Object	Built-in listener events
Key object	onKeyDown onKeyUp
Mouse object	onMouseDown onMouseMove onMouseUp
Selection object	onSetFocus
Stage object	onResize
TextField instance	onChanged onScroller

A listener object can be any kind of object, such as a text field, movie clip, or custom object. The listener object must define a listener event handler to respond to the event of interest, and it must be added as a listener using addListener( ). For example, to respond to text-scrolling events, you can create an object that defines an onScroller( ) method and then register the object to the text field of interest using the addListener( ) method. Note that the addListener( ) method is called from the text field (or other object from Table 12-1) that is generating the listener events. The addListener( ) method accepts a parameter that is a reference to the listener object (in this case, the object that defines an onScroller( ) listener event handler).

You can register multiple listeners to a single object using separate calls to addListener( ). For example, the following code adds two objects as listeners. The first listener object is a generic instance of the Object class that responds to any changes in the text field named myTextField. The second listener object is a movie clip named myMovieClip. It alters its own x coordinate in response to scroll events for myTextField.

// Create a new object and define an onChanged(  ) listener event handler.
myListener = new Object(  );
myListener.onChanged = function (changedTextField) {
  // Actions go here.
  trace("The text field changed.");
};

// Define an onScroller(  ) listener event handler for an existing movie clip.
myMovieClip.onScroller = function (scrolledTextField) {
  this._x = scrolledTextField.scroll * 10;
};

// Register the custom object and movie clip as listeners for the text field.
myTextField.addListener(myListener);
myTextField.addListener(myMovieClip);

When a listener object is added as a listener, it is eligible to receive all the listener events that the listened-to object generates. For example, an object registered as a listener using Mouse.addListener( ) can respond to onMouseDown, onMouseMove, and onMouseUp events by defining corresponding handlers for the events of interest. In the preceding example, note that both myListener and myMovieClip are eligible to receive onChanged and onScroller events from the text field. However, myListener implements an onChanged( ) event handler only, so it ignores onScroller events. Conversely, myMovieClip implements an onScroller( ) event handler but ignores onChanged events.

Furthermore, note that the onChanged( ) and onScroller( ) listener event handlers receive a parameter indicating which text field generated the event. This is handy when the listener object wants to access a property of the text field (for example, our movie clip listener sets its x location based on the text field's scroll property). It also allows a listener object to distinguish between multiple text fields, if it is receiving listener events from more than one.

Listener events are powerful because they allow you to define actions that should occur on multiple objects when another object is changed in some way. Likewise, listener events allow a single object to respond to changes that occur on multiple objects.

You can remove a listener by invoking the removeListener( ) method on the object that generates the events, passing it a reference to the listener object to remove. For example:

myTextField.removeListener(myListener);

All objects listed in Table 12-1 support both the addListener( ) and removeListener( ) methods.

12.10.4 See Also

Recipe 8.15, Recipe 8.27, and Recipe 12.11