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 Responding to mouse interactions.
The CapturePointer method will return false if the pointer was already captured.
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.
Private _pointerCount As Integer Public Sub New() Me.InitializeComponent() AddHandler bEnteredExited.PointerEntered, AddressOf bEnteredExited_PointerEntered AddHandler bEnteredExited.PointerExited, AddressOf bEnteredExited_PointerExited AddHandler bEnteredExited.PointerPressed, AddressOf bEnteredExited_PointerPressed AddHandler bEnteredExited.PointerReleased, AddressOf bEnteredExited_PointerReleased AddHandler bEnteredExited.PointerMoved, AddressOf bEnteredExited_PointerMoved 'To code for multiple Pointers (i.e. Fingers) we track how many entered/exited. _pointerCount = 0 End Sub ''' <summary> ''' Invoked when this page is about to be displayed in a Frame. ''' </summary> ''' <param name="e">Event data that describes how this page was reached. The Parameter ''' property is typically used to configure the page.</param> Protected Overrides Sub OnNavigatedTo(e As NavigationEventArgs) End Sub Private Sub bEnteredExited_PointerMoved(sender As Object, e As PointerRoutedEventArgs) Scenario2UpdateVisuals(TryCast(sender, Border), "Moved") End Sub Private Sub bEnteredExited_PointerReleased(sender As Object, e As PointerRoutedEventArgs) DirectCast(sender, Border).ReleasePointerCapture(e.Pointer) txtCaptureStatus.Text = String.Empty End Sub 'Can only get capture on PointerPressed (i.e. touch down, mouse click, pen press) Private Sub bEnteredExited_PointerPressed(sender As Object, e As PointerRoutedEventArgs) If tbPointerCapture.IsOn Then Dim _hasCapture As Boolean = DirectCast(sender, Border).CapturePointer(e.Pointer) txtCaptureStatus.Text = "Got Capture: " & _hasCapture End If End Sub Private Sub bEnteredExited_PointerExited(sender As Object, e As PointerRoutedEventArgs) _pointerCount -= 1 Scenario2UpdateVisuals(TryCast(sender, Border), "Exited") End Sub Private Sub bEnteredExited_PointerEntered(sender As Object, e As PointerRoutedEventArgs) _pointerCount += 1 Scenario2UpdateVisuals(TryCast(sender, Border), "Entered") End Sub Private Sub Scenario2UpdateVisuals(border As Border, eventDescription As String) Select Case eventDescription.ToLower() Case "exited" If _pointerCount <= 0 Then border.Background = New SolidColorBrush(Colors.Red) bEnteredExitedTextBlock.Text = eventDescription End If Exit Select Case "moved" Dim rt As RotateTransform = DirectCast(bEnteredExitedTimer.RenderTransform, RotateTransform) rt.Angle += 2 If rt.Angle > 360 Then rt.Angle -= 360 End If Exit Select Case Else border.Background = New SolidColorBrush(Colors.Green) bEnteredExitedTextBlock.Text = eventDescription Exit Select End Select End Sub Private Sub Scenario2ResetMethod(sender As Object, e As RoutedEventArgs) Reset() End Sub Private Sub Reset() bEnteredExited.Background = New SolidColorBrush(Colors.Green) bEnteredExitedTextBlock.Text = String.Empty End Sub
Minimum supported client
Minimum supported server
|Windows Server 2012|
Minimum supported phone
|Windows Phone 8.1 [Windows Runtime apps only]|