UIElement.CapturePointer(Pointer) Método

  • Referência

Definição

Namespace:
Microsoft.UI.Xaml
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 do objeto de ponteiro.

Retornos

Boolean

bool

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

Exemplos

Este exemplo mostra a chamada 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;
}

Comentários

Você só poderá capturar o ponteiro com êxito se esse 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 no 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 CapturePointer chamada que retornou false.

Normalmente, você captura o ponteiro dentro de 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 value parâmetro 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, você normalmente 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 tiver capturado o ponteiro, o primeiro elemento continuará recebendo PointerMoved eventos mesmo que o ponteiro capturado saia dos 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 são totalmente compatíveis com o 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á liberada 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 acione um evento PointerCanceled . Seu aplicativo normalmente pode depender do 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 CapturePointer método retornará false se o ponteiro já tiver sido capturado.

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

Os eventos de entrada que representam gestos (como Tapped ou DoubleTapped) geralmente são disparados somente 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 nos 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 que tenha certeza de que está associado a um ponteiro que tem permissão para ter a 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 Pointer e chamar CapturePointer usando esse novo ponteiro. Você só deve usar as Pointer referências que o sistema está fornecendo a você por meio dos dados de evento dos eventos de entrada relacionados ao ponteiro.

Aplica-se a

Confira também