Reconocedor de gesto de arrastrar y colocar

Un gesto de arrastrar y colocar de .NET Multi-platform App UI (.NET MAUI) permite arrastrar elementos y sus paquetes de datos asociados desde una ubicación en pantalla a otra ubicación mediante un gesto continuo. Arrastrar y colocar puede tener lugar en una sola aplicación o puede iniciarse en una aplicación y finalizar en otra.

El origen de arrastre, que es el elemento en el que se inicia el gesto de arrastrar, puede proporcionar los datos que se van a transferir rellenando un objeto de paquete de datos. Cuando el origen de arrastre se libera, se produce la colocación. Es entonces cuando el destino de colocación, que es el elemento bajo el origen de arrastre, procesa el paquete de datos.

El proceso para habilitar la función de arrastrar y colocar en una aplicación es el siguiente:

1. Habilite la función de arrastrar en un elemento agregando un objeto DragGestureRecognizer a su colección GestureRecognizers. Para más información, consulte Habilitación del arrastre.
2. [opcional] Cree un paquete de datos. .NET MAUI rellena automáticamente el paquete de datos para los controles de imagen y texto pero, para el resto de contenido, deberás crear tu propio paquete de datos. Para obtener más información, consulte Creación de un paquete de datos.
3. Habilita la función de colocar en un elemento agregando un objeto DropGestureRecognizer a su colección GestureRecognizers. Para más información, consulte Habilitación de la colocación.
4. [opcional] Controle el evento DropGestureRecognizer.DragOver para indicar el tipo de operación que el destino de colocación permite. Para más información, consulte Controlar el evento DragOver.
5. [opcional] Procese el paquete de datos para recibir el contenido colocado. .NET MAUI recuperará automáticamente los datos de texto e imagen del paquete de datos pero, para el resto de contenido, deberás procesarlo. Para más información, consulte Proceso del paquete de datos.

Habilitación del arrastre

En .NET MAUI la clase DragGestureRecognizer proporciona el reconocimiento del gesto de arrastrar. Esta clase define las propiedades siguientes:

• CanDrag, de tipo bool, que indica si el elemento al que está asociado el reconocedor de gestos puede ser un origen de arrastre. El valor predeterminado de esta propiedad es true.
• DragStartingCommand, de tipo ICommand, que se ejecuta cuando un gesto de arrastrar se reconoce por primera vez.
• DragStartingCommandParameter, de tipo object, que es el parámetro que se pasa al objeto DragStartingCommand.
• DropCompletedCommand, de tipo ICommand, que se ejecuta cuando el origen de arrastre se coloca.
• DropCompletedCommandParameter, de tipo object, que es el parámetro que se pasa al objeto DropCompletedCommand.

Estas propiedades están respaldadas por objetos BindableProperty, lo que significa que pueden ser destinos de los enlaces de datos, y que se les puede aplicar un estilo.

La clase DragGestureRecognizer también define los eventos DragStarting y DropCompleted que se desencadenan siempre que la propiedad CanDrag sea true. Cuando un objeto DragGestureRecognizer detecta un gesto de arrastrar, ejecuta DragStartingCommand e invoca el evento DragStarting. Después, cuando el objeto DragGestureRecognizer detecta la finalización de un gesto de colocar, ejecuta DropCompletedCommand e invoca el evento DropCompleted.

El objeto DragStartingEventArgs que acompaña al evento DragStarting define las siguientes propiedades:

• Cancel, de tipo bool, indica si se debe cancelar el evento.
• Data, de tipo DataPackage, indica el paquete de datos que acompaña al origen de arrastre. Se trata de una propiedad de solo lectura.
• PlatformArgs, de tipo PlatformDragStartingEventArgs?, representa los argumentos específicos de la plataforma asociados al evento.

void OnDragStarting(object sender, DragStartingEventArgs e)
{
#if ANDROID
    string content = "insert your content here";
    e.PlatformArgs.SetClipData(Android.Content.ClipData.NewPlainText("Drag data", content));
#endif
}

