CaptureMouse Method

Enables mouse capture for the object.

Return Value

Boolean

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

Remarks

When an object has captured the mouse, it receives mouse input whether or not the cursor is within its borders. The mouse is typically only captured during drag operations. To disable mouse capture for an object, use the ReleaseMouseCapture method. For more information on capturing the mouse, see Implementing Drag and Drop.

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 must be in a depressed state.

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

Examples

To understand how mouse capture works, consider the following XAML example in which two Rectangle objects share the same MouseMove event handler function:

<Canvas 
  xmlns="https://schemas.microsoft.com/client/2007"  
  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 corresponding event handler functions for the previous XAML content example are defined in the following JavaScript example. Notice that the green Rectangle object captures all Silverlight application mouse input from the time the left mouse button is depressed 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 is depressed over the green Rectangle object.
function onLeftButtonDown(greenRect, mouseEventArgs) 
{
    greenRect.captureMouse();
}
// Disable mouse capture when the mouse is released over the green Rectangle object.
function onLeftButtonUp(greenRect, mouseEventArgs) 
{
    greenRect.releaseMouseCapture();
}

When the Silverlight is displayed and the mouse moves 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 status displays "Red: x:y = 171, 55".

Each rectangle receives mouse input

When the mouse is depressed over the green rectangle and held down, moving the mouse over any part of the Silverlight application results in the green rectangle receiving all mouse input events. For example, when the green rectangle enables mouse capture and the mouse moves over the red rectangle, "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 element with capture

Applies To

Canvas, Ellipse, Glyphs, Image, InkPresenter, Line, MediaElement, Path, Polygon, Polyline, Rectangle, TextBlock

See Also

Silverlight Events
Silverlight Mouse Support
MouseLeftButtonDown
MouseLeftButtonUp
MouseMove
ReleaseMouseCapture