UIElement.ReleasePointerCapture(Pointer) Method

Reference

Definition

Namespace:: Microsoft.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

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

public:
 virtual void ReleasePointerCapture(Pointer ^ value) = ReleasePointerCapture;

void ReleasePointerCapture(Pointer const& value);

public void ReleasePointerCapture(Pointer value);

function releasePointerCapture(value)

Public Sub ReleasePointerCapture (value As Pointer)

Parameters

value: Pointer

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

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.

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;
}

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 PointerCaptureLostevent 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 UIElementcan 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 Handle pointer input.

Applies to