void OnDragStarting(object sender, DragStartingEventArgs e)
{
#if IOS || MACCATALYST
    Func<UIKit.UIDragPreview> action = () =>
    {
        var image = UIKit.UIImage.FromFile("dotnet_bot.png");
        UIKit.UIImageView imageView = new UIKit.UIImageView(image);
        imageView.ContentMode = UIKit.UIViewContentMode.Center;
        imageView.Frame = new CoreGraphics.CGRect(0, 0, 250, 250);
        return new UIKit.UIDragPreview(imageView);
    };

    e.PlatformArgs.SetPreviewProvider(action);
#endif
}

void OnDragStarting(object sender, DragStartingEventArgs e)
{
#if IOS || MACCATALYST
    e.PlatformArgs.SetPrefersFullSizePreviews((interaction, session) => { return true; });
#endif
}

El objeto DropCompletedEventArgs que acompaña al evento DropCompleted define una propiedad PlatformArgs, de tipo PlatformDropCompletedEventArgs?, que representa los argumentos específicos de la plataforma asociados al evento.

En el ejemplo de XAML siguiente se muestra DragGestureRecognizer, que se adjunta a Image:

<Image Source="monkeyface.png">
    <Image.GestureRecognizers>
        <DragGestureRecognizer />
    </Image.GestureRecognizers>
</Image>

En este ejemplo, se puede iniciar un gesto de arrastrar en Image.

Creación de un paquete de datos

.NET MAUI compilará automáticamente un paquete de datos, cuando se inicie una arrastre, para los siguientes controles:

• Controles de texto. Los valores de texto se pueden arrastrar desde los objetos CheckBox, DatePicker, Editor, Entry, Label, RadioButton, Switch y TimePicker.
• Controles de imagen. Las imágenes se pueden arrastrar desde los controles Button, Image y ImageButton.

En la tabla siguiente se muestran las propiedades que se leen, y cualquier conversión que se intenta, cuando se inicia una operación de arrastrar en un control de texto:

En el caso de contenido que no sea texto ni imágenes, deberá crear un paquete de datos usted mismo.

La clase DataPackage representa los paquetes de datos, que define las siguientes propiedades:

• Properties, de tipo DataPackagePropertySet, que es una colección de propiedades que comprenden los datos contenidos en DataPackage. Esta propiedad es de solo lectura.
• Image, de tipo ImageSource, que es la imagen contenida en DataPackage.
• Text, de tipo string, que es el texto contenido en DataPackage.
• View, de tipo DataPackageView, que es una versión de solo lectura de DataPackage.

La clase DataPackagePropertySet representa una bolsa de propiedades almacenada en Dictionary<string,object>. Para información sobre la clase DataPackageView, vea Proceso del paquete de datos.

Almacenamiento de datos de imagen o texto

Los datos de imagen o texto se pueden asociar a un origen de arrastre mediante el almacenamiento de los datos en la propiedad DataPackage.Image o DataPackage.Text. Puedes agregar los datos en el controlador para el evento DragStarting.

En el ejemplo de XAML siguiente se muestra DragGestureRecognizer, que registra un controlador para el evento DragStarting:

<Path Stroke="Black"
      StrokeThickness="4">
    <Path.GestureRecognizers>
        <DragGestureRecognizer DragStarting="OnDragStarting" />
    </Path.GestureRecognizers>
    <Path.Data>
        <!-- PathGeometry goes here -->
    </Path.Data>
</Path>

En este ejemplo, DragGestureRecognizer se adjunta a un objeto Path. El evento DragStarting se genera cuando se detecta un gesto de arrastrar en Path, que ejecuta el controlador de eventos OnDragStarting:

void OnDragStarting(object sender, DragStartingEventArgs e)
{
    e.Data.Text = "My text data goes here";
}

El objeto DragStartingEventArgs que acompaña al evento DragStarting tiene una propiedad Data, de tipo DataPackage. En este ejemplo, la propiedad Text del objeto DataPackage se establece en string. Después, se puede acceder a DataPackage en la colocación para recuperar string.

Almacenamiento de datos en la bolsa de propiedades

Todos los datos, incluidas las imágenes y el texto, se pueden asociar a un origen de arrastre almacenando los datos en la colección DataPackage.Properties. Puedes agregar los datos en el controlador para el evento DragStarting.

En el ejemplo de XAML siguiente se muestra DragGestureRecognizer, que registra un controlador para el evento DragStarting:

