This tutorial builds on the MX Events Tutorial and the Introduction to FLEM. In those two articles, we started to explore a newer, more object-oriented event model for ActionScript. We learned about event handlers, which are the cornerstone of the MX event model. The other main feature of the new event model is listeners. Listeners utilize event handlers, but go beyond them, allowing for more powerful programming structures.

To understand listeners, you first need to understand the difference between time-based and event-based programming. Time-based programming is like buying a magazine from the store every month, whereas event-based is like having it delivered to your door. Let's explore this analogy further.

Time-Based Programming

In time-based programming, an object has to keep checking other objects for changes that may have occurred. This is like buying your favorite magazine from the store every month. You have to check periodically to see if the new issue has arrived. If you want your shiny new mag as soon as it's available, you'll have to check quite often at the end of the month.

In object-oriented terms, imagine that you are represented by a movie clip named me. This movie clip has to check the month property of the magazine object. The magazine belongs to the newsstand, which belongs to the store. Suppose the magazine is wiredMag, and April is the next issue. The code to check the newsstand would look something like this:

// code inside the me movie clip
// check the newsstand for the April issue
if (store.newsstand.wired.month == 4) {
    this.buy (store.newsstand.wiredMag);
    this.read (store.newsstand.wiredMag);
}

• The me object finds the magazine by navigating the hierarchy of store -> newsstand -> magazine.
• The month property of magazine is compared with the number of the new month (4 for April).
• If the magazine is the new April issue, the person calls its own actions, this.buy() and this.read(), to grab the magazine.

This code covers one check of the newsstand. How would we do this repeatedly? We can easily set up a frame loop with the onEnterFrame handler (see the Events in MX tutorial), with this code:

// code inside the me movie clip
// check the newsstand for the April issue
// once per frame
this.onEnterFrame = function () {
    if (store.newsstand.wired.month == 4) {
        this.buy (store.newsstand.wiredMag);
        this.read (store.newsstand.wiredMag);
        delete this.onEnterFrame;
    }
};

I encased the code in a function and assigned it to this.onEnterFrame, causing it to be executed once per frame. I also added one other line of code:

delete this.onEnterFrame;

This stops the frame loop right after buying the magazine. Since you have the new issue, you don't need to keep checking for it. But what about the month after that? It won't be long before you'll have to start another loop, to check for the new issue again.

Surely there's a more efficient way to do this. Checking the newsstand time and again would get tiresome after a while. How many months would it take before you decided to just subscribe to the magazine? Subscriptions are at the heart of event-based programming and listeners.

Event-Based Programming

When you move from time-based to event-based programming, there is a shifting of responsibility. In event-based programming, it's no longer your job to keep checking for new events. Instead, you tell another object to subscribe you to its events. This object is the event source, and you are a listener. You listen for events from the event source.

In our example, the magazine company is the event source--let's call it wiredCo. When you buy a wiredMag subscription, you become a listener for events from wiredCo. You need to give it your address so it knows where to contact you when an event occurs.

The code to subscribe to wiredCo events looks like this:

// code inside the me movie clip
// subscribe to wiredCo events
wiredCo.addListener (this);

This short piece of code has the following results:

• The wiredCo event source object is contacted, and asked to add you as a listener, using its addListener() method.
• Your address is sent to wiredCo by passing the reference this.
• The wiredCo object stores your address in its internal list of subscribers.
• When an event occurs, wiredCo will look up the addresses of its subscribers and sends each one a message. This called event broadcasting.

Now that you've subscribed to an event source as a listener, you need to decide how you're going to handle incoming events. The event that wiredCo uses happens to be called "onNewMag". Thus, you need to set up a method with the same name. This onNewMag() function is called an event handler. We define it with the following code:

// code inside the me movie clip
// define an event handler
this.onNewMag = function (mag) {
    this.read (mag);
};

• The wiredCo object will invoke the onNewMag() method when that event occurs.
• It passed one argument, mag, an object representing the magazine.
• mag is passed to the this.read() method.

