UIElement.CapturePointer(Pointer) Method

Reference

Definition

Namespace:: Windows.UI.Xaml

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Edit

Sets pointer capture to a UIElement. Once captured, only the element that has capture will fire pointer-related events.

public:
 virtual bool CapturePointer(Pointer ^ value) = CapturePointer;

bool CapturePointer(Pointer const& value);

public bool CapturePointer(Pointer value);

function capturePointer(value)

Public Function CapturePointer (value As Pointer) As Boolean

Parameters

value: Pointer

The pointer object reference.

Returns

Boolean

bool

true if the object has pointer capture; otherwise, false.

Examples

This example shows calling CapturePointer based on handling PointerPressed. It also shows a pattern for tracking and counting pointer references.

int _pointerCount;

public Scenario2()
{
    this.InitializeComponent();
    bEnteredExited.PointerEntered += bEnteredExited_PointerEntered;
    bEnteredExited.PointerExited += bEnteredExited_PointerExited;
    bEnteredExited.PointerPressed += bEnteredExited_PointerPressed;
    bEnteredExited.PointerReleased += bEnteredExited_PointerReleased;
    bEnteredExited.PointerMoved += bEnteredExited_PointerMoved;

    // To code for multiple Pointers (that is, fingers), 
    // we track how many entered/exited.
    _pointerCount = 0;
}

private void bEnteredExited_PointerMoved(object sender, 
    PointerRoutedEventArgs e)
{
    Scenario2UpdateVisuals(sender as Border, "Moved");
}

private void bEnteredExited_PointerReleased(object sender, 
    PointerRoutedEventArgs e)
{
    ((Border)sender).ReleasePointerCapture(e.Pointer);
    txtCaptureStatus.Text = string.Empty;
}

//Can only get capture on PointerPressed (i.e. touch down, mouse click, pen press)
private void bEnteredExited_PointerPressed(object sender, 
    PointerRoutedEventArgs e)
{
    if (tbPointerCapture.IsOn)
    {
        bool _hasCapture = ((Border)sender).CapturePointer(e.Pointer);
        txtCaptureStatus.Text = "Got Capture: " + _hasCapture;
    }
}

private void bEnteredExited_PointerExited(object sender, 
    PointerRoutedEventArgs e)
{
    _pointerCount--;
    Scenario2UpdateVisuals(sender as Border, "Exited");
}

private void bEnteredExited_PointerEntered(object sender, 
    PointerRoutedEventArgs e)
{
    _pointerCount++;
    Scenario2UpdateVisuals(sender as Border, "Entered");
}

private void Scenario2UpdateVisuals(Border border, 
    String eventDescription)
{
    switch (eventDescription.ToLower())
    {
        case "exited":
            if (_pointerCount <= 0)
            {
                border.Background = new SolidColorBrush(Colors.Red);
                bEnteredExitedTextBlock.Text = eventDescription;
            }
            break;
        case "moved":
            RotateTransform rt = 
                (RotateTransform)bEnteredExitedTimer.RenderTransform;
            rt.Angle += 2;
            if (rt.Angle > 360) rt.Angle -= 360;
            break;
        default:
            border.Background = new SolidColorBrush(Colors.Green);
            bEnteredExitedTextBlock.Text = eventDescription;
            break;
    }
}

private void Scenario2Reset(object sender, RoutedEventArgs e)
{
    Scenario2Reset();
}

private void Scenario2Reset()
{
    bEnteredExited.Background = new SolidColorBrush(Colors.Green);
    bEnteredExitedTextBlock.Text = string.Empty;
}

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

Remarks

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.

Applies to

Jaa