<Rectangle Stroke="Red"
           Fill="DarkBlue"
           StrokeThickness="4"
           HeightRequest="200"
           WidthRequest="200">
    <Rectangle.GestureRecognizers>
        <DragGestureRecognizer DragStarting="OnDragStarting" />
    </Rectangle.GestureRecognizers>
</Rectangle>

En este ejemplo, DragGestureRecognizer se adjunta a un objeto Rectangle. El evento DragStarting se genera cuando se detecta un gesto de arrastrar en Rectangle, que ejecuta el controlador de eventos OnDragStarting:

void OnDragStarting(object sender, DragStartingEventArgs e)
{
    Shape shape = (sender as Element).Parent as Shape;
    e.Data.Properties.Add("Square", new Square(shape.Width, shape.Height));
}

El objeto DragStartingEventArgs que acompaña al evento DragStarting tiene una propiedad Data, de tipo DataPackage. La colección Properties del objeto DataPackage, que es una colección Dictionary<string, object>, puede modificarse para almacenar los datos necesarios. En este ejemplo, el diccionario Properties se modifica para almacenar un objeto Square, que representa el tamaño de Rectangle con respecto a una clave "Square".

Habilitación de la colocación

En .NET MAUI, el reconocimiento del gesto de colocar lo proporciona la clase DropGestureRecognizer. Esta clase define las propiedades siguientes:

• AllowDrop, de tipo bool, que indica si el elemento al que está asociado el reconocedor de gestos puede ser un destino de colocación. El valor predeterminado de esta propiedad es true.
• DragOverCommand, de tipo ICommand, que se ejecuta cuando el origen de arrastre se arrastra sobre el destino de colocación.
• DragOverCommandParameter, de tipo object, que es el parámetro que se pasa al objeto DragOverCommand.
• DragLeaveCommand, de tipo ICommand, que se ejecuta cuando el origen de arrastre se arrastra fuera del destino de colocación.
• DragLeaveCommandParameter, de tipo object, que es el parámetro que se pasa al objeto DragLeaveCommand.
• DropCommand, de tipo ICommand, que se ejecuta cuando el origen de arrastre se coloca sobre el destino de colocación.
• DropCommandParameter, de tipo object, que es el parámetro que se pasa al objeto DropCommand.

Estas propiedades están respaldadas por objetos BindableProperty, lo que significa que pueden ser destinos de los enlaces de datos, y que se les puede aplicar un estilo.

La clase DropGestureRecognizer también define los eventos DragOver, DragLeave y Drop que se desencadenan siempre que la propiedad AllowDrop es true. Cuando DropGestureRecognizer reconoce un origen de arrastre sobre el destino de colocación, ejecuta DragOverCommand e invoca el evento DragOver. A continuación, si el origen de arrastre se arrastra fuera del destino de colocación, DropGestureRecognizer ejecuta DragLeaveCommand e invoca el evento DragLeave. Finalmente, cuando DropGestureRecognizer reconoce un gesto de colocación sobre el destino de colocación, ejecuta DropCommand e invoca el evento Drop.

La clase DragEventArgs, que acompaña a los eventos DragOver y DragLeave, define las siguientes propiedades:

• Data, de tipo DataPackage, que contiene los datos asociados al origen de arrastre. Esta propiedad es de solo lectura.
• AcceptedOperation, de tipo DataPackageOperation, que especifica las operaciones que el destino de colocación permite.
• PlatformArgs, de tipo PlatformDragEventArgs?, representa los argumentos específicos de la plataforma asociados al evento.

void OnDragOver(object sender, DragEventArgs e)
{
#if IOS || MACCATALYST
    e.PlatformArgs.SetDropProposal(new UIKit.UIDropProposal(UIKit.UIDropOperation.Move));
#endif
}

void OnDragOver(object sender, DragEventArgs e)
{
#if WINDOWS
    var dragUI = e.PlatformArgs.DragEventArgs.DragUIOverride;
    dragUI.IsCaptionVisible = false;
    dragUI.IsGlyphVisible = false;
#endif
}

Para más información sobre la enumeración DataPackageOperation, consulte Controlar el evento DragOver.

La clase DropEventArgs que acompaña al evento Drop define las siguientes propiedades:

