Concepts clés

Les sections suivantes décrivent quelques concepts clés du processus de glisser-déposer.

Processus de glisser-déposer

Le processus de glisser-déposer comporte quatre étapes ou états: démarré, qui continue, a chuté et a pris fin.

Commencé

En réponse au geste de glissement d'un utilisateur, votre application appelle startDragAndDrop() pour indiquer au système de lancer une opération de glisser-déposer. La les arguments de cette méthode fournissent les éléments suivants:

• Données à faire glisser.
• Rappel pour dessiner l'ombre de glissement
• Métadonnées qui décrivent les données déplacées
• Le système répond en rappelant votre application pour obtenir un déplacement une ombre. Le système affiche ensuite l'ombre de l'action sur l'appareil.
• Ensuite, le système envoie un événement de déplacement avec un type d'action ACTION_DRAG_STARTED à l'événement de déplacement écouteur de tous les objets View de la mise en page actuelle. À continuent de recevoir des événements de déplacement, y compris un éventuel glisser-déposer - l'écouteur d'événements de déplacement doit renvoyer true. Cela enregistre l'écouteur avec le système. Seuls les écouteurs enregistrés continuent à recevoir des événements de déplacement. À ce stade, les écouteurs peuvent également modifier de l'objet View de la cible de dépôt pour montrer que la vue peut accepter un événement de dépôt.
• Si l'écouteur d'événements de déplacement renvoie false, il ne reçoit pas le déplacement pour l'opération en cours jusqu'à ce que le système envoie un événement de déplacement avec le type d'action ACTION_DRAG_ENDED. En renvoyant false, l'écouteur indique au système qu'il n'est pas intéressé lors de l'opération de glisser-déposer et ne souhaite pas accepter les données déplacées.

Poursuite de l'opération…

L'utilisateur poursuit le déplacement. Lorsque l'ombre de la traînée entre les deux cadre de délimitation d'une cible de dépôt, le système envoie un ou plusieurs événements de déplacement l'écouteur d'événements de déplacement de la cible. L'écouteur peut modifier l'apparence la cible de dépôt View en réponse à l'événement ; Par exemple, si l'événement indique que l'ombre de glissement entre dans le cadre de délimitation du dépôt cible : type d'action ACTION_DRAG_ENTERED : l'écouteur peut réagir en mettant View en surbrillance.

Déplacé

L'utilisateur libère l'ombre de glissement dans le cadre de délimitation d'un dépôt. cible. Le système envoie à l'écouteur de la cible de dépôt un événement de déplacement avec action saisissez ACTION_DROP. L'objet d'événement de déplacement contient les données transmises au système dans l'événement un appel à startDragAndDrop() qui lance l'opération. L'écouteur est doit renvoyer la valeur booléenne true au système si l'écouteur a réussi traite les données supprimées. : cette étape n'a lieu que si l'utilisateur place l'ombre de glissement à l'intérieur de la cadre de délimitation d'un objet View dont l'écouteur est enregistré pour recevoir des événements de déplacement (une cible de dépôt). Si l'utilisateur libère l'ombre de glissement dans une autre aucun événement de déplacement ACTION_DROP n'est envoyé.

Terminé

Une fois que l'utilisateur a libéré l'ombre de la trajectoire et une fois que le système a envoyé

un événement de déplacement avec le type d'action ACTION_DROP. Si nécessaire, le système envoie un événement de déplacement avec le type d'action ACTION_DRAG_ENDED pour indiquer que l'opération de glisser-déposer est terminée. Cela se fait quel que soit l'endroit où l'utilisateur libère l'ombre de la trajectoire. L'événement est envoyé à chaque écouteur enregistré pour recevoir des événements de déplacement, même si l'écouteur reçoit également Événement ACTION_DROP.

Chacune de ces étapes est décrite plus en détail dans la section intitulée Une opération de glisser-déposer.

Événements de déplacement

Le système envoie un événement de déplacement sous la forme d'un objet DragEvent, qui contient un type d'action décrivant ce qui se passe dans le glisser-déposer processus. Selon le type d'action, l'objet peut également contenir d'autres données.

Les écouteurs d'événements de déplacement reçoivent l'objet DragEvent. Pour obtenir le type d'action, appel des écouteurs DragEvent.getAction() Il existe six valeurs possibles définies par des constantes dans la classe DragEvent, décrits dans le tableau 1:

Tableau 1. Types d'action DragEvent

