Reconocimiento de un gesto de pulsación

Se usa el reconocedor de gestos de pulsación de .NET Multi-platform App UI (.NET MAUI) para la detección de pulsaciones y se implementa con la clase TapGestureRecognizer. Esta clase define las propiedades siguientes:

• Buttons, de tipo ButtonsMask, que define si el botón principal o secundario del mouse, o ambos, desencadena el gesto en Android, Mac Catalyst y Windows. Para obtener más información, consulta Definir las máscaras de botón.
• Command, de tipo ICommand, que se ejecuta cuando se reconoce una pulsación.
• CommandParameter, de tipo object, que es el parámetro que se pasa al objeto Command.
• NumberOfTapsRequired, de tipo int, que representa el número de pulsaciones necesarias para reconocer un gesto de pulsación. El valor predeterminado de esta propiedad es 1.

Estas propiedades están respaldadas por objetos BindableProperty, lo que significa que pueden ser destinos de los enlaces de datos, y con estilo.

La clase TapGestureRecognizer también define un evento Tapped que se genera cuando se reconoce una pulsación. El objeto TappedEventArgs que acompaña al evento Tapped define una propiedad Parameter de tipo object que indica el valor pasado por la propiedad CommandParameter, si se define. El objeto TappedEventArgs también define una propiedad Buttons y un método GetPosition. La propiedad Buttons es de tipo ButtonsMask y se puede usar para determinar si el botón primario o secundario del mouse desencadenó el reconocedor de gestos en Android, Mac Catalyst y Windows. El método GetPosition devuelve un objeto Point? que representa la posición en la que se detectó el gesto de pulsación. Para obtener más información sobre las máscaras de botón, consulta Definir la máscara de botón. Para obtener más información sobre el método GetPosition, consulta Obtención de la posición del gesto.

Advertencia

TapGestureRecognizer no puede reconocer más de una doble pulsación en Windows.

Crear un TapGestureRecognizer

Para hacer que View reconozca un gesto de pulsación, crea un objeto TapGestureRecognizer, controla el evento Tapped y agrega el nuevo reconocedor de gestos a la colección GestureRecognizers de la vista. En el ejemplo de código siguiente se muestra un elemento TapGestureRecognizer adjunto a Image:

<Image Source="dotnet_bot.png">
    <Image.GestureRecognizers>
        <TapGestureRecognizer Tapped="OnTapGestureRecognizerTapped"
                              NumberOfTapsRequired="2" />
  </Image.GestureRecognizers>
</Image>

El código del controlador de eventos OnTapGestureRecognizerTapped debería agregarse al archivo de código subyacente:

void OnTapGestureRecognizerTapped(object sender, TappedEventArgs args)
{
    // Handle the tap
}

El código de C# equivalente es el siguiente:

TapGestureRecognizer tapGestureRecognizer = new TapGestureRecognizer();
tapGestureRecognizer.Tapped += (s, e) =>
{
    // Handle the tap
};
Image image = new Image();
image.GestureRecognizers.Add(tapGestureRecognizer);

De forma predeterminada, Image responderá a pulsaciones simples. Cuando se establece la propiedad NumberOfTapsRequired por encima de uno, el controlador de eventos solo se ejecuta si las pulsaciones se producen dentro de un período de tiempo. Si la segunda pulsación (o las posteriores) no se producen dentro de ese período, se omiten eficazmente.

Definición de la máscara de botón

Un objeto TapGestureRecognizer tiene una propiedad Buttons, de tipo ButtonsMask, que define si el botón primario o secundario del mouse, o ambos, desencadena el gesto en Android, Mac Catalyst y Windows. La enumeración ButtonsMask define los miembros siguientes:

• Primary representa el botón primario del mouse, que suele ser el botón izquierdo del mouse.
• Secondary representa el botón secundario del mouse, que suele ser el botón derecho del mouse.

En el ejemplo siguiente se muestra TapGestureRecognizer que detecta pulsaciones con el botón secundario del mouse:

<Image Source="dotnet_bot.png">
    <Image.GestureRecognizers>
        <TapGestureRecognizer Tapped="OnTapGestureRecognizerTapped"
                              Buttons="Secondary" />
  </Image.GestureRecognizers>
</Image>

El controlador de eventos del evento Tapped puede determinar qué botón desencadenó el gesto:

void OnTapGestureRecognizerTapped(object sender, TappedEventArgs args)
{
    // Handle the tap
    if (args.Buttons == ButtonsMask.Secondary)
    {
        // Do something
    }
}

El código de C# equivalente es el siguiente:

TapGestureRecognizer tapGestureRecognizer = new TapGestureRecognizer
{
    Buttons = ButtonsMask.Secondary
};
tapGestureRecognizer.Tapped += (s, e) =>
{
    // Handle the tap
    if (args.Buttons == ButtonsMask.Secondary)
    {
        // Do something
    }
};
Image image = new Image();
image.GestureRecognizers.Add(tapGestureRecognizer);

Advertencia

En Windows, TapGestureRecognizer que establece la propiedad Buttons en Secondary no respeta la propiedad NumberOfTapsRequired cuando es mayor que uno.

Además, se puede definir TapGestureRecognizer para que el botón primario o secundario del mouse desencadene el gesto:

<TapGestureRecognizer Tapped="OnTapGestureRecognizerTapped"
                      Buttons="Primary,Secondary" />

El código de C# equivalente es el siguiente:

TapGestureRecognizer tapGestureRecognizer = new TapGestureRecognizer
{
    Buttons = ButtonsMask.Primary | ButtonsMask.Secondary
};

Obtención de la posición del gesto

La posición en la que se produjo un gesto de pulsación se puede obtener llamando al método GetPosition en un objeto TappedEventArgs. El método GetPosition acepta un argumento Element? y devuelve una posición como un objeto Point?:

void OnTapGestureRecognizerTapped(object sender, TappedEventArgs 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);
}

El argumento Element? define el elemento con respecto al cual debe obtenerse la posición. Proporcionar un valor null como este argumento significa que el método GetPosition devuelve un objeto Point? que define la posición del gesto de pulsación dentro de la ventana.