event_flow_starter_file.fla

To discuss the Event Flow through a display list, we first need a display list. Download the starter fla file linked above, as it contains a very simple display list with a menu and a couple of MovieClip buttons. We are going to be considering here only those events that flow through a display list, and of those, only the events that have a bubbling phase (don't worry if that word is unfamiliar to you; we'll get to explaining the phases later). In fact, we're going to get even more specific than that and only consider one event, the MouseEvent.CLICK event. My feeling is that the best way to get a clear picture of the event flow is to focus on one type of event for now. The CLICK event makes a nice example to look at, and the other events are similar.

Here is what the starter fla file looks like when you run it:


And here is the code that puts the various objects out there on the display list:
var menu = new Menu();
menu.x = 84;
menu.y = 89;
addChild(menu);

var button1 = new ButtonOne();
button1.x = 117;
button1.y = 71;
menu.addChild(button1);

var button2 = new ButtonTwo();
button2.x = 117;
button2.y = 131;
menu.addChild(button2);

The line addChild(menu) adds the menu to the display list. The menu is being added to the main timeline (root), and not to the stage. You may not have even known there was a distinction. Notice we didn't say stage.addChild(menu). What's the difference? Well, when you create a new fla file, before you even add anything of your own, you automatically get a stage instance to which the root has already been added. It's as though a line of code something like this:
stage.addChild(root);

...has already been executed for you. The stage and the root provide a foundation on which to build all the rest of your display list. When you add things to the root with addChild or this.addChild (those are equivalent), they automatically get displayed, because the root has already been added to the stage previously. Here is a diagram illustrating the structure of our display list once the above lines of code have executed:

If you have ever added a child to an object's display list, and it didn't show up on the screen when you ran the file, chances are the object you were adding it to didn't have a connection to the stage. It might be helpful to think of the stage object as being analagous to a main electrical power source. You might have a maze of electrical cords that are all plugged into each other, but if they aren't also connected to the main power source at the other end, you don't have power. Similarly, you must ultimately have a connection to the stage for your display object to be displayed.

Now that we have a simple display list, let's discuss it a bit. How do events "flow" through this display list anyway? The answer is that when you add a display object to a display object container using addChild(), the container gets a reference to its new child, and the child gets a reference to its new parent. This creates a chain of objects, each one knowing its parent and each one (if it's a container) having a list of its children. The event flow travels along this chain beginning at the stage. The event object is passed along from object to object thanks to this chain of references.

The following event flow demo swf is intended to show you how this event flow takes place. Try clicking on the various objects in the display list--the buttons, the menu, and even the stage--and watch the event object travel along the event flow. Note how many places it "visits" when you click on the different things:

The Event Flow Demo Swf:

Note: Don't just pass this by! You should click on this demo several times. I know this is a simple display list hierarchy, but I want you to get a good mental picture of the way events flow through it. I will refer back to this demo swf several more times during the course of this article.


There are a lot of things to note here: First, it's important to realize that this event flow takes place whether there are any listeners defined or not (as noted in the demo). Secondly, unlike what you see in this demo, the "real" event object travels through the display list at a much more blinding speed. Thirdly, it should be noted that there are different kinds of event objects, and they carry along with them a lot of valuable information. This event object for a mouse click would be an instance of the MouseEvent class (but for simplicity's sake in the demo I've just labelled it "event object."), and it would carry along infomation specific to mouse events. Later we'll see how to make practical use of this information.

Finally, notice that if you click on either of the buttons, the event object "visits" five places. If you click on the menu, it visits three. If you click on the stage, it only visits one. At each place, it checks to see if there are any event listeners defined there, and if so, their code would be executed.

So, here's what I want you take away from this demo: A mental picture of the event object flowing through a display list and "visiting" the various "places" along the way.  On the next page, we'll examine how to define listeners for each of those "places." Make sure that you've downloaded the starter fla file from the top of this page, if you want to follow along.