Article
06/13/2011

CaptureMouse

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

Enables mouse capture for the object.

retval = object.CaptureMouse()

Return Value

Type: Boolean

true if the object has enabled mouse capture; otherwise, false.

Managed Equivalent

CaptureMouse

Remarks

When an object has captured the mouse, it receives mouse input whether or not the cursor is in its borders. The mouse is typically captured only during drag operations. To disable mouse capture for an object, use the ReleaseMouseCapture method.

The mouse can be captured when all of the following conditions are true:

The mouse is over the Silverlight plug-in content area.
No other Silverlight object has captured the mouse.
No other non-Silverlight object has captured the mouse.
The left mouse button is in the pressed state.

Only a UIElement type can capture the mouse (for a list of applicable objects, see the Applies To section later in this topic). Notable cases of other objects that have a visual character but cannot capture the mouse are Run (only the parent TextBlock object can capture the mouse) and geometries (only the parent Path object can capture the mouse).

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.

Example

The following example demonstrates how mouse capture works. In this example, two Rectangle objects share the same MouseMove event-handler function.

<Canvas 
  xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation"  
  xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml" 
  Height="180" Width="300" 
  Background="PowderBlue">
  
  <Rectangle 
    x:Name="Green"
    MouseMove="onMouseMove"
    MouseLeftButtonDown="onLeftButtonDown"
    MouseLeftButtonUp="onLeftButtonUp"
    Width="100" Height="100" 
    Fill="Green" />
  
  <!-- The MouseMove event-handler function is shared with the first rectangle. -->
  <Rectangle 
    x:Name="Red"    
    MouseMove="onMouseMove"    
    Canvas.Left="120" 
    Width="100" Height="100" 
    Fill="Maroon" />
  
  <TextBlock 
    x:Name="statusTextBlock" 
    FontSize="18" 
    Canvas.Top="120" />

</Canvas>

The following JavaScript example defines the corresponding event-handler functions for the previous XAML content example. Notice that the green Rectangle object captures all Silverlight-based application mouse input from the time the left mouse button is pressed until the left mouse button is released.

// Display the current mouse position for the Rectangle object.
function onMouseMove(sender, mouseEventArgs)
{
    var msg = "x:y = " + mouseEventArgs.getPosition(null).x + ", " + mouseEventArgs.getPosition(null).y;
    sender.findName("statusTextBlock").Text = sender.Name + ": " + msg;
}

// Enable mouse capture when the mouse button is pressed over the green Rectangle object.
function onLeftButtonDown(greenRect, mouseEventArgs) 
{
    greenRect.captureMouse();
}

// Disable mouse capture when the mouse button is released over the green Rectangle object.
function onLeftButtonUp(greenRect, mouseEventArgs) 
{
    greenRect.releaseMouseCapture();
}

When the Silverlight-based application is displayed and you move the mouse over the rectangles, each rectangle displays its mouse position by using the shared onMouseMove event-handler function. For example, when the mouse is over the red rectangle, the display will show a value similar to "Red: x:y = 171, 55".

Each rectangle receives mouse input

Red: x:y = 171, 55

When you press and hold the mouse button over the green rectangle, the green rectangle receives all mouse input events when you move the mouse over any part of the Silverlight-based application. For example, when the green rectangle enables mouse capture and you move the mouse over the red rectangle, the display will show a value similar to "Green: x:y = 140, 76". This is because all events are being redirected to the green rectangle, even though the mouse is outside the green rectangle's bounding area.

Input goes to the element that enabled the capture

Green: x:y = 140, 76