아티클
06/13/2011

MouseMove

Microsoft Silverlight will reach end of support after October 2021. Learn more.

Occurs when the coordinate position of the mouse changes.

<object MouseMove="eventhandlerFunction" .../>

[token = ]object.AddEventListener("MouseMove", eventhandlerFunction)

Arguments

AddEventListener Parameters

token

integer

A token that is returned from the function, which you can optionally retain as a variable. If you intend to call RemoveEventListener to remove the handler, you will need this token.

eventhandlerFunction

object

The name of your event handler function as it is defined in script. When used as an AddEventListener parameter, quotation marks around the function name are not required. (See the "Remarks" section.)

Event Handler Parameters

sender

object

The object that invoked the event.

mouseEventArgs

object

MouseEventArgs

mouseEventArgs.GetPosition(element).X identifies the x-coordinate position of the mouse.

mouseEventArgs.GetPosition(element).Y identifies the y-coordinate position of the mouse.

mouseEventArgs.Shift determines whether the SHIFT key is down.

mouseEventArgs.Ctrl determines whether the CTRL key is down.

mouseEventArgs.Source: Reports the object that raised the event. (Silverlight 2)

Managed Equivalent

MouseMove

Remarks

Be careful when you write code for a MouseMove handler. The MouseMove event will frequently occur while the user is interacting with the application or with the specific object area that has the handler. Any computationally or graphically intensive code in a MouseMove handler can potentially introduce a noticeable lag in how the mouse pointer draws and how the application generally behaves.

The MouseMove event can be defined for any UIElement-derived class, such as Canvas, TextBlock, or Rectangle.

The MouseMove event is typically raised in response to the mouse pointer moving across the object's bounding area. If the mouse pointer enters the object's bounding area, the MouseEnter event precedes the MouseMove event for the object.

The MouseMove event is a bubbling event. This means that if multiple MouseMove events are defined for a tree of elements, the event is received by each object in the object hierarchy, starting with the object that directly receives the event, and then bubbling to each successive parent element. The bubbling metaphor indicates that the event starts at the bottom and works its way up the object tree. For a bubbling event, the sender parameter identifies the object where the event is handled, not necessarily the object that actually received the input condition that initiated the event.

For more information on basic concepts, see Mouse Support. Note that the Mouse Support topic is written primarily for users of the managed API, and may not have code examples or specific information that address the JavaScript API scenarios.

You can also add handlers in script by using a quoted string for the event handler name, as follows:

object.AddEventListener("MouseMove", "eventhandlerFunction")

This syntax also returns a token. However, the token is not an absolute requirement for removing the handler in cases where the handler was added by using a quoted string. For details, see RemoveEventListener.

Example

The following XAML example illustrates event bubbling. It shows MouseMove events defined for a Canvas and two Rectangle objects. In this case, if you move the mouse pointer over either Rectangle object, it receives the MouseMove event. The event then bubbles up to the parent Canvas.

<!-- The Rectangle MouseMove events occur first, then the Canvas MouseMove event. -->
<Canvas
  xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation"
  xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml"
  Loaded="onLoaded"
  MouseMove="rootCanvasMouseMove">

  <Rectangle
    MouseMove="rect1MouseMove"
    Width="100" Height="100"
    Fill="PowderBlue" />

  <Rectangle
    MouseMove="rect2MouseMove"
    Canvas.Top="50" Canvas.Left="50"
    Width="100" Height="100"
    Fill="Gold" Opacity="0.5" />

  <TextBlock
    x:Name="statusTextBlock"
    Canvas.Top="180" />

</Canvas>

The following JavaScript example shows how to implement the MouseMove event handler functions for the corresponding XAML content in the previous example.

var statusTextBlock;

function onLoaded(sender, eventArgs)
{
    statusTextBlock = sender.findName("statusTextBlock");
}

function rootCanvasMouseMove(sender, mouseEventArgs)
{
    var msg = "x:y = " + mouseEventArgs.getPosition(null).x + ", " + mouseEventArgs.getPosition(null).y;
    // Uncomment the next line to show MouseMove event bubbling.
    // statusTextBlock.text = "rootCanvas: " + msg;
}

function rect1MouseMove(sender, mouseEventArgs)
{
    var msg = "x:y = " + mouseEventArgs.getPosition(null).x + ", " + mouseEventArgs.getPosition(null).y;
    statusTextBlock.text = "rect1: " + msg;
}

function rect2MouseMove(sender, mouseEventArgs)
{
    var msg = "x:y = " + mouseEventArgs.getPosition(null).x + ", " + mouseEventArgs.getPosition(null).y;
    statusTextBlock.text = "rect2: " + msg;
}

The following illustration shows the displayed XAML content.

Example content

Screenshot of sample.

When the mouse pointer moves over the Rectangle objects, the event handlers display the x:y coordinate position of the mouse. Notice that when the mouse is over the overlapping area of the Rectangle objects, the topmost object blocks the MouseMove events from the obscured object, because events do not bubble to siblings, only to ancestors. If you uncommented the line in the rootCanvasMouseMove event handler function in the JavaScript code, the function would correctly display the position of the mouse for both of its child objects.

In this case, where the Canvas object has a Height or Width property set to 0 and a Background property set to null, the MouseMove event is generated only for the child objects. This is because the Canvas object has no visibility as far as MouseMove events are concerned.

The mouse position reported in the mouseEventArgs parameter value may not be exactly on the boundary of the object because of the coalescing of mouse movements.