UIElement.CaptureMouse Method

Syntax

'Declaration
Public Function CaptureMouse As Boolean

public bool CaptureMouse()

Remarks

When an object has captured the mouse, that object receives mouse input whether or not the mouse pointer is within its bounding area. The mouse is typically only captured during simulated drag operations. To release mouse capture, call the ReleaseMouseCapture method on the object that holds capture.

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

• The mouse pointer 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 at a native or scripting level (this is possible if the mouse pointer exited into the non-Silverlight area of the browser and was captured by scripting).

• The left mouse button is in a pressed (down) state.

If one of these conditions is false, the CaptureMouse return value is false.

If an initial CaptureMouse call returned true and successfully captured the mouse, subsequent calls to CaptureMouse on the same object will still return true unless conditions have changed; CaptureMouse returns nothing different if that object already had capture. Depending on your application's requirements, you might find it useful to set a variable that either tracks whether any object holds capture, or provides a reference to the specific object that currently has capture. If you use this technique, set the variable on each CaptureMouse call and clear it on each ReleaseMouseCapture call.

Only a UIElement derived object can capture the mouse. Notable cases of other objects that have a visual character but cannot capture the mouse are Run (only the parent TextBlock can capture) and geometries (only the parent Path can capture).

The UIElement that calls CaptureMouse must be hit test visible in the UI. This means that IsHitTestVisible cannot be false. For more information, see Hit Testing and Input Events.

Version Information

Silverlight

Supported in: 5, 4, 3

Silverlight for Windows Phone

Supported in: Windows Phone OS 7.1, Windows Phone OS 7.0

Platforms

For a list of the operating systems and browsers that are supported by Silverlight, see Supported Operating Systems and Browsers.

See Also

Reference

Other Resources