The Flash Connection Make mine Actionscript 3.0!

I have referred throughout this article to the event object in a generic sense. But actually, the event object we have been using is an instance of the MouseEvent class. The MouseEvent class is a subclass of the Event class. Two properties of the Event class, target and currentTarget, are inherited by the MouseEvent class. However, the MouseEvent class defines a few properties of its own that apply specifically to Mouse events, and these are quite useful, too.

For example, the properties altKey, ctrlKey, and shiftKey are Boolean properties that can tell you if those keyboard keys are currently being held down when the mouse event occurs. To use them, just remember that they are properties of the MouseEvent object that your handler function receives as a parameter. So you use them the same way you used target and currentTarget. Example:

button_mc.addEventListener(MouseEvent.CLICK, clickHandler);
function clickHandler(event:MouseEvent):void {
    if(event.shiftKey == true) {
        event.currentTarget.x += 5;
    }
}

In this scenario, button_mc will move five pixels to the right when it is clicked, but only if the Shift key is also being pressed when the click happens.

Also useful are the localX, localY, stageX, and stageY properties. These properties are Number properties that can tell you the screen coordinates of the mouse pointer's location when the click happened. localX and localY give you the mouse coordinates in relation to the target (in the case of our examples so far, whatever was clicked on). stageX and stageY, meanwhile, give you the mouse coordinates in relation to the stage.

Another useful property of the Event class is type. This property is a String value that can tell you what type of event triggered the listener. This might be useful for combining two or more event handler functions into one. For example, let's consider our sample file as we last left it, and let's combine the two event handler functions into one big one:

menu.addEventListener(MouseEvent.CLICK, clickHandler);
menu.addEventListener(MouseEvent.MOUSE_DOWN, clickHandler);
function clickHandler(event:MouseEvent):void {
	if (event.type == MouseEvent.MOUSE_DOWN) {
		if (event.target == menu) {
			event.target.startDrag();
		}
	} else if (event.type == MouseEvent.CLICK) {
		if (event.target == menu) {
			event.target.stopDrag();
		}
		if (event.target == button1) {
			navigateToURL(new URLRequest("http://www.google.com"), "_blank");
		}
		if (event.target == button2) {
			navigateToURL(new URLRequest("http://www.amazon.com"), "_blank");
		}
	}
}

It's not that this is necessarily any more desirable than the previous version, but it makes a good example of one possible use of the type property. The main thing is that the type property can tell you what kind of event triggered the listener. What you do with that information is up to you.

There are several other properties of the MouseEvent class (some inherited from the Event class) that you can use in the body of your event handler functions. You should consult the Adobe documentation (help files) for the complete list.

Also available are several methods of the MouseEvent class. One particularly useful method is updateAfterEvent, which can cause the screen to be updated when the event happens, when it would normally be updated only at the framerate of the flash movie. You would use methods of the MouseEvent class the same way you use properties. Just use the name of the event parameter, followed by a dot, then the name of the method, followed by the method call operator ():

event.updateAfterEvent();

Two other methods worth mentioning here, inherited from the Event class, are stopPropagation() and stopImmediatePropagation(). stopPropagation() will prevent the event flow from continuing beyond the current "place" in the event flow (remember the demo from several pages back?) after the listeners there are executed. stopImmediatePropagation() also prevents the event flow from continuing beyond the current "place" in the event flow, but also doesn't allow the listeners there to be executed (I know my use of the term "place" in the event flow is unofficial; Adobe in the documentation calls it a "node").

The main point is that all of these properties and methods of the Event and MouseEvent classes can be used by you in the body of your event handler functions. Once again, see the documentation for a complete list.

While we have been primarily focused on the CLICK event, the event flow through the display list also applies to most of the other mouse events, like MOUSE_DOWN, MOUSE_UP, MOUSE_OVER, MOUSE_OUT, MOUSE_MOVE, DOUBLE_CLICK, and MOUSE_WHEEL. All of these events will propagate to display object children when the event listener is added to a display object container.

The one pair of mouse events that don't have a bubbling phase is ROLL_OVER and ROLL_OUT. This is on purpose, to give you an alternative to MOUSE_OVER and MOUSE_OUT. You would use ROLL_OVER and ROLL_OUT instead when you want to program a display object container for mouse rollovers, but don't want the rollout to be triggered by the children. Rather, you want to detect only when a rollout happens for the whole container.

I'm sure I haven't covered everything to do with the MouseEvent class, and you can check out whatever I've missed on your own. My main purpose with this article has been to help you understand the Actionscript 3.0 event flow. The MouseEvent.CLICK event served a good purpose as an example of one of the events that flows through the display list. By all means, you should explore and experiment with the other events on your own. As always, I hope I've sparked your imagination and insipired you to create your own flash applications. Send me a link to yours, drop me a line, leave me a comment. Thanks!

Happy coding!

Jody Hall