That's it--now you can sit back and let the magazines come to you automatically. This is quite a nice arrangement. Once you've done these two things--

1. define event handler(s)
2. subscribe as a listener

--you don't have to do any more work. The system is in place, and the event source is in control. (Note: it's a good idea to define the event handlers first, before subscribing as a listener. You want to be ready in case the event comes in right away.)

Listening to MX Objects

Flash MX has several built-in objects that can act as event sources: Key, Mouse, Stage, Selection, Textfield, and FStyleFormat. Each has an addListener() method, which subscribes a listener for events from that object. The following table summarizes the events for each of these:

 

Key.addListener (obj)	subscribes obj to onKeyDown/onKeyUp events
Mouse.addListener (obj)	subscribes obj to onMouseDown/ onMouseMove/onMouseUp events
Selection.addListener (obj)	subscribes obj to the onSetFocus event
Stage.addListener (obj)	subscribes obj to the onResize event
myTextField.addListener (obj)	subscribes obj to onChanged/onScroller events from myTextField
myStyleFormat.addListener (obj)	registers obj (a component) to myStyleFormat

In MX, movie clips are automatically subscribed to Key and Mouse events. For example, a movie clip's onMouseDown() event handler is automatically called when the mouse is pressed. However, this isn't the case for custom code objects.

You can make an object listen to the mouse by using Mouse.addListener(). Here is a code example you can try:

// make a code object listen for Mouse events
obj = new Object();
obj.onMouseDown = function () { trace ("obj received mouseDown"); };
obj.onMouseUp = function () { trace ("obj received mouseUp"); };
obj.onMouseMove = function () { trace ("obj received mouseMove"); };
Mouse.addListener (obj);

Paste this code into a new movie and watch the results in the output window.

Example: Listening to a TextField

Text fields in MX are instances of the TextField class. They are much more powerful than in Flash 5. Among other things, a TextField can broadcast events to listeners. The movie below gives a simple demonstration. The triangle movie clip is affected when the text field is changed or scrolled:

The text field is on the main timeline, and has an instance name of infoText. The triangle movie clip's response to infoText is produced by these few lines of code:

// code inside triangle movie clip
this.onChanged = function () {
    this._yscale += 10;
};

this.onScroller = function () {
    this._rotation += 10;
};

_parent.infoText.addListener (this);

Here again, we see the two steps for subscribing to events:

1. define event handler(s)
2. subscribe as a listener

In this case, there are two event handlers, because there are two events coming from the text field: onChanged and onScroller. Looking first at the onChanged event handler:

this.onChanged = function () {
    this._yscale += 10;
};

With this setup, the onChanged event causes the movie clip to stretch vertically--whenever you type in the text field.

this.onScroller = function () {
    this._rotation += 10;
};

The onScroller event handler is called when the text field is scrolled. It causes the triangle to rotate by 10 degrees.

With the event handlers in place, the last step is to subscribe the movie clip to the text field's events:

_parent.infoText.addListener (this);

The infoText object adds the movie clip as a listener, and we're all set.

One-To-Many Broadcasting

The preceding example is purposefully quite simple: one object listens to one other object. However, event-based programming shows its true prowess when you have multiple objects listening to each other. An object can listen to more than one event source. Conversely, an event source can broadcast to many listeners.

Here is a modified example, with multiple triangle listeners:

It takes a mere ten seconds to turn the first example into this one. The triangle and its code are nicely self-contained, so you can just throw more copies onto the stage. Each instance will automatically register itself with infoText as a listener. As a result, when the onChanged and onScroller events occur, the text field notifies all of the triangles.

This is an example of one-to-many broadcasting with listeners. The core concept is not really that complicated, but it is extremely powerful. Event-based programming has revolutionized the way I program in ActionScript. I now think much more in terms of events, and responding to them. Increasingly, I'm making my own event sources, using custom classes. But that is a step beyond this tutorial.

For now, get familiar with the different event sources that are supplied in Flash MX, listed in the earlier table. In a subsequent tutorial, we'll look at how you can create your own event sources, which can add listeners and broadcast messages.