Type d'action	Signification
ACTION_DRAG_STARTED	L'application appelle startDragAndDrop() et obtient une ombre glissante. Si l'écouteur souhaite continuer à recevoir des événements de déplacement pour cette opération, la valeur booléenne true doit être renvoyée au du système d'exploitation.
ACTION_DRAG_ENTERED	L'ombre de déplacement entre dans le cadre de délimitation de l'écouteur d'événements de déplacement View Il s'agit du premier type d'action d'événement que l'écouteur reçoit lorsque l'ombre glissante entre dans le cadre de délimitation.
ACTION_DRAG_LOCATION	Après un ACTION_DRAG_ENTERED, l'ombre de l'étirement est fixe situé dans le cadre de délimitation de l'écouteur d'événements de déplacement View
ACTION_DRAG_EXITED	Vous suivez un ACTION_DRAG_ENTERED et au moins un ACTION_DRAG_LOCATION, l'ombre de l'action se déplace en dehors du cadre de délimitation de l'écouteur d'événements de déplacement View
ACTION_DROP	L'ombre de glissement se libère sur le paramètre View Ce type d'action est envoyé à un View écouteur de l'objet uniquement si l'écouteur renvoie des valeurs booléennes true en réponse à ACTION_DRAG_STARTED événement de déplacement. Ce type d'action n'est pas envoyé si l'utilisateur libère l'ombre de glissement sur un View dont l'écouteur n'est pas enregistré ou si l'utilisateur libère le déplacement une ombre sur tout ce qui ne fait pas partie de la mise en page actuelle. L'écouteur renvoie la valeur booléenne true s'il traite la chute avec succès. Sinon, elle doit renvoyer false
ACTION_DRAG_ENDED	Le système met fin à l'opération de glisser-déposer. Ce type d'action n'est pas nécessairement précédé d'un événement ACTION_DROP. Si le système envoie un ACTION_DROP, recevant la Le type d'action ACTION_DRAG_ENDED n'implique pas suppression réussie. L'écouteur doit appeler getResult(), comme indiqué dans le tableau 2, pour obtenir la valeur renvoyé en réponse à ACTION_DROP. Si un ACTION_DROP événement n'est pas envoyé, puis getResult() renvoie false.

L'objet DragEvent contient également les données et les métadonnées que votre application fournit au système dans l'appel de startDragAndDrop(). Certaines des données sont valide uniquement pour certains types d'actions, comme résumé dans le tableau 2. Pour plus sur les événements et les données associées, reportez-vous à la section A glisser-déposer.

Tableau 2. Données DragEvent valides par type d'action

getAction() valeur	getClipDescription() valeur	getLocalState() valeur	getX() valeur	getY() valeur	getClipData() valeur	getResult() valeur
ACTION_DRAG_STARTED	&vérifier;	&vérifier;
ACTION_DRAG_ENTERED	&vérifier;	&vérifier;
ACTION_DRAG_LOCATION	&vérifier;	&vérifier;	&vérifier;	&vérifier;
ACTION_DRAG_EXITED	&vérifier;	&vérifier;
ACTION_DROP	&vérifier;	&vérifier;	&vérifier;	&vérifier;	&vérifier;
ACTION_DRAG_ENDED		&vérifier;				&vérifier;

Les méthodes DragEvent getAction(), describeContents(), writeToParcel(), et toString() toujours renvoyer des données valides.

Si une méthode ne contient pas de données valides pour un type d'action particulier, elle renvoie null ou 0, selon le type de résultat.

Faire glisser l'ombre

Lors d'une opération de glisser-déposer, le système affiche une image que l'utilisateur fait glisser. Pour le déplacement des données, cette image représente les données déplacées. Pour d'autres opérations, l'image représente un aspect de l'opération de déplacement.

Cette image est appelée une ombre de déplacement. Vous la créez à l'aide des méthodes que vous déclarez un View.DragShadowBuilder . Vous transmettez le compilateur au système lorsque vous lancez un glisser-déposer à l'aide de startDragAndDrop(). Dans le cadre de sa réponse aux startDragAndDrop(), le système appelle les méthodes de rappel que vous définissez dans View.DragShadowBuilder pour obtenir une ombre de déplacement.

La classe View.DragShadowBuilder comporte deux constructeurs:

View.DragShadowBuilder(View)

Ce constructeur accepte n'importe quel élément Objets View. Le constructeur stocke l'objet View dans l'objet View.DragShadowBuilder, de sorte que les rappels peut y accéder pour construire l'ombre de glissement. Il n'est pas nécessaire que la vue soit View que l'utilisateur sélectionne pour lancer l'opération de déplacement.

