發行項
06/13/2011

MouseEnter

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

Occurs when the mouse enters the bounding area of an object.

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

[token = ]object.AddEventListener("MouseEnter", 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

MouseEnter

Remarks

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

The MouseEnter event is only raised in response to the mouse moving into the object's bounding area, which would also raise MouseMove. In this case, the MouseEnter event precedes the MouseMove event for the object. The MouseEnter event is not raised if the mouse did not actually move. For instance, MouseEnter is not raised if the mouse pointer remains stationary, and an object with a MouseEnter handler has its position animated or otherwise adjusted to move under the mouse pointer.

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("MouseEnter", "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.

You can define multiple MouseEnter events for objects in XAML content. However, if a child object and its parent object both define a MouseEnter event, the parent object's MouseEnter event occurs before the child object's MouseEnter event. This is not a case of a bubbling event; it indicates only that the mouse has entered both objects, potentially at different times depending on the object layout.

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

Example

The following XAML example shows MouseEnter events defined for a Canvas and a TextBlock object. In this case, the Canvas object's event handler function is invoked before the TextBlock object's event handler function.

<!-- Canvas MouseEnter event fires first, then TextBlock MouseEnter event -->
<Canvas
  xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation"
  xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml"
  MouseEnter="rootCanvasMouseEnter">
  
  <TextBlock
    x:Name="myTextBlock" 
    MouseEnter="textBlockMouseEnter"
    Text="Test order of MouseEnter events" />

</Canvas>

The following JavaScript example shows how to implement a MouseEnter event handler function.

function rootCanvasMouseEnter(sender, mouseEventArgs)
{   
    // Concatenate the values of the MouseEventArgs parameter.
    var msg  = "x = " + mouseEventArgs.getPosition(null).x;
        msg += "  y = " + mouseEventArgs.getPosition(null).y;
        msg += "  shift = " + mouseEventArgs.shift;
        msg += "  ctrl = " + mouseEventArgs.ctrl;

    // Display the values of the MouseEventArgs parameter.
    sender.findName("myTextBlock").text = msg;
}