Use drag-and-drop animations when users move objects with their fingers or with an input device, such as a mouse or stylus. Common drag-and-drop actions include moving a single item within a list and dropping one item on top of another.
Note Use the drag-and-drop animations only when the user is moving the object. To move the object otherwise, use the reposition animation.
This set of animations consists of the following APIs:
- dragSourceStart: the user begins to drag an object
- dragBetweenEnter: the user drags an object between two other objects that it can be dropped between
- dragBetweenLeave: the user drags an object away from a potential drop location
- dragSourceEnd: the user drops an object that they have been dragging
The following video demonstrates the animations associated with a drag-and-drop operation:
Drag start
Every drag-and-drop animation sequence begins with a drag start (dragSourceStart), which is shown when the user begins to drag an object.
This animation modifies the appearance of both the drag source (the object being dragged) and one or more affected objects. An affected object is an object that might change position in response to the drag-and-drop sequence. For example, when you reorder a list, all items in the list other than the drag source are affected objects because their position in the list could change as a result. Affected items are animated to show the user how those items would change position in response to the current action. Note that not all drag sources have affected objects.
To use the dragSourceStart function, you'll need to know the object that the user is dragging and its affected objects.
The following images show the relation of the drag source to the affected objects in the drag start animation. The first image shows the drag object and its neighbors before the user begins to drag the object.
When the user selects the object and begins to drag it, the dragged object becomes larger and the affected objects become smaller.
If neighboring objects are not affected, they do not become smaller.
Drag end
Every drag-and-drop animation sequence ends with the drag end animation (dragSourceEnd), which is shown when the user drops a dragged object. The drag end animation is never used unless the drag start animation was used first.
This animation places the drag source (the object being dragged) into its final position. It also removes the visual changes to the drag source and affected items that were applied by the drag start animation. The affected objects in a call to dragSourceEnd are always the same as the affected objects in the call to dragSourceStart.
To use the dragSourceEnd function, you'll need to know the object that the user is dropping, the final position of the dropped object, and the affected objects (if the dragSourceStart function included them).
The following images show the relation of the drag source to its affected objects in the drag end animation. The first image shows an object before the user drops it into a set of affected objects. The drag source is larger than its normal size, and offset from the list. The affected objects are smaller than their normal size.
If the dropped object does not affect other objects, the drag source is again larger and offset from the others, but the other objects are at their normal size.
Once the user drops the drag source, all objects return to their normal size, repositioned if necessary.
Drag between enter
Use the drag between enter animation (dragBetweenEnter) when the user drags an object (the drag source) between two other objects that it can be dropped between. This animation shows the user how affected objects move apart to make room for the drag source if the user chooses to drop the drag source in that position.
To use the dragBetweenEnter function, you'll need to know the affected objects and the direction and distance that those objects will move as part of the animation.
The following images show the movement of the affected objects in response to the drag source. The first image shows the affected objects before the position of the drag source triggers the drag between enter animation.
In the next image, the drag between enter animation has caused two objects, which the drag source is positioned to be dropped between, to move apart.
Drag between leave
Use the drag between leave animation (dragBetweenLeave) when the user drags the drag source away from a legitimate drop area between two objects. This animation shows the user that they no longer have the drag source in position to drop between those two objects. The drag between leave animation is used only after a drag between enter animation.
The action of the drag between leave animation is the opposite of the drag between enter animation. The drag between leave animation moves the affected objects back to their original positions.
To use the dragBetweenLeave function, you'll just need to know the affected objects.
The following images show the movement of the affected objects in response to the drag source. The first image shows the affected objects separated by the drag source enter animation, in response to the drag source's position.
In the next image, the drag between leave animation has been called to bring the affected objects back to their initial position.
Other resources
See the Using the Animation Library animations sample for code examples that demonstrate the use of the drag-and-drop animation APIs.
See Guidelines and checklist for drag-and-drop animations for design best practices in the use of these animations.
Related topics
- Animating your UI
- dragSourceEnd
- dragSourceStart
- dragBetweenLeave
- dragBetweenEnter
Build date: 3/5/2013