• Data, de tipo DataPackageView, que es una versión de solo lectura del paquete de datos.
• Handled, de tipo bool, indica si el controlador de eventos ha controlado el evento o si .NET MAUI debe continuar su propio procesamiento.
• PlatformArgs, de tipo PlatformDropEventArgs?, representa los argumentos específicos de la plataforma asociados al evento.

En el ejemplo de XAML siguiente se muestra DropGestureRecognizer, que se adjunta a Image:

<Image BackgroundColor="Silver"
       HeightRequest="300"
       WidthRequest="250">
    <Image.GestureRecognizers>
        <DropGestureRecognizer />
    </Image.GestureRecognizers>
</Image>

En este ejemplo, cuando un origen de arrastre se coloca en el destino de colocación Image, el origen de arrastre se copia en el destino de colocación, si dicho origen de arrastre es una clase ImageSource. .NET MAUI copia automáticamente las imágenes arrastradas, y el texto, en destinos de colocación compatibles.

Controlar el evento DragOver

El evento DropGestureRecognizer.DragOver se puede controlar opcionalmente para indicar qué tipo de operaciones permite el destino de colocación. Puedes indicar las operaciones permitidas estableciendo la propiedad AcceptedOperation, del tipo DataPackageOperation, en el objeto DragEventArgs que acompaña al evento DragOver.

La enumeración DataPackageOperation define los miembros siguientes:

• None, indica que no se realizará ninguna acción.
• Copy, indica que el contenido de origen de arrastre se copiará en el destino de colocación.

En el ejemplo de XAML siguiente se muestra DropGestureRecognizer, que registra un controlador para el evento DragOver:

<Image BackgroundColor="Silver"
       HeightRequest="300"
       WidthRequest="250">
    <Image.GestureRecognizers>
        <DropGestureRecognizer DragOver="OnDragOver" />
    </Image.GestureRecognizers>
</Image>

En este ejemplo, DropGestureRecognizer se adjunta a un objeto Image. El evento DragOver se desencadena cuando se arrastra un origen de arrastre sobre el destino de colocación, pero sin colocarse, lo que ejecuta el controlador de eventos OnDragOver:

void OnDragOver(object sender, DragEventArgs e)
{
    e.AcceptedOperation = DataPackageOperation.None;
}

En este ejemplo, la propiedad AcceptedOperation del objeto DragEventArgs se establece en DataPackageOperation.None. Este valor garantiza que no se realiza ninguna acción cuando se coloca un origen de arrastre sobre el destino de colocación.

Proceso del paquete de datos

El evento Drop se desencadena cuando se libera un origen de arrastre sobre un destino de colocación. .NET MAUI intenta automáticamente recuperar datos del paquete de datos cuando se coloca un origen de arrastre en los controles siguientes:

• Controles de texto. Los valores de texto se pueden colocar en los objetos CheckBox, DatePicker, Editor, Entry, Label, RadioButton, Switch y TimePicker.
• Controles de imagen. Las imágenes se pueden colocar en los controles Button, Imagey ImageButton.

En la tabla siguiente se muestran las propiedades que se establecen, y cualquier conversión que se intenta, cuando un origen de arrastre basado en texto se coloca en un control de texto:

En el caso de contenido que no sea texto ni imágenes, deberá procesar el paquete de datos usted mismo.

La clase DropEventArgs que acompaña al evento Drop define una propiedad Data, de tipo DataPackageView. Esta propiedad representa una versión de solo lectura del paquete de datos.

Recuperación de datos de imagen o texto

Los datos de imagen o texto se pueden recuperar de un paquete de datos en el controlador para el evento Drop, mediante métodos definidos en la clase DataPackageView.

La clase DataPackageView incluye los métodos GetImageAsync y GetTextAsync. El método GetImageAsync recupera una imagen del paquete de datos, que estaba almacenada en la propiedad DataPackage.Image, y devuelve Task<ImageSource>. De forma similar, el método GetTextAsync recupera texto del paquete de datos, que estaba almacenada en la propiedad DataPackage.Text, y devuelve Task<string>.

En el ejemplo siguiente se muestra un controlador de eventos Drop que recupera texto del paquete de datos para Path:

async void OnDrop(object sender, DropEventArgs e)
{
    string text = await e.Data.GetTextAsync();

    // Perform logic to take action based on the text value.
}

En este ejemplo, los datos de texto se recuperan del paquete de datos mediante el método GetTextAsync. Después, se puede tomar una acción basada en el valor de texto.

