| -api-id | -api-type |
|---|---|
M:Windows.UI.Xaml.UIElement.CapturePointer(Windows.UI.Xaml.Input.Pointer) |
winrt method |
Sets pointer capture to a UIElement. Once captured, only the element that has capture will fire pointer-related events.
The pointer object reference.
true if the object has pointer capture; otherwise, false.
You can only successfully capture the pointer if that pointer is in a pressed state (Pointer.IsInContact should be true). What physically constitutes being pressed will vary based on the pointer device type (mouse button pressed, touch point down, stylus in contact). If you attempt to capture a pointer that isn't pressed, or where the pointer was previously pressed but is now released, CapturePointer returns false. Existing captures aren't affected by a CapturePointer call that returned false.
You typically capture the pointer within a PointerPressed event handler. The Pointer instance you get from the PointerRoutedEventArgs event data of your PointerPressed handler is the value you should pass for the value parameter when you call CapturePointer from within your handler's code.
You typically capture the pointer because you want the current pointer action to initiate a behavior in your app. In this case you typically don't want other elements to handle any other events that come from that pointer's actions, until your behavior is either completed or is canceled by releasing the pointer capture. If a pointer is captured, only the element that has capture gets the pointer's input events, and other elements don't fire events even if the pointer moves into their bounds. For example, consider a UI that has two adjacent elements. Normally, if you moved the pointer from one element to the other, you'd first get PointerMoved events from the first element, and then from the second element. But if the first element has captured the pointer, then the first element continues to receive PointerMoved events even if the captured pointer leaves its bounds. Also, the second element doesn't fire PointerEntered events for a captured pointer when the captured pointer enters it.
The pointer capture state and generating the events that are related to pointer capture isn't entirely up to app code. If the user releases the pointer, that generates a PointerReleased event, and pointer captures associated with that pointer are lost. This also fires PointerCaptureLost on the original capturing element.
In most cases the pointer capture will be released automatically when the user completes an input action that releases the previous pointer capture (lifting a touch point, releasing the left mouse button, taking the stylus out of range). Another condition that might release capture is any action that also fires a PointerCanceled event. Your app can typically rely on the capture-release behavior associated with user input actions, without having to specifically cancel a pointer capture with ReleasePointerCapture or ReleasePointerCaptures. For more info, see Mouse interactions.
The CapturePointer method will return false if the pointer was already captured.
A UIElement can capture more than one pointer point at a time. Use the value parameter to indicate the Pointer instance you want to capture.
The input events that represent gestures (such as Tapped or DoubleTapped) are usually only fired after a pointer is released, so you shouldn't attempt to capture a pointer in event handlers for gesture events. The Pointer reference in event data for gesture events won't be permitted to initiate a pointer capture.
Tip
Don't try to use CapturePointer outside the scope of pointer-relevant input event handlers. Unless you have a Pointer that you're sure is associated with a pointer that's permitted to have pointer capture at that time, your CapturePointer call won't have any effect. There's no practical way to generate a new Pointer and call CapturePointer using that new pointer. You should only use the Pointer references the system is providing to you through the event data of the pointer-related input events.
This example shows calling CapturePointer based on handling PointerPressed. It also shows a pattern for tracking and counting pointer references.
[!code-csharpScenario2Code]
[!code-vbScenario2Code]
Pointer, ReleasePointerCapture, Handle pointer input, Relative mouse movement and CoreWindow, Input sample