Detecting When Mouse Leaves Movie
       by senocular  and kirupa |  11 September 2008

One thing about previous versions of ActionScript was that you could never tell when the user no longer had his or her mouse over the Flash movie. This made it hard for people to know whether or not the user is still interacting with their movie or if they've given up and moved on to something more interesting. This was especially a problem for custom cursors where, if the user moved the cursor off the Flash movie, the custom cursor would still remain in the Flash movie not moving while the real cursor could be seen moving around everywhere else.

ActionScript 3 now allows you to detect when the mouse has left the flash movie using the stage's MOUSE_LEAVE event. To see this in action, hover your mouse over the following Flash movie:

Notice the custom mouse cursor follows your mouse as long as you are within the movie's boundaries. Once your mouse leaves your movie's boundaries, the cursor fades out of view. Pretty cool, ehh?

Download Source File
To see how this was done, download the Flash CS3 source file from the following location:

Download Final Source

Download and extract the above file and open it in Flash CS3. Much of what you see should be pretty straightforward, but let's look at the contents in greater detail.

Examining the File
Our movie is made up of two main things. The first is the cursor movie clip, and the second is the code. Let's look at the easy part - the cursor movie clip:

[ your custom cursor has the instance name cursor ]

Your cursor movie clip is nothing more than a white circle with a ridiculously large stroke. You can look inside the movie clip to see the basic fade out animation, but I won't discuss how that is created or setup in this tutorial. The only thing to note about this movie clip is that its instance name is cursor.

Your cursor movie clip relies on code to tell it to follow your mouse and disappear when the mouse leaves the stage, so let's look at the code.

Below, you will see all of the code that powers this movie:

import flash.events.Event;

import flash.events.MouseEvent;

import flash.ui.Mouse;

 

function Start() {

stage.addEventListener(Event.MOUSE_LEAVE, cursorHide);

stage.addEventListener(MouseEvent.MOUSE_MOVE, cursorFollow);

}

function cursorHide(evt:Event):void {

cursor.gotoAndPlay("fadeOut");

}

function cursorFollow(evt:MouseEvent):void {

if (cursor.currentFrame != 0) {

cursor.gotoAndStop(1);

}

cursor.x = stage.mouseX;

cursor.y = stage.mouseY;

evt.updateAfterEvent();

}

Start();

Let's start at the very top:

function Start() {

stage.addEventListener(Event.MOUSE_LEAVE, cursorHide);

stage.addEventListener(MouseEvent.MOUSE_MOVE, cursorFollow);

}

The Start function is what gets called first when your movie is run. Notice the Start function call at the very bottom of our code. The Start function is responsible for registering two events with their corresponding event handlers:

function Start() {

stage.addEventListener(Event.MOUSE_LEAVE, cursorHide);

stage.addEventListener(MouseEvent.MOUSE_MOVE, cursorFollow);

}

First you setup the MOUSE_LEAVE event on your stage to call cursorHide when your mouse leaves the stage. Next, you setup the MOUSE_MOVE event on your stage to call cursorFollow when your mouse is moved around the stage.

function cursorHide(evt:Event):void {

cursor.gotoAndPlay("fadeOut");

}

The cursorHide function gets called when your MOUSE_LEAVE event is fired, and that event is fired only when your mouse cursor leaves your stage. Any thing you want your movie to to do when the mouse leaves the stage, you add the code for that here.

In this case, when the cursorHide function gets called, I play the small fading transition that starts at the frame labeled fadeOut inside your cursor movie clip:

[ inside the cursor movie clip, you'll find the fade out transition ]

This transition is responsible for fading your cursor out gradually when your mouse cursor leaves the movie's boundaries!

The final function we will look at is cursorFollow.

function cursorFollow(evt:MouseEvent):void {

if (cursor.currentFrame != 0) {

cursor.gotoAndStop(1);

}

cursor.x = stage.mouseX;

cursor.y = stage.mouseY;

evt.updateAfterEvent();

}

This function is tied to your MOUSE_MOVE event, so each time your mouse cursor moves around your movie, this function will get called.

The first thing I do is ensure the the first frame of the cursor movie clip is displayed, for I don't want to display it in its faded out state.

function cursorFollow(evt:MouseEvent):void {

if (cursor.currentFrame != 0) {

cursor.gotoAndStop(1);

}

cursor.x = stage.mouseX;

cursor.y = stage.mouseY;

evt.updateAfterEvent();

}

The exact position of the cursor movie clip is determined by your stage's mouseX and mouseY properties:

function cursorFollow(evt:MouseEvent):void {

if (cursor.currentFrame != 0) {

cursor.gotoAndStop(1);

}

cursor.x = stage.mouseX;

cursor.y = stage.mouseY;

evt.updateAfterEvent();

}

By setting my cursor movie clip's x and y position to the stage's mouseX and mouseY properties, I ensure that the custom cursor follows the mouse around. The final line is the updateAfterEvent call:

function cursorFollow(evt:MouseEvent):void {

if (cursor.currentFrame != 0) {

cursor.gotoAndStop(1);

}

cursor.x = stage.mouseX;

cursor.y = stage.mouseY;

evt.updateAfterEvent();

}

Because we are moving our cursor movie clip each time the MOUSE_MOVE event fires, you will find yourself calling the cursorFollow function more frequently than allowed by your frame rate. This will cause fast and rapid movements to seem like they are lagging. Calling updateAfterEvent on your evt MouseEvent object forces Flash to redraw the stage as quickly as needed independent of the frame rate.

Conclusion
That's all there is to this. The new addition in AS3 has been the MOUSE_LEAVE event attached to your stage. You now have the ability to listen for mouse events on the stage itself, and one thing you can do now that you couldn't before is detect when the mouse leaves the movie and deal with that as you wish.

If you have any questions, feel free to post on the kirupa.com Forums.

Cheers!

	senocular
	kirupa