UIElement.CapturePointer(Pointer) Método

Referência

Definição

Namespace:: Windows.UI.Xaml

Importante

Algumas informações se referem a produtos de pré-lançamento que podem ser substancialmente modificados antes do lançamento. A Microsoft não oferece garantias, expressas ou implícitas, das informações aqui fornecidas.

Editar

Define a captura de ponteiro para um UIElement. Depois de capturado, somente o elemento que tem captura disparará eventos relacionados ao ponteiro.

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

Parâmetros

value: Pointer

A referência de objeto de ponteiro.

Retornos

Boolean

bool

true se o objeto tiver captura de ponteiro; caso contrário, false.

Exemplos

Este exemplo mostra a chamada de CapturePointer com base no tratamento de PointerPressed. Ele também mostra um padrão para rastrear e contar referências de ponteiro.

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

Comentários

Você só poderá capturar o ponteiro com êxito se o ponteiro estiver em um estado pressionado (Pointer.IsInContact deve ser true). O que fisicamente constitui ser pressionado varia de acordo com o tipo de dispositivo de ponteiro (botão do mouse pressionado, ponto de toque para baixo, caneta em contato). Se você tentar capturar um ponteiro que não está pressionado ou onde o ponteiro foi pressionado anteriormente, mas agora é liberado, CapturePointer retorna false. As capturas existentes não são afetadas por uma chamada do CapturePointer que retornou false.

Normalmente, você captura o ponteiro em um manipulador de eventos PointerPressed . A instância pointer que você obtém dos dados de evento PointerRoutedEventArgs do manipulador PointerPressed é o valor que você deve passar para o parâmetro de valor ao chamar CapturePointer de dentro do código do manipulador.

Normalmente, você captura o ponteiro porque deseja que a ação de ponteiro atual inicie um comportamento em seu aplicativo. Nesse caso, normalmente, você não deseja que outros elementos manipulem outros eventos provenientes das ações desse ponteiro, até que seu comportamento seja concluído ou seja cancelado liberando a captura de ponteiro. Se um ponteiro for capturado, somente o elemento que tem captura obterá os eventos de entrada do ponteiro e outros elementos não dispararão eventos mesmo que o ponteiro se mova para seus limites. Por exemplo, considere uma interface do usuário que tenha dois elementos adjacentes. Normalmente, se você movesse o ponteiro de um elemento para o outro, primeiro obteria eventos PointerMoved do primeiro elemento e, em seguida, do segundo elemento. Mas se o primeiro elemento capturou o ponteiro, o primeiro elemento continuará a receber eventos PointerMoved mesmo que o ponteiro capturado deixe seus limites. Além disso, o segundo elemento não dispara eventos PointerEntered para um ponteiro capturado quando o ponteiro capturado o insere.

O estado de captura de ponteiro e a geração dos eventos relacionados à captura de ponteiro não estão totalmente à espera do código do aplicativo. Se o usuário liberar o ponteiro, isso gerará um evento PointerReleased e as capturas de ponteiro associadas a esse ponteiro serão perdidas. Isso também dispara PointerCaptureLost no elemento de captura original.

Na maioria dos casos, a captura de ponteiro será lançada automaticamente quando o usuário concluir uma ação de entrada que libera a captura de ponteiro anterior (levantando um ponto de toque, liberando o botão esquerdo do mouse, tirando a caneta do intervalo). Outra condição que pode liberar a captura é qualquer ação que também dispare um evento PointerCanceled . Seu aplicativo normalmente pode contar com o comportamento de versão de captura associado às ações de entrada do usuário, sem precisar cancelar especificamente uma captura de ponteiro com ReleasePointerCapture ou ReleasePointerCaptures. Para obter mais informações, consulte Interações por mouse.

O método CapturePointer retornará false se o ponteiro já tiver sido capturado.

Um UIElement pode capturar mais de um ponto de ponteiro por vez. Use o parâmetro value para indicar a instância ponteiro que você deseja capturar.

Os eventos de entrada que representam gestos (como Tapped ou DoubleTapped) geralmente só são disparados depois que um ponteiro é liberado, portanto, você não deve tentar capturar um ponteiro em manipuladores de eventos para eventos de gesto. A referência ponteiro em dados de evento para eventos de gesto não terá permissão para iniciar uma captura de ponteiro.

Dica

Não tente usar CapturePointer fora do escopo de manipuladores de eventos de entrada relevantes para ponteiro. A menos que você tenha um Ponteiro associado a um ponteiro que tenha permissão para captura de ponteiro nesse momento, sua chamada do CapturePointer não terá nenhum efeito. Não há nenhuma maneira prática de gerar um novo Ponteiro e chamar CapturePointer usando esse novo ponteiro. Você só deve usar as referências de ponteiro que o sistema está fornecendo a você por meio dos dados de evento dos eventos de entrada relacionados ao ponteiro.

Aplica-se a

UIElement.CapturePointer(Pointer) Método

Definição

Parâmetros

Retornos

Exemplos

Comentários

Aplica-se a

Confira também

Comentários

Comentários

Recursos adicionais