Share via

Reconhecer um gesto de ponteiro

  • Artigo

Um reconhecedor de gestos de ponteiro do .NET MAUI (interface do usuário de aplicativo multiplataforma do .NET) detecta quando o ponteiro entra, sai e se move dentro de uma exibição e é implementado com a classe PointerGestureRecognizer. Essa classe define as seguintes propriedades:

Essas propriedades são apoiadas por objetos BindableProperty, o que significa que podem ser alvos de associações de dados e ser estilizada.

A classe PointerGestureRecognizer também define os seguintes eventos:

  • PointerEntered, que é gerado quando o ponteiro entra na área delimitadora da exibição.
  • PointerExited, que é gerado quando o ponteiro que está na área delimitadora da exibição deixa essa área delimitadora.
  • PointerMoved, que é gerado quando o ponteiro se move enquanto permanece dentro da área delimitadora da exibição.
  • PointerPressed, que é gerado quando o ponteiro inicia um pressionamento dentro da exibição.
  • PointerReleased, que é gerado quando o ponteiro que iniciou anteriormente um pressionamento é liberado, enquanto dentro da exibição.

Um objeto PointerEventArgs acompanha os eventos e define uma propriedade PlatformArgs do tipo PlatformPointerEventArgs, que fornece acesso a argumentos específicos da plataforma para o evento.

No Android, a classe PlatformPointerEventArgs define as seguintes propriedades:

  • Sender, do tipo View, representa a exibição nativa anexada ao evento.
  • MotionEvent, do tipo MotionEvent, indica o evento nativo ou o manipulador anexado à exibição.

Além disso, o objeto PointerEventArgs define um método GetPosition que retorna um objeto Point? que representa a posição do ponteiro quando o gesto foi detectado. Para obter mais informações sobre o método GetPosition, consulte Obter a posição do gesto.

Importante

O reconhecimento de gestos de ponteiro tem suporte no Android, iPadOS, Mac Catalyst e Windows.

O MAUI do .NET também define um estado visual PointerOver. Esse estado pode alterar a aparência visual de uma exibição quando ela tem um cursor do mouse pairando sobre ela, mas não é pressionada. Para obter mais informações, confira Estados visuais.

Criar um PointerGestureRecognizer

Para fazer um View reconhecer gestos de ponteiro, crie um objeto PointerGestureRecognizer, manipule os eventos necessários e adicione o reconhecedor de gestos à coleção GestureRecognizers na exibição. Como alternativa, crie um objeto PointerGestureRecognizer e associe os comandos necessários às implementações de ICommand e adicione o reconhecedor de gestos à coleção GestureRecognizers na exibição.

O exemplo de código a seguir mostra um PointerGestureRecognizer anexado a um Image. O PointerGestureRecognizer usa eventos para responder à detecção de gestos de ponteiro:

<Image Source="dotnet_bot.png">
    <Image.GestureRecognizers>
        <PointerGestureRecognizer PointerEntered="OnPointerEntered"
                                  PointerExited="OnPointerExited"
                                  PointerMoved="OnPointerMoved" />
  </Image.GestureRecognizers>
</Image>

O código para os manipuladores de eventos precisa ser adicionado ao arquivo code-behind:

void OnPointerEntered(object sender, PointerEventArgs e)
{
    // Handle the pointer entered event
}

void OnPointerExited(object sender, PointerEventArgs e)
{
    // Handle the pointer exited event
}

void OnPointerMoved(object sender, PointerEventArgs e)
{
    // Handle the pointer moved event
}

Este é o código C# equivalente:

PointerGestureRecognizer pointerGestureRecognizer = new PointerGestureRecognizer();
pointerGestureRecognizer.PointerEntered += (s, e) =>
{
    // Handle the pointer entered event
};
pointerGestureRecognizer.PointerExited += (s, e) =>
{
    // Handle the pointer exited event
};
pointerGestureRecognizer.PointerMoved += (s, e) =>
{
    // Handle the pointer moved event
};

Image image = new Image();
image.GestureRecognizers.Add(pointerGestureRecognizer);

Obter a posição do gesto

A posição na qual ocorreu um gesto de ponteiro pode ser obtida chamando o método GetPosition em um objeto PointerEventArgs. O método GetPosition aceita um argumento Element? e retorna uma posição como um objeto Point?:

void OnPointerExited(object sender, PointerEventArgs e)
{
    // Position inside window
    Point? windowPosition = e.GetPosition(null);

    // Position relative to an Image
    Point? relativeToImagePosition = e.GetPosition(image);

    // Position relative to the container view
    Point? relativeToContainerPosition = e.GetPosition((View)sender);
}

O argumento Element? define o elemento em relação ao qual a posição deve ser obtida. Fornecer um valor null como esse argumento significa que o método GetPosition retorna um objeto Point? que define a posição do gesto de ponteiro dentro da janela.