Android drag-and-drop model

English Original: http://developer.android.com/guide/topics/ui/drag-drop.html

PS: Time has passed, this article has been lost in my netease cloud notes. I have forgotten this is my excerpt of the online children's shoes, or the translation of their own.

It should have been generated on October 17, 2013, probably when I was writing an Android launcher project.

In order not to infringe on the rights of another, smart I picked up a few words in the article Baidu, found a similar translation but the wording like me so sharp as if there is no. Then the right to be translated by yourself.

Yes, do not doubt me, English level four will pass also can translate technical article.

API level 11 Join (Android 3.0)

With Android's drag-and-drop framework, you can allow users to move data from one view of the current layout to another view using an image drag-and-drop. This framework includes a drag event class, a drag listener, and some helper methods and classes.
While this framework is primarily designed for data movement, you can also use it for other interface actions. For example, you can create an app that blends two colors when the user drags a color icon onto another icon. The remainder of this topic describes the framework for data movement.
Overview
A drag-and-drop operation begins when the user makes some gestures that you can identify as starting to drag data. As a response, your application tells the system that the drag has started. The system callbacks your application to get a description of the data being dragged. When the user's finger moves this description in the current layout (a drag shadow), the system sends a drag event to the Drag event listener object and the drag event callback method associated with the view object in the layout. Once the user releases the drag shadow, the system ends the drag operation.
You can create a drag event listener through a class that implements the View.ondraglistener (). Bind to view by Setondraglistener (). Each view has a callback function for Ondragevent (). They have more details in the drag event listener and Callback methods section.
Note: For simplicity, the next section we call a routine that receives a drag event as a drag event listener, even if it is actually a callback method.
When you start a drag, you include the data that is being moved and the metadata that describes the data as part of the calling system. During drag, the system sends a drag-and-drop event to the listener or to the callback function for each view in the layout.
When the drag is stopped, the listener or callback function passes the metadata to determine whether they accept the drag. If accepted, the system sends the data of the drag event to the listener and the callback function.
Your application tells the system to start a drag by calling StartDrag (). This tells the system to start sending the drag event, and the colleague also sends the data you dragged.
You can call StartDrag () for other additional view in the current layout, and the system knowledge uses this view object to get the properties of the global configuration in your layout.
Once your application calls StartDrag (), the rest of the process uses the event that the system sends to the View object.
drag and drop process
The drag-and-drop process consists of four steps or states:
Started
In response to a user's gesture starting a drag, the application calls StartDrag () to tell the system to start a drag. The StartDrag () parameter provides the dragged data, its metadata, and the callback that draws the drag shadow.
The system first gets the drag shadow through the callback to the application, and then the drag shadow is displayed on the device.
Next, the system sends a drag event with the action type action_drag_started to the drag event listener for all view objects on the current layout. In order to continue accepting drag events, including possible drop events, the listener must return true. This is the Register listener to the system. Only registered listeners can continue to receive the drag event. At this point, the listener can also change the appearance of their view object to indicate that the listener can receive the drag event.
If the listener returns false, it will not be able to receive the current action's drag events until the system sends a drag event with the action type action_drag_ended. By sending false, the listener tells the system that it is not interested in this drag operation and does not want to continue to receive drag data.
continuing
The user continues to drag. When you drag a shadow through the border of the View object, one or more drag events are sent to the View object (if the receive event has already been registered). The listener may choose to change the appearance of the view object to respond to events. For example, if the event represents a drag shadow into the bounding area of the view (Action typeaction_drag_entered), the listener can highlight the view to respond.
Dropped
The user releases the drag shadow in the bounding area of a view that can receive it. The system sends a drag event to the View object with an action type of Action_drop. The drag event contains data passed to the system via the StartDrag () operation when initiating this operation. If the code receives success, the listener is expected to return true to the system.
Note that this step only occurs when the user drops the drag shadow in the bounding area of the view whose listener is registered to receive the drag event. If the user releases the drag shadow under any other circumstances, no Action_drop drag event is sent.
Ended
After the user releases the drag shadow, after the system sends a drag event of type Action_drop, the system sends a drag event with the action type action_drag_ended to indicate the end of the drag operation. This is done regardless of where the user released the Drag shadow. This event is sent to each listener registering to receive the drag event, even if the listener receives the Action_drop event.
Drag event listeners and callback methods
A view can receive a drag event by implementing View.ondraglistener's Drag event listener or view's Ondragevent method. When the system calls a callback method or listener, it passes to them a Dragevent object.
In most cases you might want to use the listener more. When designing an interface, it is usually not a subclass of the view class, but using a callback function forces you to do so, in order to override the method. By comparison, you can implement a listener class and then use it in several different view objects. You can also implement listeners in the same way as anonymous internal classes. To bind the listener to the View object, you need to call Setondraglistener ().
You can have both listeners and callback methods in a View object. In this case, the system calls the listener first. The system does not continue to invoke the callback method unless the listener returns FALSE.
The connection between Ondragevent (Dragevent) and View.ondraglistener is like the relationship between Ontouchevent () and View.ontouchlistener in touch events.
Drag Events
The system emits a drag event in the form of an Dragevent object. This object contains an action type that tells the listener what happened during the drag-and-drop process. This object also contains additional data, depending on the action type.
In order to get the action type, the listener calls Getaction (). There are six possible values, defined as constants in the Dragevent class.
The Drag event object also contains the data that the application provides to the system in StartDrag (). Some data is valid only if it is of a specific action type.

