Table of Contents

listener.onMouseMove()

Description

The onMouseMove( ) event lets us detect changes in the mouse pointer's position. Whenever the mouse is in motion, onMouseMove( ) events are issued repeatedly, as fast as the processor can generate new events. Each time onMouseMove( ) executes, we know the mouse pointer has changed position. We can check that position relative to any movie clip by querying the clip's _xmouse and _ymouse properties. To check the position of the mouse pointer relative to the main Stage, use _root._xmouse and _root._ymouse.

To respond to an onMouseMove( ) event, we must assign a callback function to the onMouseMove property of some object, such as listener, and then add listener as a listener using Mouse.addListener( ), as follows:

// Create a generic object (although it can be any type of object)
mouseListener = new Object();
   
// Assign a callback function to the object's onMouseMove property
mouseListener.onMouseMove = function () {
  trace("The mouse was moved!");
}
   
// Register the listener with the Mouse object
Mouse.addListener(mouseListener);

Any number of listener objects of any class can respond to the onMouseMove( ) event.

The onMouseMove( ) event is useful for code that wakes up idle applications, displays mouse trails, or creates custom pointers. However, for visual applications in Flash 6, the MovieClip.onMouseMove( ) handler is preferred over the Mouse.onMouseMove( ) listener event because the former allows for between-frame screen refreshes.

The onMouseMove( ) event executes immediately when the mouse moves, independently of the code on a movie's timeline(s). However, visual changes to the movie made by the listener are not rendered until the next frame refresh, which is determined by the frame rate of the movie. Unfortunately, in Flash 6, updateAfterEvent( ) cannot be used to force a screen refresh from within an onMouseMove( ) listener; updateAfterEvent( ) has an effect only when invoked either from a movie clip mouse or key event or a setInterval( ) callback. Hence, in Flash 6, it's often appropriate to create a movie clip simply to implement onMouseMove( ) with a screen refresh. For example:

// Create the movie clip
this.createEmptyMovieClip("mouseListener_mc", 1);
// Assign a callback function to the clip's onMouseMove handler
mouseListener_mc.onMouseMove = function () {
  // Respond to mouse movement (details omitted)...then refresh screen
  updateAfterEvent();
}

See the Example under Mouse.hide( ) for custom pointer code. Mouse trailer code is available at the online Code Depot, in varying degrees of complexity.

See Also

Mouse.addListener( ), Mouse.onMouseDown( ), Mouse.onMouseUp( ), MovieClip.onMouseMove( )

Table of Contents