From ad57431f497fc555f8a58a7890073997883bf85f Mon Sep 17 00:00:00 2001 From: Vadim Tryshev Date: Tue, 27 Sep 2016 18:33:23 -0700 Subject: [PATCH] More fixes in drag/drop docs. Bug: 31702571 Test: Built docs, inspected in Chrome. Change-Id: Ib7c421a6eacac5e352bbba64eedb9f8b689cbe60 --- core/java/android/view/DragEvent.java | 27 ++++---- core/java/android/view/View.java | 3 + docs/html/guide/topics/ui/drag-drop.jd | 88 ++++++++++++++------------ 3 files changed, 68 insertions(+), 50 deletions(-) diff --git a/core/java/android/view/DragEvent.java b/core/java/android/view/DragEvent.java index 2baa0b4691ab6..16f2d7d0b6c7e 100644 --- a/core/java/android/view/DragEvent.java +++ b/core/java/android/view/DragEvent.java @@ -26,7 +26,7 @@ import com.android.internal.view.IDragAndDropPermissions; //TODO: Improve Javadoc /** * Represents an event that is sent out by the system at various times during a drag and drop - * operation. It is a complex data structure that contains several important pieces of data about + * operation. It is a data structure that contains several important pieces of data about * the operation and the underlying data. *

