Update/correct Drag and Drop docs.
This CL reflects the N MR1 behavior and
fixes some bugs.
Defining the compatibility behavior will be
done separately.
Bug: 31702571
Change-Id: I2a79871f47849f9f5a9c3377a3061208488e6ecb
diff --git a/core/java/android/view/DragEvent.java b/core/java/android/view/DragEvent.java
index 691a385..2baa0b4 100644
--- a/core/java/android/view/DragEvent.java
+++ b/core/java/android/view/DragEvent.java
@@ -153,12 +153,16 @@
* 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
- * ACTION_DRAG_STARTED.
+ * Views added or becoming visible for the first time during a drag operation receive this
+ * 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 @@
* </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
- * into the View object's bounding box, the View receives an ACTION_DRAG_ENTERED again before
- * receiving any more ACTION_DRAG_LOCATION events.
+ * drag shadow out of the View object's bounding box or into a descendant view that can accept
+ * the data. If the user moves the drag shadow back into the View object's bounding box or out
+ * 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 @@
/**
* 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 @@
* 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
- * ACTION_DRAG_ENDED event even if they are not currently visible when the drag ends.
+ * All views with listeners that returned boolean <code>true</code> for the ACTION_DRAG_STARTED
+ * 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 @@
* 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
- * into the View object's bounding box, the View receives an ACTION_DRAG_ENTERED again before
- * receiving any more ACTION_DRAG_LOCATION events.
+ * drag shadow out of the View object's bounding box or into a descendant view that can accept
+ * the data. If the user moves the drag shadow back into the View object's bounding box or out
+ * 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 @@
/**
* 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>
diff --git a/docs/html/guide/topics/ui/drag-drop.jd b/docs/html/guide/topics/ui/drag-drop.jd
index 8871c87..092271b 100644
--- a/docs/html/guide/topics/ui/drag-drop.jd
+++ b/docs/html/guide/topics/ui/drag-drop.jd
@@ -152,7 +152,7 @@
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 @@
</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 @@
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 @@
<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
- continue receiving drag events for this operation, it must return boolean
- <code>true</code> to the system.
+ listener receives when the drag shadow enters the bounding box.
</td>
</tr>
<tr>
@@ -334,7 +337,8 @@
<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 @@
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 @@
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
- {@link android.view.DragEvent#ACTION_DRAG_ENDED}.
+ will stop sending drag events for the current drag operation.
</li>
</ol>
<p>
@@ -754,7 +758,8 @@
<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>
