UIElement.CapturePointer(Pointer) Method
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.
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
- value
- Pointer
The pointer object reference.
bool
true if the object has pointer capture; otherwise, false.
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
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.
Product | Versions |
---|---|
WinRT | Build 10240, Build 10586, Build 14383, Build 15063, Build 16299, Build 17134, Build 17763, Build 18362, Build 19041, Build 20348, Build 22000, Build 22621, Build 26100 |