* View objects that receive a DragEvent call {@link #getAction()}, which returns @@ -161,8 +161,8 @@ public class DragEvent implements Parcelable { * 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. + * A View only receives further drag events for the drag operation if it returns {@code true} + * in response to ACTION_DRAG_STARTED. *

* @see #ACTION_DRAG_ENDED * @see #getX() @@ -172,8 +172,9 @@ public class DragEvent implements Parcelable { /** * Action constant returned by {@link #getAction()}: Sent to a View after - * {@link #ACTION_DRAG_ENTERED} if the drag shadow is still within the View object's bounding - * box. The {@link #getX()} and {@link #getY()} methods supply + * {@link #ACTION_DRAG_ENTERED} while the drag shadow is still within the View object's bounding + * box, but not within a descendant view that can accept the data. The {@link #getX()} and + * {@link #getY()} methods supply * the X and Y position of of the drag point within the View object's bounding box. *

* A View receives an {@link #ACTION_DRAG_ENTERED} event before receiving any @@ -355,9 +356,10 @@ public class DragEvent implements Parcelable { /** * Returns the {@link android.content.ClipData} object sent to the system as part of the call * to - * {@link android.view.View#startDrag(ClipData,View.DragShadowBuilder,Object,int) startDrag()}. + * {@link android.view.View#startDragAndDrop(ClipData,View.DragShadowBuilder,Object,int) + * startDragAndDrop()}. * This method only returns valid data if the event action is {@link #ACTION_DROP}. - * @return The ClipData sent to the system by startDrag(). + * @return The ClipData sent to the system by startDragAndDrop(). */ public ClipData getClipData() { return mClipData; @@ -366,12 +368,14 @@ public class DragEvent implements Parcelable { /** * Returns the {@link android.content.ClipDescription} object contained in the * {@link android.content.ClipData} object sent to the system as part of the call to - * {@link android.view.View#startDrag(ClipData,View.DragShadowBuilder,Object,int) startDrag()}. + * {@link android.view.View#startDragAndDrop(ClipData,View.DragShadowBuilder,Object,int) + * startDragAndDrop()}. * The drag handler or listener for a View can use the metadata in this object to decide if the * View can accept the dragged View object's data. *

* This method returns valid data for all event actions except for {@link #ACTION_DRAG_ENDED}. - * @return The ClipDescription that was part of the ClipData sent to the system by startDrag(). + * @return The ClipDescription that was part of the ClipData sent to the system by + * startDragAndDrop(). */ public ClipDescription getClipDescription() { return mClipDescription; @@ -384,7 +388,8 @@ public class DragEvent implements Parcelable { /** * Returns the local state object sent to the system as part of the call to - * {@link android.view.View#startDrag(ClipData,View.DragShadowBuilder,Object,int) startDrag()}. + * {@link android.view.View#startDragAndDrop(ClipData,View.DragShadowBuilder,Object,int) + * startDragAndDrop()}. * The object is intended to provide local information about the drag and drop operation. For * example, it can indicate whether the drag and drop operation is a copy or a move. *

@@ -394,7 +399,7 @@ public class DragEvent implements Parcelable { *

* This method returns valid data for all event actions except for {@link #ACTION_DRAG_ENDED}. *

- * @return The local state object sent to the system by startDrag(). + * @return The local state object sent to the system by startDragAndDrop(). */ public Object getLocalState() { return mLocalState; diff --git a/core/java/android/view/View.java b/core/java/android/view/View.java index d060aac4251de..6e18d6c5a5ba1 100644 --- a/core/java/android/view/View.java +++ b/core/java/android/view/View.java @@ -20830,6 +20830,9 @@ public class View implements Drawable.Callback, KeyEvent.Callback, * {@link android.view.DragEvent#ACTION_DROP} if it consumed the drop, or * {@code false} if it didn't. *

+ *

+ * For all other events, the return value is ignored. + *

*/ public boolean onDragEvent(DragEvent event) { return false; diff --git a/docs/html/guide/topics/ui/drag-drop.jd b/docs/html/guide/topics/ui/drag-drop.jd index 4a87cd4938cbc..bae3fe663800e 100644 --- a/docs/html/guide/topics/ui/drag-drop.jd +++ b/docs/html/guide/topics/ui/drag-drop.jd @@ -157,19 +157,22 @@ DraggableDot.java in
In response to the user's gesture to begin a drag, your application calls - {@link android.view.View#startDrag(ClipData,View.DragShadowBuilder,Object,int) startDrag()} - to tell the system to start a drag. The arguments - {@link android.view.View#startDrag(ClipData,View.DragShadowBuilder,Object,int) startDrag()} - provide the data to be dragged, metadata for this data, and a callback for drawing the - drag shadow. + {@link android.view.View#startDragAndDrop(ClipData,View.DragShadowBuilder,Object,int) + startDragAndDrop()} + to tell the system to start a drag. The + {@link android.view.View#startDragAndDrop(ClipData,View.DragShadowBuilder,Object,int) + startDragAndDrop()} + arguments provide the data to be dragged, metadata for this data, and a callback for drawing + the drag shadow.

The system first responds by calling back to your application to get a drag shadow. It then displays the drag shadow on the device. @@ -199,12 +204,13 @@ DraggableDot.java in true to the system if code for accepting the drop succeeds.

@@ -297,7 +304,8 @@ DraggableDot.java in table 2. It is also described in detail with the event for which it is valid in the section @@ -316,8 +324,9 @@ DraggableDot.java in {@link android.view.DragEvent#ACTION_DRAG_EXITED} 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 + {@link android.view.DragEvent#ACTION_DRAG_ENTERED} event, and after the user has moved the drag shadow outside the bounding box of the View or into a descendant view that can accept the data. @@ -355,7 +363,8 @@ DraggableDot.java in @@ -516,7 +527,8 @@ DraggableDot.java in Handling events during the drag

@@ -751,7 +762,9 @@ imageView.setOnLongClickListener(new View.OnLongClickListener() { {@link android.view.DragEvent#ACTION_DRAG_LOCATION}: Once the listener receives an {@link android.view.DragEvent#ACTION_DRAG_ENTERED} event, and before it receives an A{@link android.view.DragEvent#ACTION_DRAG_EXITED} event, it receives a new - {@link android.view.DragEvent#ACTION_DRAG_LOCATION} event every time the touch point moves. + {@link android.view.DragEvent#ACTION_DRAG_LOCATION} event immediately after the + {@link android.view.DragEvent#ACTION_DRAG_ENTERED} event, and then every time the touch + point moves. The {@link android.view.DragEvent#getX()} and {@link android.view.DragEvent#getY()} methods return the X and Y coordinates of the touch point. @@ -769,9 +782,9 @@ imageView.setOnLongClickListener(new View.OnLongClickListener() {

  • - In response to {@link android.view.DragEvent#ACTION_DRAG_ENTERED} or - {@link android.view.DragEvent#ACTION_DRAG_LOCATION}, the listener can change the appearance - of the View to indicate that it is about to receive a drop. + In response to {@link android.view.DragEvent#ACTION_DRAG_ENTERED}, the listener can change + the appearance + of the View to indicate that it is ready to receive a drop.
  • An event with the action type {@link android.view.DragEvent#ACTION_DRAG_LOCATION} contains @@ -784,14 +797,14 @@ imageView.setOnLongClickListener(new View.OnLongClickListener() {
  • In response to {@link android.view.DragEvent#ACTION_DRAG_EXITED}, the listener should reset any appearance changes it applied in response to - {@link android.view.DragEvent#ACTION_DRAG_ENTERED} or - {@link android.view.DragEvent#ACTION_DRAG_LOCATION}. This indicates to the user that + {@link android.view.DragEvent#ACTION_DRAG_ENTERED}. This indicates to the user that the View is no longer an imminent drop target.

Responding to a drop

- When the user releases the drag shadow on a View in the application, and that View previously + When the user releases the drag shadow on a View in the application, but not on its descendant + view that can accept the data, and that View previously reported that it could accept the content being dragged, the system dispatches a drag event to that View with the action type {@link android.view.DragEvent#ACTION_DROP}. The listener should do the following: @@ -800,8 +813,8 @@ imageView.setOnLongClickListener(new View.OnLongClickListener() {

  • Call {@link android.view.DragEvent#getClipData()} to get the {@link android.content.ClipData} object that was originally supplied in the call - to -{@link android.view.View#startDrag(ClipData, View.DragShadowBuilder, Object, int) startDrag()} + to {@link android.view.View#startDragAndDrop(ClipData, View.DragShadowBuilder, Object, int) + startDragAndDrop()} and store it. If the drag and drop operation does not represent data movement, this may not be necessary.
    • @@ -856,9 +869,6 @@ imageView.setOnLongClickListener(new View.OnLongClickListener() { including any case in which the system did not send out a {@link android.view.DragEvent#ACTION_DROP} event. -
  • - The listener should return boolean true to the system. -