From c5109b3f6e98b00518f00f5965479542c9bde394 Mon Sep 17 00:00:00 2001 From: Vadim Tryshev Date: Thu, 22 Sep 2016 18:26:09 -0700 Subject: [PATCH] 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 --- core/java/android/view/DragEvent.java | 36 ++++++++++++++++---------- docs/html/guide/topics/ui/drag-drop.jd | 25 +++++++++++------- 2 files changed, 38 insertions(+), 23 deletions(-) diff --git a/core/java/android/view/DragEvent.java b/core/java/android/view/DragEvent.java index 691a385be9da6..2baa0b4691ab6 100644 --- a/core/java/android/view/DragEvent.java +++ b/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. *

- * 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. + *

+ *

+ * A View only receives further drag events if it returns {@code true} in response to + * ACTION_DRAG_STARTED. *

* @see #ACTION_DRAG_ENDED * @see #getX() @@ -177,9 +181,10 @@ public class DragEvent implements Parcelable { *

*

* 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. *

* @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. *

- * 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 true 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. *

*

* 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. *

* 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. *

* @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. *

diff --git a/docs/html/guide/topics/ui/drag-drop.jd b/docs/html/guide/topics/ui/drag-drop.jd index 8871c87f4f258..092271b5caa99 100644 --- a/docs/html/guide/topics/ui/drag-drop.jd +++ b/docs/html/guide/topics/ui/drag-drop.jd @@ -152,7 +152,7 @@ DraggableDot.java in

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 in 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 - true to the system. + listener receives when the drag shadow enters the bounding box. @@ -334,7 +337,8 @@ DraggableDot.java in @@ -711,8 +716,7 @@ imageView.setOnLongClickListener(new View.OnLongClickListener() { If the listener can accept a drop, it should return true. This tells the system to continue to send drag events to the listener. If it can't accept a drop, it should return false, 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.

@@ -754,7 +758,8 @@ imageView.setOnLongClickListener(new View.OnLongClickListener() {

  • {@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.