The Android drag and drop framework enables you to add interactive drag and drop capabilities to your app. With drag and drop, users can copy or move text, images, objects—any content that can be represented by a URI—from one Show
The framework includes a drag event class, drag listeners, and helper classes and methods. Although primarily designed to enable the transfer of data, the framework can be used for other UI actions. For example, you could create an app that mixes colors when the user drags a color icon over another icon. The rest of this guide, however, describes the drag and drop framework in the context of data transfer. OverviewA drag and drop operation starts when the user makes a UI gesture that your app recognizes as a signal to start dragging data. In response, the app notifies the system that a drag and drop operation is starting. The system calls back to your app to get a representation of the data being dragged (a drag shadow). As the user moves the drag shadow over the
app's layout, the system sends drag events to the drag event listeners and callback methods associated with the You create a drag event listener by implementing
Your application notifies the system to start a drag and drop operation by calling the During the drag and drop operation, the system sends drag events to the drag event listeners or callback methods of the Drag event listeners and callback methodsA In most cases, using a
listener is preferable to using the callback method. When you design UIs, you usually don't subclass As an alternative, the default implementation of
You define the You can have both a drag event listener and a callback method for a The combination of the Drag and drop processThere are basically four steps or states in the drag and drop process: Started, Continuing, Dropped, and Ended. StartedIn response to a user's drag gesture, your application calls
The system responds by first calling back to your application to get a drag shadow. The system then displays the drag shadow on the device. Next, the system sends a drag event with action type If the drag event listener returns The user continues the drag. As the drag shadow intersects the bounding box of a drop target, the system sends one or more drag events to the target's drag event listener. The listener may
choose to alter the appearance of the drop target The user releases the drag shadow within the bounding box of a drop target. The system
sends the drop target's listener a drag event with action type Note that this step only occurs if the user drops the drag shadow
within the bounding box of a After the user releases the drag shadow, and after the system sends out (if necessary) a drag event with action type Each of these four steps is described in more detail in A drag and drop operation. Drag eventsThe system sends out a drag event in
the form of a Drag event listeners receive the Table 1. DragEvent action types
The Table 2. Valid DragEvent data by action type
The If a method does not contain valid data for a particular action type, it returns either Drag shadowDuring a drag and drop operation, the system displays an image that the user drags. For data movement, this image represents the data being dragged. For other operations, the image represents some aspect of the drag operation. The image is called a drag shadow. You create it with methods you declare for a The View.DragShadowBuilder(View) This constructor accepts any of your application's If you use this constructor, you don't have to extend View.DragShadowBuilder() If you use this
constructor, no The onProvideShadowMetrics() The system calls this method immediately after you call Point object. The drag shadow width goes in x , and its height goes in y .outShadowTouchPointA Point object. The touch point is the location within the drag shadow
that should be under the user's finger during the drag. Its X position goes in x and its Y position goes in y .onDrawShadow() Immediately
after the call to To improve performance, you should keep the size of the drag shadow small. For a single item, you may want to use an icon. For a multiple-item selection, you may want to use icons in a stack rather than full images spread out over the screen. A drag and drop operationThis section shows step by step how to start a drag, how to respond to events during the drag, how respond to a drop event, and how to end the drag and drop operation. Start a dragThe user starts a drag with a drag gesture,
usually a touch & hold, on a
Respond to a drag startDuring the drag operation, the system dispatches drag events to the drag event listeners of the In
response to an event with the action type
Note that for an Handle events during the dragDuring the drag action, drag event listeners that returned During the drag action,
The drag event listener does not need to react to any of these action types. If the listener returns a value to the system, it is ignored. Here are some guidelines for responding to each of these action types:
Respond to a dropWhen the user releases the drag shadow over a The drag event listener should do the following:
For an The system allows the user to release the drag shadow over a Respond to a drag endImmediately after the user releases the drag shadow, the system sends a drag event with an action type of
Each drag event listener should do the following:
Respond to drag events: An exampleAll drag events are received by your drag event method or listener. The following code snippet is a simple example of responding to drag events:
Drag and drop in multi-window modeDevices that run Android 7.0 (API level 24) or higher support multi-window mode, which enables users to move data from one app to another using a drag and drop operation (see Multi-window support). The source app provides the data. The drag and drop operation starts in the source app. The target app receives the data. The drag and drop operation ends in the target app. When starting the drag and drop operation, the source app must set the Because the data moves across app boundaries, the apps share access to the data using a content URI:
The following code snippet demonstrates how to release read-only access to drag and drop data immediately after the drag and drop operation takes place. See the DragAndDrop sample on GitHub for a more complete example. Source drag and drop activity
Target drag and drop activity
DropHelper for simplified drag and dropThe Use Drop targets
For example, to create a drop target that accepts images, use either of the following method calls:
The second call omits the drop target configuration options, in which case the drop target highlight color is set to the theme secondary (or accent) color, the highlight corner radius is set to 16dp, and the list of EditTexts is empty (see Drop target configuration below). Drop target configurationThe Drop target highlighting
Use the
|