Ajouter des modules de reconnaissance des mouvements de glisser-déplacer

Un mouvement de glisser-déplacer permet aux éléments et à leurs packages de données associés d’être déplacés d’un emplacement à l’écran vers un autre emplacement à l’aide d’un mouvement continu. Le glisser-déplacer peut se produire au sein d’une même application, ou il peut commencer dans une application et se terminer dans une autre.

Important

La reconnaissance des mouvements de glisser-déplacer est prise en charge sur iOS, Android et le plateforme Windows universelle (UWP). Toutefois, sur iOS, une plateforme minimale d’iOS 11 est requise.

La source de glissement, qui est l’élément sur lequel le mouvement de glissement est initié, peut fournir des données à transférer en remplissant un objet de package de données. Quand la source de glissement est relâchée, le dépôt se produit. La cible de dépôt, qui est l’élément sous la source de glissement, traite alors le package de données.

Le processus d’activation du glisser-déplacer dans une application est le suivant :

1. Activez le glissement sur un élément en ajoutant un objet DragGestureRecognizer à sa collection GestureRecognizers. Pour plus d’informations, consultez Activer le glissement.
2. [facultatif] Créez un package de données. Xamarin.Forms remplit automatiquement le package de données pour les contrôles image et texte, mais pour d’autres contenus, vous devez construire votre propre package de données. Pour plus d’informations, consultez Créer un package de données.
3. Activez la suppression sur un élément en ajoutant une collection d’objets DropGestureRecognizer GestureRecognizers . Pour plus d’informations, consultez Activer le dépôt.
4. [facultatif] Gérez l’événement DropGestureRecognizer.DragOver pour indiquer le type d’opération autorisé par la cible de dépôt. Pour plus d’informations, consultez Gérer l’événement DragOver.
5. [facultatif] Traitez le package de données pour recevoir le contenu déposé. Xamarin.Forms récupère automatiquement les données d’image et de texte du package de données, mais pour d’autres contenus, vous devez traiter le package de données. Pour plus d’informations, consultez Traiter le package de données.

Remarque

Le fait de faire glisser des éléments vers et depuis un élément CollectionView n’est actuellement pas pris en charge.

Activer le dépôt

Dans Xamarin.Forms, la reconnaissance des mouvements de glisser est fournie par la DragGestureRecognizer classe. Cette classe définit les propriétés suivantes :

• CanDrag, de type bool, qui indique si l’élément auquel le module de reconnaissance de mouvement est attaché peut être une source de glissement. La valeur par défaut de cette propriété est true.
• DragStartingCommand, de type ICommand, qui est exécutée quand un mouvement de glissement est reconnu pour la première fois.
• DragStartingCommandParameter, de type object : paramètre passé à la commande DragStartingCommand.
• DropCompletedCommand, de type ICommand, qui est exécutée quand la source de glissement est déposée.
• DropCompletedCommandParameter, de type object : paramètre passé à la commande DropCompletedCommand.

Les propriétés s’appuient sur des objets BindableProperty, ce qui signifie qu’elles peuvent être les cibles de liaisons de données et mises en forme avec un style.

La DragGestureRecognizer classe définit DragStarting également et DropCompleted les événements qui se déclenchent à condition que la CanDrag propriété soit true. Quand un objet DragGestureRecognizer détecte un mouvement de glissement, il exécute la DragStartingCommand et appelle l’événement DragStarting. Ensuite, quand l’objet DragGestureRecognizer détecte la fin d’un mouvement de dépôt, il exécute la DropCompletedCommand et appelle l’événement DropCompleted.

L’objet DragStartingEventArgs qui accompagne l’événement DragStarting définit les propriétés suivantes :

• Handled, de type bool, indique si le gestionnaire d’événements a géré l’événement ou s’il Xamarin.Forms doit continuer son propre traitement.
• Cancel, de type bool, indique si l’événement doit être annulé.
• Data, de type DataPackage, indique le package de données qui accompagne la source de glissement. Il s’agit d’une propriété en lecture seule.

L’exemple XAML suivant montre un DragGestureRecognizer attaché à une Image :

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

Dans cet exemple, un mouvement de glissement peut être initié sur l’Image.

Conseil

Sur iOS, Android et UWP, un mouvement de glisser est lancé avec une longue pression suivie d’un glisser.

Créer un package de données

Xamarin.Forms génère automatiquement un package de données pour vous, lorsqu’un glisser-déplacer est lancé, pour les contrôles suivants :

• Contrôles de texte. Les valeurs de texte peuvent faire l'objet d'un glissement depuis des objets CheckBox, DatePicker, Editor, Entry, Label, RadioButton, Switch et TimePicker.
• Contrôles d’image. Les images peuvent faire l'objet d'un glissement depuis des contrôles Button, Image et ImageButton.

Le tableau suivant montre les propriétés qui sont lues et les conversions qui sont tentées quand un glissement est initié sur un contrôle de texte :

Control	Propriété	Conversion
CheckBox	IsChecked	bool converti en string.
DatePicker	Date	DateTime converti en string.
Editor	Text
Entry	Text
Label	Text
RadioButton	IsChecked	bool converti en string.
Switch	IsToggled	bool converti en string.
TimePicker	Time	TimeSpan converti en string.

