Expand Minimize

UIElement.ReleasePointerCapture method

Applies to Windows and Windows Phone

Releases pointer captures for capture of one specific pointer by this UIElement.

Syntax

Public Sub ReleasePointerCapture(
  value As Pointer 
)

Parameters

value

Type: Pointer

The pointer reference. Use either saved references from previous captures, or pointer event data, to obtain this reference.

Remarks

Programmatically releasing the pointer capture with ReleasePointerCapture is not the only way that an element might lose pointer capture. For example, user-driven events such as releasing the pointer (touch point up, mouse button released) can cause the pointer capture to be canceled. You can listen for the PointerCaptureLost event to determine when this happens.

Another way that pointer capture might be canceled is if a pointer moves out of one app and into another app while the two apps are side-by-side.

You should only call ReleasePointerCapture if your app code has previously called CapturePointer, and has a reference to the particular Pointer instance where you want to release the pointer capture. You'd typically get that Pointer reference through an event such as PointerReleased or perhaps PointerMoved.

Your app code might call CapturePointer from a different UIElement than the one that has any current pointer capture. If so, that cancels any pointer capture previously made by other elements. A UIElement can capture multiple pointers to handle multiple touch points such as for manipulations, but only one UIElement in an app can have any pointer captures at any one time. For more info, see Quickstart: Pointers.

Examples

This example shows calling ReleasePointerCapture based on handling PointerReleased. It also shows code for capturing the pointer initially, and 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

Requirements

Minimum supported client

Windows 8

Minimum supported server

Windows Server 2012

Minimum supported phone

Windows Phone 8.1 [Windows Runtime apps only]

Namespace

Windows.UI.Xaml
Windows::UI::Xaml [C++]

Metadata

Windows.winmd

See also

CapturePointer
PointerReleased
UIElement
PointerCaptureLost
Input sample

 

 

Show:
© 2014 Microsoft