Si vous utilisez ce constructeur, vous n'avez pas besoin d'étendre View.DragShadowBuilder ou remplacer ses méthodes. Par défaut, vous obtenez un indicateur une ombre qui a la même apparence que l'élément View que vous transmettez en tant qu'argument, centré sous l'endroit où l'utilisateur touche l'écran.

View.DragShadowBuilder()

Si vous utilisez ce constructeur, aucun objet View n'est disponible dans le View.DragShadowBuilder. Le champ est défini sur null. Vous devez prolonger View.DragShadowBuilder et remplacer ses méthodes. Dans le cas contraire, vous obtenez une une ombre de glissement invisible. Le système ne génère pas d'erreur.

La classe View.DragShadowBuilder comporte deux méthodes qui, ensemble, créent le déplacement shadow:

onProvideShadowMetrics()

Le système appelle cette méthode immédiatement après avoir appelé startDragAndDrop(). Cette méthode permet d'envoyer les dimensions et le point de contact de l'ombre glissante vers le système. Cette méthode comporte deux paramètres:

outShadowSize:Point . La largeur de l'ombre de glissement est comprise x, et sa hauteur est exprimée en y

outShadowTouchPoint:objet Point. Le point de contact est l'emplacement dans l'ombre qui doit se trouver sous le doigt de l'utilisateur pendant le déplacement. Sa position X passe à x et sa position Y à y.

onDrawShadow()

Immédiatement après l'appel à onProvideShadowMetrics(), le système appelle onDrawShadow() pour créer l'ombre de déplacement. La méthode ne comporte qu'un seul un argument, un objet Canvas qui le système à partir des paramètres que vous indiquez onProvideShadowMetrics() Cette méthode dessine l'ombre de glissement sur l'élément Canvas

Pour améliorer les performances, réduisez la taille de l'ombre de glissement. Pour une personne vous pouvez utiliser une icône. Dans le cas d'une sélection de plusieurs éléments, vous pouvez souhaitent utiliser des icônes dans une pile plutôt que des images complètes éparpillées sur l'écran.

Écouteurs d'événements de glisser-déposer et méthodes de rappel

Un View reçoit des événements de déplacement avec un écouteur d'événements de déplacement qui implémente View.OnDragListener ou avec la méthode de rappel onDragEvent() de la vue. Quand ? le système appelle la méthode ou l'écouteur, il fournit l'argument DragEvent.

Dans la plupart des cas, il est préférable d'utiliser un écouteur plutôt que la méthode de rappel. Quand ? vous concevez des UI, vous ne sous-classez généralement pas les classes View, mais en utilisant de rappel vous oblige à créer des sous-classes pour remplacer la méthode. Dans vous pouvez implémenter une classe d'écouteur, puis l'utiliser avec plusieurs différents objets View. Vous pouvez également l'implémenter en tant que classe inline anonyme. ou une expression lambda. Pour définir l'écouteur pour un objet View, appelez setOnDragListener()

Vous pouvez également modifier l'implémentation par défaut de onDragEvent(). sans remplacer la méthode. Définissez un OnReceiveContentListener sur une vue ; pour en savoir plus, consultez setOnReceiveContentListener() La méthode onDragEvent() effectue alors les opérations suivantes par défaut:

• Renvoie la valeur "true" en réponse à l'appel de startDragAndDrop().

• Appels performReceiveContent() si les données du glisser-déposer sont déposées sur la vue. Les données sont transmises en tant qu'objet ContentInfo. La appelle OnReceiveContentListener.

• Renvoie la valeur "true" si les données de type "glisser-déposer" sont déposées sur la vue et si la OnReceiveContentListener consomme n'importe quel contenu.

Définissez OnReceiveContentListener de sorte qu'il traite les données spécifiquement pour votre l'application. Pour assurer la rétrocompatibilité jusqu'au niveau d'API 24, utilisez la version Jetpack de OnReceiveContentListener

Vous pouvez disposer d'un écouteur d'événements de déplacement et d'une méthode de rappel pour un objet View, dans auquel cas le système appelle d'abord l'écouteur. Le système n'appelle pas de rappel, sauf si l'écouteur renvoie false.

La combinaison de la méthode onDragEvent() et de View.OnDragListener est la suivante : analogue à la combinaison du onTouchEvent() et View.OnTouchListener utilisée avec les événements tactiles.