Pour le contenu autre que du texte et des images, vous devez créer vous-même un package de données.

Les packages de données sont représentés par la classe DataPackage, qui définit les propriétés suivantes :

• Properties, de type DataPackagePropertySet, qui est une collection de propriétés comprenant les données contenues dans le DataPackage. Cette propriété est en lecture seule.
• Image, de type ImageSource, qui est l’image contenue dans le DataPackage.
• Text, de type string, qui est le texte contenu dans le DataPackage.
• View, de type DataPackageView, qui est une version en lecture seule du DataPackage.

La classe DataPackagePropertySet représente un conteneur de propriétés stocké en tant que Dictionary<string,object>. Pour plus d’informations sur la classe DataPackageView, consultez Traiter le package de données.

Stocker des données d’image ou de texte

Les données d’image ou de texte peuvent être associées à une source de glissement en stockant les données dans la propriété DataPackage.Image ou DataPackage.Text. Cette opération peut être effectuée dans le gestionnaire de l’événement DragStarting .

L’exemple XAML suivant montre un DragGestureRecognizer qui inscrit un gestionnaire pour l’événement DragStarting :

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

Dans cet exemple, le DragGestureRecognizer est attaché à un objet Path. L’événement DragStarting est déclenché lorsqu’un mouvement de glisser est détecté sur le Path, qui exécute le OnDragStarting gestionnaire d’événements :

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

L’objet DragStartingEventArgs qui accompagne l’événement DragStarting a une propriété Data, de type DataPackage. Dans cet exemple, la propriété Text de l’objet DataPackage est définie sur une string. Le DataPackage peut ensuite fait l’objet d’un accès au moment du dépôt pour récupérer la string.

Stocker des données dans le conteneur de propriétés

Vous pouvez associer les données, y compris les images et le texte, à une source de glissement en stockant les données dans la collection DataPackage.Properties. Cette opération peut être effectuée dans le gestionnaire de l’événement DragStarting .

L’exemple XAML suivant montre un DragGestureRecognizer qui inscrit un gestionnaire pour l’événement DragStarting :

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

Dans cet exemple, le DragGestureRecognizer est attaché à un objet Rectangle. L’événement DragStarting est déclenché lorsqu’un mouvement de glisser est détecté sur le Rectangle, qui exécute le OnDragStarting gestionnaire d’événements :

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));
}

L’objet DragStartingEventArgs qui accompagne l’événement DragStarting a une propriété Data, de type DataPackage. La collection Properties de l’objet DataPackage, qui est une collection Dictionary<string, object>, peut être modifiée pour stocker les données requises. Dans cet exemple, le Properties dictionnaire est modifié pour stocker un Square objet, qui représente la taille du Rectangle, par rapport à une clé « Carré ».

Activer le dépôt

Dans Xamarin.Forms, la reconnaissance des mouvements de suppression est fournie par la DropGestureRecognizer classe. Cette classe définit les propriétés suivantes :

• AllowDrop, de type bool, qui indique si l’élément auquel le module de reconnaissance de mouvement est attaché peut être une cible de dépôt. La valeur par défaut de cette propriété est true.
• DragOverCommand, de type ICommand, qui est exécutée quand la source de glissement fait l’objet d’un glissement sur la cible de dépôt.
• DragOverCommandParameter, de type object : paramètre passé à la commande DragOverCommand.
• DragLeaveCommand, de type ICommand, qui est exécutée quand la source de glissement fait l’objet d’un glissement en dehors de la cible de dépôt.
• DragLeaveCommandParameter, de type object : paramètre passé à la commande DragLeaveCommand.
• DropCommand, de type ICommand, qui est exécutée quand la source de glissement est déposée sur la cible de dépôt.
• DropCommandParameter, de type object : paramètre passé à la commande DropCommand.

Les propriétés s’appuient sur des objets BindableProperty, ce qui signifie qu’elles peuvent être les cibles de liaisons de données et mises en forme avec un style.

La DropGestureRecognizer classe définit DragOverégalement , DragLeaveet Drop les événements qui se déclenchent à condition que la AllowDrop propriété soit true. Quand un DropGestureRecognizer reconnaît une source de glissement sur la cible de dépôt, il exécute l’événement DragOverCommand et appelle l’événement DragOver. Ensuite, si la source de glissement fait l'objet d'un glissement en dehors de la cible de dépôt, le DropGestureRecognizer exécute l’événement DragLeaveCommand et appelle l’événement DragLeave. Enfin, quand le DropGestureRecognizer reconnaît un mouvement de dépôt sur la cible de dépôt, il exécute la DropCommand et appelle l’événement Drop.

La DragEventArgs classe, qui accompagne les événements et DragLeave les DragOver événements, définit les propriétés suivantes :

• Data, de type DataPackage, qui contient les données associées à la source de glissement. Cette propriété est en lecture seule.
• AcceptedOperation, de type DataPackageOperation, qui spécifie les opérations autorisées par la cible de dépôt.