Recuperación de datos de la bolsa de propiedades

Todos los datos se pueden recuperar de un paquete de datos en el controlador del evento Drop mediante el acceso a la colección Properties del paquete de datos.

La clase DataPackageView define una propiedad Properties, de tipo DataPackagePropertySetView. La clase DataPackagePropertySetView representa una bolsa de propiedades de solo lectura almacenada en Dictionary<string, object>.

En el ejemplo siguiente se muestra un controlador de eventos Drop que recupera datos de la bolsa de propiedades de un paquete de datos para Rectangle:

void OnDrop(object sender, DropEventArgs e)
{
    Square square = (Square)e.Data.Properties["Square"];

    // Perform logic to take action based on retrieved value.
}

En este ejemplo, el objeto de Square se recupera de la bolsa de propiedades del paquete de datos mediante la especificación de la clave de diccionario "Square". Después, se puede tomar una acción basada en el valor recuperado.

Arrastrar y colocar entre aplicaciones

En iOS, Mac Catalyst y Windows, la arrastrar puede iniciarse en una aplicación con la operación de colocación correspondiente que termina en una aplicación .NET MAUI. La aplicación desde la que se arrastra un elemento es la aplicación de origen y la aplicación MAUI de .NET en la que se quita un elemento es la aplicación de destino.

#if IOS || MACCATALYST
using UIKit;
using Foundation;
#endif

async void OnDropGestureRecognizerDrop(object? sender, DropEventArgs e)
{
    var filePaths = new List<string>();

#if IOS || MACCATALYST
    var session = e.PlatformArgs?.DropSession;
    if (session == null)
        return;

    foreach (UIDragItem item in session.Items)
    {
        var result = await LoadItemAsync(item.ItemProvider, item.ItemProvider.RegisteredTypeIdentifiers.ToList());
        if (result is not null)
            filePaths.Add(result.FileUrl?.Path!);
    }
    foreach (var item in filePaths)
    {
        Debug.WriteLine($"Path: {item}");
    }

    static async Task<LoadInPlaceResult?> LoadItemAsync(NSItemProvider itemProvider, List<string> typeIdentifiers)
    {
        if (typeIdentifiers is null || typeIdentifiers.Count == 0)
            return null;

        var typeIdent = typeIdentifiers.First();

        if (itemProvider.HasItemConformingTo(typeIdent))
            return await itemProvider.LoadInPlaceFileRepresentationAsync(typeIdent);

        typeIdentifiers.Remove(typeIdent);
        return await LoadItemAsync(itemProvider, typeIdentifiers);
    }
#endif

    string filePath = filePaths.FirstOrDefault();

    // Process the dropped file
}

#if WINDOWS
using Windows.ApplicationModel.DataTransfer;
using Windows.Storage;
#endif

async void OnDropGestureRecognizerDrop(object? sender, DropEventArgs e)
{
    var filePaths = new List<string>();

#if WINDOWS
    if (e.PlatformArgs is not null && e.PlatformArgs.DragEventArgs.DataView.Contains(StandardDataFormats.StorageItems))
    {
        var items = await e.PlatformArgs.DragEventArgs.DataView.GetStorageItemsAsync();
        if (items.Any())
        {
            foreach (var item in items)
            {
                if (item is StorageFile file)
                    filePaths.Add(item.Path);
            }
        }
    }
#endif

    string filePath = filePaths.FirstOrDefault();

    // Process the dropped file
}

Obtención de la posición del gesto

La posición en la que se puede obtener un gesto de arrastrar o soltar llamando al método GetPosition en un objeto DragEventArgs, DragStartingEventArgs o DropEventArgs. El método GetPosition acepta un argumento Element? y devuelve una posición como un objeto Point?:

void OnDragStarting(object sender, DragStartingEventArgs e)
{
    // Position relative to screen
    Point? screenPosition = e.GetPosition(null);

    // Position relative to specified element
    Point? relativeToImagePosition = e.GetPosition(image);
}

El argumento Element? define el elemento con respecto al cual debe obtenerse la posición. Suministrar un valor null como este argumento significa que el método GetPosition devuelve un objeto Point? que define la posición del gesto de arrastrar o soltar en relación con la pantalla.