ActionScript 3 Display List Event Flow

Download the Flash CS3/AS3/FP9 Source Files for this post

I've *finally* completed and posted a version of my ActionScript 3 Events workshop to the Rich Media Institute Online. I wrote the first full draft of this course almost a year ago, and I first taught it live in Los Angeles in May -- and now I've finally completed a version for online entitled, Unlocking ActionScript 3 Fluency: Events and the Broadcaster (see below for an extended excerpt of that course).

I gave this name to the course because I believe (and argue in the course) that events really are the glue that bind everything together, and understanding events is vital to achieving fluency in ActionScript 3. Understanding how to reduce the potential for errors in your code makes you a better coder; understanding how to work with and around events makes you a fluent coder.

Stated another way: everything in Flash is an object. There are two ways to make your objects communicate:

1. Direct references: which even your grandmother knows not to use if possible, since direct references create less maintainable, less reusable, and more spaghetti-ish code.
2. Events: which are dispatched and heard, and are like butter to work with

So, since objects need to communicate to do anything cool or complex, and since events are really the only clean way to have objects communicate (until you get into advanced stuff, like frameworks), well it looks like you need to understand events if you want to do anything fun, cool or sexy!

Fortunately, events in AS3 are not that hard to work with -- in fact, they are incredibly consistent and pretty darn easy. They do have some pretty key limitations, but there are several ways around them, and my course teaches a CustomEvent and a CustomEvent Broadcaster as two such solutions.

But before we get that far, there is one very most important aspect of working with events in ActionScript 3, a concept that many users of Flash do not understand when walking into my course. This concept of Display List Event Flow can be stated in two simple bullets.

Events in Flash:

• are objects
• that can travel

Unlike in real life, where an 'event' is likely not tangible (try touching a party), events in Flash are as real and tangible as anything else, such as a MovieClip. Events have properties and methods, and they exist and occupy memory -- just like any other type of object. And these events have a lifespan -- they are born, they travel (or 'flow') and they die.

Because Flash is an inherently visual platform, it is not surprising that the native event flow in Flash is inherently tied to the Display List -- the tree formed by the relationships of the display objects on our stage -- which can change each frame (since the MovieClip that's on my stage on this frame, might not be there on the next frame). To help you visualize what we're talking about when we say 'display list', here is a simple example display list:

Many events in AS3 (especially MouseEvents and KeyboardEvents, as well as any bubbling events of our own that we might dispatch in our movies) travel around the display list, in three phases:

1. the capture phase: the event is heard down from the stage to the 'target' or source of the event
2. the target phase: the event is heard on the target itself
3. the bubbling phase: the event is heard back up the display list, from the target to the stage

So, looking back at our sample display list, let's say the user clicks on sub1a, whose full path is: stage.mc1.mc1_a.sub1a. In that case, the event (in our case, a MouseEvent) would be created and dispatched first on the stage, and then down to the target (or source, in our case, sub1a) of the event, in the capture phase.

The event (again, in our case, a MouseEvent) is heard on the target (again, in our case, sub1a), in the target phase.

And finally, the event will be dispatched up the display list, from the target, to the stage, in the bubbling phase.

So, the full flow -- the complete lifespan of an event in the display list -- looks something like this:

So, to be clear, in this very, very simple example of the user clicking on sub1a, that MouseEvent can be heard in four separate locations, at seven separate occasions (3 in capture phase, 1 in target phase, and three again in the bubbles phase).

Remember! The display list event flow not only tells us which parts of the display list will hear an event, but also which parts CAN NOT hear events (this limitation gets to why it can be so difficult, with the native AS3 event flow, to have different objects hear events from different parts of your movies).

By default, when you write addEventListener in AS3, you will listen for events in the target and bubbles phases. If you use the 'useCapture' property of addEventListener, you can listen for events in the capture phase instead, as in:

addEventListener ( MouseEvent.CLICK , _onClick , true ) ;

Why would you ever want to hear an event in the capture phase? Well, honestly, it's rare, but we had to use it today at work to suppress keyboard input from being heard in parts of our movie in certain specific instances, so there are times when it can come in handy. But it's still useful to know about, because 'capture' makes 'bubbling' make a whole lot more sense!

I've prepared two Flash CS3/AS3/FP9 samples (including source) that hopefully help demonstrate the concept. The first is intended to provide visual indication of the actual event flow, including the phases, and which branches of the display list can hear an event. The second provides a more accurate estimation of the timing of the event flow -- which lasts milliseconds -- by tracing messages to a textarea. I'm embedding the visual one at 50% so you can get a sense of it here.

Visual Display List Event Flow Tracer

Preview from R's AS3 Events Course

Share and enjoy!

-r