Getaction (), describecontents (), Writetoparcel (), and ToString () always return valid data.
If the method does not contain valid data, it returns null or 0, depending on its return value type.
Drag a shadow
In a drag-and-drop operation, the system displays a user-dragged image. For data movement, this picture represents the data being dragged. For other operations, the image represents some aspect of the drag operation.
This image is called a drag shadow. You can create it using the method you view.dragshadowbuilder the object declaration, and then use StartDrag () to pass it to the system when you start a drag. As a response to StartDrag (), the system calls the callback method you defined in View.dragshadowbuilder to get a drag shadow.
View.dragshadowbuilder has two constructors:
View.dragshadowbuilder (View)
View.dragshadowbuilder ()
There are two methods of View.dragshadowbuilder:
Onprovideshadowmetrics ()
Ondrawshadow ()
To improve performance, you should keep the size of this drag shadow small enough. In a single project, you might use an icon. In multiple projects, you may want to use the icon in the stack instead of expanding the full image on the screen.
design a drag-and-drop operation
This section step-by-step shows how to start a drag, how to drag an event in a process, how to respond to a release event, and how to end a drag-and-drop operation.
start a drag-and-drop

The user begins a drag gesture by dragging, usually in a long press of a view object. As a response, you should;
1. Create Clipdata and Clipdata.item for data that is about to be moved, if necessary. Clipdata provides metadata stored in its internal Clipdescription object. For drag-and-drop operations that do not represent data movement, you might want to replace the actual object with NULL.
Like what
2. The following code fragment defines Mydragshadowbuilder. It creates a small gray hold as a drag shadow for dragging a text view.
Note: You do not have to inherit View.dragshadowbuilder. The constructor View.dragshadowbuilder (view) creates a default drag shadow that is the same size as the incoming view, with the touch point as the center.
response A drag to start
During a drag operation, the system distributes drag events to the drag event listener for the View object in the current layout. The listener should get the action type by calling Getaction (). At the beginning of the drag, this method returns action_drag_started.
In response to an action_drag_started event, the listener needs to do the following:
1, call Getclipdescription () to get clipdescription. Use the MIME type method in Clipdescription to see if the listener can receive data that is being dragged.
This may not be necessary if the drag-and-drop operation does not represent data movement.
2. If the listener can receive the release, it should return true. This tells the system to continue sending the drag event to the listener. If you cannot receive the release event, you should return false and the system will stop sending the drag event until the action_drag_ended is issued.
Note: For a action_drag_started event, getclipdata () \ GetX () \ GetY () \ GetResult () in dragevent is not valid.
handling events during a drag
During the drag process, a listener that returns true as a response to the action_drag_started drag event continues to receive the drag event. The type of drag event that the listener receives during the drag process, depending on the location of the drag shadow and the visibility of the listener view.
During the drag process, the listener primarily uses the drag event to determine whether the shape of the view should be changed.
During the drag process, getaction () returns one of the following 3 values:
Action_drag_entered: The listener receives this event when the touch point enters the bounding area of the listener's view.
Action_drag_location: Once the listener receives the Action_drag_entered event, the touch point will receive a new action_drag_ each time it receives the action drag_exited The location event. The Getx and Gety methods return the coordinates of the touch points.
Action_drag_exited: When the drag shadow is no longer within the bounding area of the listener's view, the event is sent to a listener that previously received action_drag_entered.
The listener does not need to respond to other action types. If the listener returns a value to the system, it is ignored. Here are some guidelines for responding to these action types:
In response to action_drag_entered and action_drag_location, the listener can change the shape of the view to indicate that it can receive release.
Events with the action type Action_drag_location contain valid data for Getx and gety, corresponding to the position of the touch point. The listener may need this information to change the shape of the view on the touch point. The listener can also use this information to determine exactly where the user is going to release the drag shadow.
In response to action_drag_exited, the listener needs to be reset to a shape that changes in response to action_drag_entered or action_drag_location. This shows that the view is no longer a goal to release.
Response Release
When the user releases the drag shadow on the application's view, and the view has previously reported that it can receive the content being dragged, the system distributes an event of type Action_drop to the view. The listener needs to do the following:
1. Call Getclipdata () to get the Clipdata object that was originally provided by StartDrag () and store it. This is not necessary if the drag-and-drop operation does not represent data movement.
2. Returns true to indicate that the release operation was successfully processed and false indicates unsuccessful. The value of the GetResult () of the Action_drag_ended event as the return value.
Note: If the system does not emit a Action_drop event, Action_drag_ended's GetResult () returns false.
For the Action_drop event, Getx and Gety return the position of the drag point at release, using the coordinate system that receives the released view.
The system allows the user to release a drag shadow on a view that does not receive a drag event. It also allows the user to release drag shadows in an empty area of the application interface, or in an area other than the application. In these cases, the system does not issue a action_drop event, but it sends the action_drag_ended event.

End of response drag
As soon as the user releases the drag shadow, the system sends a action_drag_ended drag event to all the drag event listeners in the application. This is used to indicate that the drag operation is complete.
Each listener should do the following:
1. If the listener changes the appearance of the View object during the operation, it should be reset to the default appearance. This is to give the user a visual representation of the end of the operation.
2. The listener can choose to call GetResult () to find out more about the operation. Returns true if the listener returns true in response to Action_drop,getresult (). In other cases, GetResult () returns false, including cases where the system does not emit a Action_drop event.
3. The listener should return true to the system.

Android drag-and-drop model