What does it mean to “Capture the mouse” in WPF?

76
votes

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.

3
wpfeventsmouse
Think about how you can resize (more generally manipulate) an element drawn in a graphic editor. If you want to resize it using the corners of the bounding box, and be allowed to drag a corner outside the canvas, then you need to capture the mouse to continue receiving mouse events when the mouse pointer has left the canvas element. – mins

3 Answers

85
votes

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.

Only the capturing control receives the mouse events until released.

Capturing the mouse is useful for dragging because all the dragging code can exist in the one control, rather than being spread over multiple controls.

13
votes

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)
4
votes

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.