Update/correct Drag and Drop docs.

am: c5109b3f6e

Change-Id: I6b64deb63cfdf6a2afac41cb819fb163b76f8849

core/java/android/view/DragEvent.java

@@ -153,12 +153,16 @@ public class DragEvent implements Parcelable {
      * if it can accept a drop. The onDragEvent() or onDrag() methods usually inspect the metadata
      * from {@link #getClipDescription()} to determine if they can accept the data contained in
      * this drag. For an operation that doesn't represent data transfer, these methods may
-     * perform other actions to determine whether or not the View should accept the drag.
+     * perform other actions to determine whether or not the View should accept the data.
      * If the View wants to indicate that it is a valid drop target, it can also react by
      * changing its appearance.
      * <p>
-     * A View only receives further drag events if it returns {@code true} in response to
+     *  Views added or becoming visible for the first time during a drag operation receive this
-     * ACTION_DRAG_STARTED.
+     *  event when they are added or becoming visible.
+     * </p>
+     * <p>
+     *  A View only receives further drag events if it returns {@code true} in response to
+     *  ACTION_DRAG_STARTED.
      * </p>
      * @see #ACTION_DRAG_ENDED
      * @see #getX()
@@ -177,9 +181,10 @@ public class DragEvent implements Parcelable {
      * </p>
      * <p>
      * The system stops sending ACTION_DRAG_LOCATION events to a View once the user moves the
-     * drag shadow out of the View object's bounding box. If the user moves the drag shadow back
+     * drag shadow out of the View object's bounding box or into a descendant view that can accept
-     * into the View object's bounding box, the View receives an ACTION_DRAG_ENTERED again before
+     * the data. If the user moves the drag shadow back into the View object's bounding box or out
-     * receiving any more ACTION_DRAG_LOCATION events.
+     * of a descendant view that can accept the data, the View receives an ACTION_DRAG_ENTERED again
+     * before receiving any more ACTION_DRAG_LOCATION events.
      * </p>
      * @see #ACTION_DRAG_ENTERED
      * @see #getX()
@@ -189,7 +194,8 @@ public class DragEvent implements Parcelable {
 
     /**
      * Action constant returned by {@link #getAction()}: Signals to a View that the user
-     * has released the drag shadow, and the drag point is within the bounding box of the View.
+     * has released the drag shadow, and the drag point is within the bounding box of the View and
+     * not within a descendant view that can accept the data.
      * The View should retrieve the data from the DragEvent by calling {@link #getClipData()}.
      * The methods {@link #getX()} and {@link #getY()} return the X and Y position of the drop point
      * within the View object's bounding box.
@@ -212,8 +218,10 @@ public class DragEvent implements Parcelable {
      * operation has concluded.  A View that changed its appearance during the operation should
      * return to its usual drawing state in response to this event.
      * <p>
-     * All views that received an ACTION_DRAG_STARTED event will receive the
+     *  All views with listeners that returned boolean <code>true</code> for the ACTION_DRAG_STARTED
-     * ACTION_DRAG_ENDED event even if they are not currently visible when the drag ends.
+     *  event will receive the ACTION_DRAG_ENDED event even if they are not currently visible when
+     *  the drag ends. Views removed during the drag operation won't receive the ACTION_DRAG_ENDED
+     *  event.
      * </p>
      * <p>
      *  The View object can call {@link #getResult()} to see the result of the operation.
@@ -234,9 +242,10 @@ public class DragEvent implements Parcelable {
      *  drop target.
      * </p>
      * The system stops sending ACTION_DRAG_LOCATION events to a View once the user moves the
-     * drag shadow out of the View object's bounding box. If the user moves the drag shadow back
+     * drag shadow out of the View object's bounding box or into a descendant view that can accept
-     * into the View object's bounding box, the View receives an ACTION_DRAG_ENTERED again before
+     * the data. If the user moves the drag shadow back into the View object's bounding box or out
-     * receiving any more ACTION_DRAG_LOCATION events.
+     * of a descendant view that can accept the data, the View receives an ACTION_DRAG_ENTERED again
+     * before receiving any more ACTION_DRAG_LOCATION events.
      * </p>
      * @see #ACTION_DRAG_ENTERED
      * @see #ACTION_DRAG_LOCATION
@@ -245,7 +254,8 @@ public class DragEvent implements Parcelable {
 
     /**
      * Action constant returned by {@link #getAction()}: Signals that the user has moved the
-     * drag shadow outside the bounding box of the View.
+     * drag shadow out of the bounding box of the View or into a descendant view that can accept
+     * the data.
      * The View can react by changing its appearance in a way that tells the user that
      * View is no longer the immediate drop target.
      * <p>

docs/html/guide/topics/ui/drag-drop.jd

@@ -152,7 +152,7 @@ DraggableDot.java</a> in <a href="{@docRoot}resources/samples/ApiDemos/index.htm
     drag event listeners or callback methods of each View in the layout. The listeners or callback
     methods can use the metadata to decide if they want to accept the data when it is dropped.
     If the user drops the data over a View object, and that View object's listener or callback
-    method has previously told the system that it wants to accept the drop, then the system sends
+    method has previously told the system that it wants to accept the data, then the system sends
     the data to the listener or callback method in a drag event.
 </p>
 <p>
@@ -226,7 +226,8 @@ DraggableDot.java</a> in <a href="{@docRoot}resources/samples/ApiDemos/index.htm
     </dt>
     <dd>
         The user releases the drag shadow within the bounding box of a View that can accept the
-        data. The system sends the View object's listener a drag event with action type
+        data, but not within its descendant view that can accept the data. The system sends the View
+        object's listener a drag event with action type
         {@link android.view.DragEvent#ACTION_DROP}. The drag event contains the data that was
         passed to the system in the call to
         {@link android.view.View#startDrag(ClipData,View.DragShadowBuilder,Object,int) startDrag()}
@@ -317,6 +318,10 @@ DraggableDot.java</a> in <a href="{@docRoot}resources/samples/ApiDemos/index.htm
             application calls
 {@link android.view.View#startDrag(ClipData,View.DragShadowBuilder,Object,int) startDrag()} and
             gets a drag shadow.
+            <p>
+                If the listener wants to continue receiving drag events for this operation, it must
+                return boolean <code>true</code> to the system.
+            <\p>
         </td>
     </tr>
     <tr>
@@ -324,9 +329,7 @@ DraggableDot.java</a> in <a href="{@docRoot}resources/samples/ApiDemos/index.htm
         <td>
             A View object's drag event listener receives this event action type when the drag shadow
             has just entered the bounding box of the View. This is the first event action type the
-            listener receives when the drag shadow enters the bounding box. If the listener wants to
+            listener receives when the drag shadow enters the bounding box.
-            continue receiving drag events for this operation, it must return boolean
-            <code>true</code> to the system.
         </td>
     </tr>
     <tr>
@@ -334,7 +337,8 @@ DraggableDot.java</a> in <a href="{@docRoot}resources/samples/ApiDemos/index.htm
         <td>
             A View object's drag event listener receives this event action type after it receives a
             {@link android.view.DragEvent#ACTION_DRAG_ENTERED} event while the drag shadow is
-            still within the bounding box of the View.
+            still within the bounding box of the View and not within a descendant view that can
+            accept the data.
         </td>
     </tr>
     <tr>
@@ -343,7 +347,8 @@ DraggableDot.java</a> in <a href="{@docRoot}resources/samples/ApiDemos/index.htm
             A View object's drag event listener receives this event action type after it receives a
             {@link android.view.DragEvent#ACTION_DRAG_ENTERED} and at least one
             {@link android.view.DragEvent#ACTION_DRAG_LOCATION} event, and after the user has moved
-            the drag shadow outside the bounding box of the View.
+            the drag shadow outside the bounding box of the View or into a descendant view that can
+            accept the data.
         </td>
     </tr>
     <tr>
@@ -711,8 +716,7 @@ imageView.setOnLongClickListener(new View.OnLongClickListener() {
         If the listener can accept a drop, it should return <code>true</code>. This tells
         the system to continue to send drag events to the listener.
         If it can't accept a drop, it should return <code>false</code>, and the system
-        will stop sending drag events until it sends out
+        will stop sending drag events for the current drag operation.
-        {@link android.view.DragEvent#ACTION_DRAG_ENDED}.
     </li>
 </ol>
 <p>
@@ -754,7 +758,8 @@ imageView.setOnLongClickListener(new View.OnLongClickListener() {
     <li>
         {@link android.view.DragEvent#ACTION_DRAG_EXITED}:  This event is sent to a listener that
         previously received {@link android.view.DragEvent#ACTION_DRAG_ENTERED}, after
-        the drag shadow is no longer within the bounding box of the listener's View.
+        the drag shadow is no longer within the bounding box of the listener's View or it's within
+        the bounding box of a descendant view that can accept the data.
     </li>
 </ul>
 <p>