What does it mean to "Capture the mouse" in WPF?

Question

On System.Windows.UIElement there is a CaptureMouse() and a paired ReleaseMouseCapture() method. In this WPF DragDrop sample they call CaptureMouse on MouseDown and release it on MouseUp. The documentation in MSDN is about as useless as it comes - "CaptureMouse -> Captures the mouse."

In my head before trying it I assumed that it somehow locked the mouse inside the UIElement bounds, but that's clearly not the case when I try it. From experimenting, it seems to have something to do with responding to events when the mouse is outside of the UIElement, but not wanting to be a cargo cult programmer I don't want to just use it because the example does, I'd like an authoritative description of what it means.

Answer 1

From Capture and Uncapture the Mouse on MSDN:

When an object captures the mouse, all mouse related events are treated as if the object with mouse capture perform the event, even if the mouse pointer is over another object.

Capturing the mouse is useful for dragging because only the capturing control receives the mouse events until released. All the dragging code can exist in the one control, rather than being spread over multiple controls.

Answer 2

The Silverlight 2 documentation for it has a more verbose description, I don't know why it isn't a part of the 3.5 documentation page too:

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.
...

It works the same with WPF, and so the reason it is used with DragDrop, is that is how the it knows to report back to the control being dragged from when the mouse may be outside of that control. If you comment out the MyCanvas.Capture() and the Capture(Null) (which clears it) then you can no longer drop.

Answer 3

When it has captured the mouse, a control will receive mouse events even if the mouse pointer is no longer within its bounding area.

Typically, it's used for:

• Drag and drop
• Buttons (to handle Mouse Up when you put the mouse down on the button and move the mouse before you release the button)