Pour plus d’informations sur l’énumération DataPackageOperation, consultez Gérer l’événement DragOver.

La classe DropEventArgs qui accompagne l’événement Drop définit les propriétés suivantes :

• Data, de type DataPackageView, qui est une version en lecture seule du package de données.
• Handled, de type bool, indique si le gestionnaire d’événements a géré l’événement ou s’il Xamarin.Forms doit continuer son propre traitement.

L’exemple XAML suivant montre un DropGestureRecognizer attaché à une Image :

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

Dans cet exemple, lorsqu’une source de glissement est supprimée sur la Image cible de déplacement, la source de glissement est copiée vers la cible de déplacement, à condition que la source de glissement soit une ImageSource. Cela se produit, car Xamarin.Forms copie automatiquement les images déplacées et le texte vers des cibles de suppression compatibles.

Gérer l’événement DragOver

L’événement DropGestureRecognizer.DragOver peut éventuellement être géré pour indiquer les types d’opérations autorisés par la cible de dépôt. Pour ce faire, définissez la AcceptedOperation propriété, de type DataPackageOperation, de l’objet DragEventArgs qui accompagne l’événement DragOver .

L’énumération DataPackageOperation définit les membres suivants :

• None indique qu’aucune action ne sera effectuée.
• Copy indique que le contenu de la source de glissement sera copié dans la cible de dépôt.

Important

Quand un objet DragEventArgs est créé, la propriété AcceptedOperation a par défaut la valeur DataPackageOperation.Copy.

L’exemple XAML suivant montre un DropGestureRecognizer qui inscrit un gestionnaire pour l’événement DragOver :

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

Dans cet exemple, le DropGestureRecognizer est attaché à un objet Image. L’événement DragOver est déclenché lorsqu’une source de glissement est déplacée sur la cible de déplacement, mais n’a pas été supprimée, qui exécute le OnDragOver gestionnaire d’événements :

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

Dans cet exemple, la propriété AcceptedOperation de l’objet DragEventArgs est définie sur DataPackageOperation.None. Cela garantit qu’aucune action n’est effectuée lorsqu’une source de glisser-déplacer est supprimée sur la cible de déplacement.

Traiter le package de données

L’événement Drop est déclenché lorsqu’une source de glissement est libérée sur une cible de déplacement. Lorsque cela se produit, Xamarin.Forms tente automatiquement de récupérer des données à partir du package de données, lorsqu’une source de glissement est supprimée sur les contrôles suivants :

• Contrôles de texte. Les valeurs de texte peuvent être déposées sur des objets CheckBox, DatePicker, Editor, Entry, Label, RadioButton, Switch et TimePicker.
• Contrôles d’image. Les images peuvent être déposées sur des contrôles Button, Image et ImageButton.

Le tableau suivant montre les propriétés définies et toute conversion tentée, lorsqu’une source de glisser texte est supprimée sur un contrôle de texte :

Control	Propriété	Conversion
CheckBox	IsChecked	string est converti en bool.
DatePicker	Date	string est converti en DateTime.
Editor	Text
Entry	Text
Label	Text
RadioButton	IsChecked	string est converti en bool.
Switch	IsToggled	string est converti en bool.
TimePicker	Time	string est converti en TimeSpan.

Pour du contenu autre que du texte et des images, vous devez traiter vous-même le package de données.

La classe DropEventArgs qui accompagne l’événement Drop définit une propriété Data, de type DataPackageView. Cette propriété représente une version en lecture seule du package de données.

Récupérer des données d’image ou de texte

Les données d’image ou de texte peuvent être récupérées auprès d’un package de données dans le gestionnaire de l’événement Drop en utilisant des méthodes définies dans la classe DataPackageView.

La classe DataPackageView inclut les méthodes GetImageAsync et GetTextAsync. La GetImageAsync méthode récupère une image du package de données, qui a été stockée dans la DataPackage.Image propriété et retourne Task<ImageSource>. De même, la GetTextAsync méthode récupère du texte à partir du package de données, qui a été stocké dans la DataPackage.Text propriété et retourne Task<string>.

L’exemple suivant montre un gestionnaire d’événements Drop qui récupère du texte auprès du package de données pour un Path :

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

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

Dans cet exemple, les données de texte sont récupérées auprès du package de données en utilisant la méthode GetTextAsync. Une action basée sur la valeur de texte peut ensuite être effectuée.

Récupérer des données auprès du conteneur de propriétés

Les données peuvent être récupérées auprès d’un package de données dans le gestionnaire de l’événement Drop en accédant à la collection Properties du package de données.

La classe DataPackageView définit une propriété Properties de type DataPackagePropertySetView. La classe DataPackagePropertySetView représente un conteneur de propriétés en lecture seule stocké en tant que Dictionary<string, object>.

L’exemple suivant montre un gestionnaire d’événements Drop qui récupère des données auprès du conteneur de propriétés d’un package de données pour un Rectangle :

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

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

Dans cet exemple, l’objet Square est récupéré auprès du conteneur de propriétés du package de données en spécifiant la clé de dictionnaire « Square ». Une action basée sur la valeur récupérée peut ensuite être effectuée.