sdk doc change: Copy/Paste/Drag/Drop

Change-Id: Ifb9ed554ae1a72ce6badff1c79d95c02f30525e9

1 files changed, 250 insertions, 78 deletions

diff --git a/core/java/android/view/DragEvent.java b/core/java/android/view/DragEvent.java
index 4d838914c178..8f491ef61a0f 100644
--- a/core/java/android/view/DragEvent.java
+++ b/core/java/android/view/DragEvent.java
@@ -21,7 +21,100 @@ import android.content.ClipDescription;
 import android.os.Parcel;
 import android.os.Parcelable;
 
-/** !!! TODO: real docs */
+//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
+ * the operation and the underlying data.
+ * <p>
+ *  View objects that receive a DragEvent call {@link #getAction()}, which returns
+ *  an action type that indicates the state of the drag and drop operation. This allows a View
+ *  object to react to a change in state by changing its appearance or performing other actions.
+ *  For example, a View can react to the {@link #ACTION_DRAG_ENTERED} action type by
+ *  by changing one or more colors in its displayed image.
+ * </p>
+ * <p>
+ *  During a drag and drop operation, the system displays an image that the user drags. This image
+ *  is called a drag shadow. Several action types reflect the position of the drag shadow relative
+ *  to the View receiving the event.
+ * </p>
+ * <p>
+ *  Most methods return valid data only for certain event actions. This is summarized in the
+ *  following table. Each possible {@link #getAction()} value is listed in the first column. The
+ *  other columns indicate which method or methods return valid data for that getAction() value:
+ * </p>
+ * <table>
+ *  <tr>
+ *      <th scope="col">getAction() Value</th>
+ *      <th scope="col">getClipDescription()</th>
+ *      <th scope="col">getLocalState()</th>
+ *      <th scope="col">getX()</th>
+ *      <th scope="col">getY()</th>
+ *      <th scope="col">getClipData()</th>
+ *      <th scope="col">getResult()</th>
+ *  </tr>
+ *  <tr>
+ *      <td>ACTION_DRAG_STARTED</td>
+ *      <td style="text-align: center;">X</td>
+ *      <td style="text-align: center;">X</td>
+ *      <td style="text-align: center;">X</td>
+ *      <td style="text-align: center;">X</td>
+ *      <td style="text-align: center;">&nbsp;</td>
+ *      <td style="text-align: center;">&nbsp;</td>
+ *  </tr>
+ *  <tr>
+ *      <td>ACTION_DRAG_ENTERED</td>
+ *      <td style="text-align: center;">X</td>
+ *      <td style="text-align: center;">X</td>
+ *      <td style="text-align: center;">&nbsp;</td>
+ *      <td style="text-align: center;">&nbsp;</td>
+ *      <td style="text-align: center;">&nbsp;</td>
+ *      <td style="text-align: center;">&nbsp;</td>
+ *  </tr>
+ *  <tr>
+ *      <td>ACTION_DRAG_LOCATION</td>
+ *      <td style="text-align: center;">X</td>
+ *      <td style="text-align: center;">X</td>
+ *      <td style="text-align: center;">X</td>
+ *      <td style="text-align: center;">X</td>
+ *      <td style="text-align: center;">&nbsp;</td>
+ *      <td style="text-align: center;">&nbsp;</td>
+ *  </tr>
+ *  <tr>
+ *      <td>ACTION_DRAG_EXITED</td>
+ *      <td style="text-align: center;">X</td>
+ *      <td style="text-align: center;">X</td>
+ *      <td style="text-align: center;">&nbsp;</td>
+ *      <td style="text-align: center;">&nbsp;</td>
+ *      <td style="text-align: center;">&nbsp;</td>
+ *      <td style="text-align: center;">&nbsp;</td>
+ *  </tr>
+ *  <tr>
+ *      <td>ACTION_DROP</td>
+ *      <td style="text-align: center;">X</td>
+ *      <td style="text-align: center;">X</td>
+ *      <td style="text-align: center;">X</td>
+ *      <td style="text-align: center;">X</td>
+ *      <td style="text-align: center;">X</td>
+ *      <td style="text-align: center;">&nbsp;</td>
+ *  </tr>
+ *  <tr>
+ *      <td>ACTION_DRAG_ENDED</td>
+ *      <td style="text-align: center;">X</td>
+ *      <td style="text-align: center;">X</td>
+ *      <td style="text-align: center;">&nbsp;</td>
+ *      <td style="text-align: center;">&nbsp;</td>
+ *      <td style="text-align: center;">&nbsp;</td>
+ *      <td style="text-align: center;">X</td>
+ *  </tr>
+ * </table>
+ * <p>
+ *  The {@link android.view.DragEvent#getAction()},
+ *  {@link android.view.DragEvent#describeContents()},
+ *  {@link android.view.DragEvent#writeToParcel(Parcel,int)}, and
+ *  {@link android.view.DragEvent#toString()} methods always return valid data.
+ * </p>
+ */
 public class DragEvent implements Parcelable {
     private static final boolean TRACK_RECYCLED_LOCATION = false;
 
@@ -42,89 +135,113 @@ public class DragEvent implements Parcelable {
     private static DragEvent gRecyclerTop = null;
 
     /**
-     * Action constant returned by {@link #getAction()}.  Delivery of a DragEvent whose
-     * action is ACTION_DRAG_STARTED means that a drag operation has been initiated.  The
-     * view receiving this DragEvent should inspect the metadata of the dragged content,
-     * available via {@link #getClipDescription()}, and return {@code true} from
-     * {@link View#onDragEvent(DragEvent)} if the view is prepared to accept a drop of
-     * that clip data.  If the view chooses to present a visual indication that it is
-     * a valid target of the ongoing drag, then it should draw that indication in response
-     * to this event.
+     * Action constant returned by {@link #getAction()}: Signals the start of a
+     * drag and drop operation. The View should return {@code true} from its
+     * {@link View#onDragEvent(DragEvent) onDragEvent()} handler method or
+     * {@link View.View.OnDragListener#onDrag(View,DragEvent) OnDragListener.onDrag()} listener
+     * 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.
+     * If the View wants to indicate that it is a valid drop target, it can also react by
+     * changing its appearance.
      * <p>
-     * A view will only receive ACTION_DRAG_ENTERED, ACTION_DRAG_LOCATION, ACTION_DRAG_EXITED,
-     * and ACTION_DRAG_LOCATION events if it returns {@code true} in response to the
-     * ACTION_DRAG_STARTED event.
+     * A View only receives further drag events if it returns {@code true} in response to
+     * ACTION_DRAG_STARTED.
+     * </p>
+     * @see #ACTION_DRAG_ENDED
      */
     public static final int ACTION_DRAG_STARTED = 1;
 
     /**
-     * Action constant returned by {@link #getAction()}.  Delivery of a DragEvent whose
-     * action is ACTION_DRAG_LOCATION means that the drag operation is currently hovering
-     * over the view.  The {@link #getX()} and {@link #getY()} methods supply the location
-     * of the drag point within the view's coordinate system.
+     * 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
+     * the X and Y position of of the drag point within the View object's bounding box.
+     * <p>
+     * A View receives an {@link #ACTION_DRAG_ENTERED} event before receiving any
+     * ACTION_DRAG_LOCATION events.
+     * </p>
      * <p>
-     * A view will receive an ACTION_DRAG_ENTERED event before receiving any
-     * ACTION_DRAG_LOCATION events.  If the drag point leaves the view, then an
-     * ACTION_DRAG_EXITED event is delivered to the view, after which no more
-     * ACTION_DRAG_LOCATION events will be sent (unless the drag re-enters the view,
-     * of course).
+     * 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.
+     * </p>
+     * @see #ACTION_DRAG_ENTERED
+     * @see #getX()
+     * @see #getY()
      */
     public static final int ACTION_DRAG_LOCATION = 2;
 
     /**
-     * Action constant returned by {@link #getAction()}.  Delivery of a DragEvent whose
-     * action is ACTION_DROP means that the dragged content has been dropped on this view.
-     * The view should retrieve the content via {@link #getClipData()} and act on it
-     * appropriately.  The {@link #getX()} and {@link #getY()} methods supply the location
-     * of the drop point within the view's coordinate system.
+     * 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.
+     * 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.
+     * <p>
+     * The View should return {@code true} from its {@link View#onDragEvent(DragEvent)}
+     * handler or {@link View.View.OnDragListener#onDrag(View,DragEvent) OnDragListener.onDrag()}
+     * listener if it accepted the drop, and {@code false} if it ignored the drop.
+     * </p>
      * <p>
-     * The view should return {@code true} from its {@link View#onDragEvent(DragEvent)}
-     * method in response to this event if it accepted the content, and {@code false}
-     * if it ignored the drop.
+     * The View can also react to this action by changing its appearance.
+     * </p>
+     * @see #getClipData()
+     * @see #getX()
+     * @see #getY()
      */
     public static final int ACTION_DROP = 3;
 
     /**
-     * Action constant returned by {@link #getAction()}.  Delivery of a DragEvent whose
-     * action is ACTION_DRAG_ENDED means that the drag operation has concluded.  A view
-     * that is drawing a visual indication of drag acceptance should return to its usual
-     * drawing state in response to this event.
+     * Action constant returned by {@link #getAction()}:  Signals to a View that the drag and drop
+     * 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.
+     * ACTION_DRAG_ENDED event even if they are not currently visible when the drag ends.
+     * </p>
+     * <p>
+     *  The View object can call {@link #getResult()} to see the result of the operation.
+     *  If a View returned {@code true} in response to {@link #ACTION_DROP}, then
+     *  getResult() returns {@code true}, otherwise it returns {@code false}.
+     * </p>
+     * @see #ACTION_DRAG_STARTED
+     * @see #getResult()
      */
     public static final int ACTION_DRAG_ENDED = 4;
 
     /**
-     * Action constant returned by {@link #getAction()}.  Delivery of a DragEvent whose
-     * action is ACTION_DRAG_ENTERED means that the drag point has entered the view's
-     * bounds.  If the view changed its visual state in response to the ACTION_DRAG_ENTERED
-     * event, it should return to its normal drag-in-progress visual state in response to
-     * this event.
+     * Action constant returned by {@link #getAction()}: Signals to a View that the drag point has
+     * entered the bounding box of the View.
      * <p>
-     * A view will receive an ACTION_DRAG_ENTERED event before receiving any
-     * ACTION_DRAG_LOCATION events.  If the drag point leaves the view, then an
-     * ACTION_DRAG_EXITED event is delivered to the view, after which no more
-     * ACTION_DRAG_LOCATION events will be sent (unless the drag re-enters the view,
-     * of course).
+     *  If the View can accept a drop, it can react to ACTION_DRAG_ENTERED
+     *  by changing its appearance in a way that tells the user that the View is the current
+     *  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.
+     * </p>
+     * @see #ACTION_DRAG_ENTERED
+     * @see #ACTION_DRAG_LOCATION
      */
     public static final int ACTION_DRAG_ENTERED = 5;
 
     /**
-     * Action constant returned by {@link #getAction()}.  Delivery of a DragEvent whose
-     * action is ACTION_DRAG_ENTERED means that the drag point has entered the view's
-     * bounds.  If the view chooses to present a visual indication that it will receive
-     * the drop if it occurs now, then it should draw that indication in response to
-     * this event.
+     * Action constant returned by {@link #getAction()}: Signals that the user has moved the
+     * drag shadow outside the bounding box of the View.
+     * 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>
-     * A view will receive an ACTION_DRAG_ENTERED event before receiving any
-     * ACTION_DRAG_LOCATION events.  If the drag point leaves the view, then an
-     * ACTION_DRAG_EXITED event is delivered to the view, after which no more
-     * ACTION_DRAG_LOCATION events will be sent (unless the drag re-enters the view,
-     * of course).
+     *  After the system sends an ACTION_DRAG_EXITED event to the View, the View receives no more
+     *  ACTION_DRAG_LOCATION events until the user drags the drag shadow back over the View.
+     * </p>
+     *
      */
-public static final int ACTION_DRAG_EXITED = 6;
+     public static final int ACTION_DRAG_EXITED = 6;
 
     private DragEvent() {
     }
@@ -175,64 +292,101 @@ public static final int ACTION_DRAG_EXITED = 6;
 
     /**
      * Inspect the action value of this event.
-     * @return One of {@link #ACTION_DRAG_STARTED}, {@link #ACTION_DRAG_ENDED},
-     *         {@link #ACTION_DROP}, {@link #ACTION_DRAG_ENTERED}, {@link #ACTION_DRAG_EXITED},
-     *         or {@link #ACTION_DRAG_LOCATION}.
+     * @return One of the following action constants, in the order in which they usually occur
+     * during a drag and drop operation:
+     * <ul>
+     *  <li>{@link #ACTION_DRAG_STARTED}</li>
+     *  <li>{@link #ACTION_DRAG_ENTERED}</li>
+     *  <li>{@link #ACTION_DRAG_LOCATION}</li>
+     *  <li>{@link #ACTION_DROP}</li>
+     *  <li>{@link #ACTION_DRAG_EXITED}</li>
+     *  <li>{@link #ACTION_DRAG_ENDED}</li>
+     * </ul>
      */
     public int getAction() {
         return mAction;
     }
 
     /**
-     * For ACTION_DRAG_LOCATION and ACTION_DROP events, returns the x coordinate of the
-     * drag point.
-     * @return The current drag point's x coordinate, when relevant.
+     * Gets the X coordinate of the drag point. The value is only valid if the event action is
+     * {@link #ACTION_DRAG_LOCATION} or {@link #ACTION_DROP}.
+     * @return The current drag point's Y coordinate
      */
     public float getX() {
         return mX;
     }
 
     /**
-     * For ACTION_DRAG_LOCATION and ACTION_DROP events, returns the y coordinate of the
-     * drag point.
-     * @return The current drag point's y coordinate, when relevant.
+     * Gets the Y coordinate of the drag point. The value is valid if the
+     * event action is {@link #ACTION_DRAG_ENTERED}, {@link #ACTION_DRAG_LOCATION},
+     * {@link #ACTION_DROP}, or {@link #ACTION_DRAG_EXITED}.
+     * @return The current drag point's Y coordinate
      */
     public float getY() {
         return mY;
     }
 
     /**
-     * Provides the data payload of the drag operation.  This payload is only available
-     * for events whose action value is ACTION_DROP.
-     * @return The ClipData containing the data being dropped on the view.
+     * 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()}.
+     * This method only returns valid data if the event action is {@link #ACTION_DROP}.
+     * @return The ClipData sent to the system by startDrag().
      */
     public ClipData getClipData() {
         return mClipData;
     }
 
     /**
-     * Provides a description of the drag operation's data payload.  This payload is
-     * available for all DragEvents other than ACTION_DROP.
-     * @return A ClipDescription describing the contents of the data being dragged.
+     * 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()}.
+     * 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.
+     * <p>
+     * This method returns valid data for all event actions.
+     * @return The ClipDescription that was part of the ClipData sent to the system by startDrag().
      */
     public ClipDescription getClipDescription() {
         return mClipDescription;
     }
 
     /**
-     * Provides the local state object passed as the {@code myLocalState} parameter to
-     * View.startDrag(). The object will always be null here if the application receiving
-     * the DragEvent is not the one that started the drag.
+     * 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()}.
+     * 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.
+     * <p>
+     *  This method returns valid data for all event actions.
+     * </p>
+     * @return The local state object sent to the system by startDrag().
      */
     public Object getLocalState() {
         return mLocalState;
     }
 
     /**
-     * Provides an indication of whether the drag operation concluded successfully.
-     * This method is only available on ACTION_DRAG_ENDED events.
-     * @return {@code true} if the drag operation ended with an accepted drop; {@code false}
-     *         otherwise.
+     * <p>
+     * Returns an indication of the result of the drag and drop operation.
+     * This method only returns valid data if the action type is {@link #ACTION_DRAG_ENDED}.
+     * The return value depends on what happens after the user releases the drag shadow.
+     * </p>
+     * <p>
+     * If the user releases the drag shadow on a View that can accept a drop, the system sends an
+     * {@link #ACTION_DROP} event to the View object's drag event listener. If the listener
+     * returns {@code true}, then getResult() will return {@code true}.
+     * If the listener returns {@code false}, then getResult() returns {@code false}.
+     * </p>
+     * <p>
+     * Notice that getResult() also returns {@code false} if no {@link #ACTION_DROP} is sent. This
+     * happens, for example, when the user releases the drag shadow over an area outside of the
+     * application. In this case, the system sends out {@link #ACTION_DRAG_ENDED} for the current
+     * operation, but never sends out {@link #ACTION_DROP}.
+     * </p>
+     * @return {@code true} if a drag event listener returned {@code true} in response to
+     * {@link #ACTION_DROP}. If the system did not send {@link #ACTION_DROP} before
+     * {@link #ACTION_DRAG_ENDED}, or if the listener returned {@code false} in response to
+     * {@link #ACTION_DROP}, then {@code false} is returned.
      */
     public boolean getResult() {
         return mDragResult;
@@ -271,6 +425,11 @@ public static final int ACTION_DRAG_EXITED = 6;
         }
     }
 
+    /**
+     * Returns a string containing a concise, human-readable representation of this DragEvent
+     * object.
+     * @return A string representation of the DragEvent object.
+     */
     @Override
     public String toString() {
         return "DragEvent{" + Integer.toHexString(System.identityHashCode(this))
@@ -281,10 +440,20 @@ public static final int ACTION_DRAG_EXITED = 6;
 
     /* Parcelable interface */
 
+    /**
+     * Returns information about the {@link android.os.Parcel} representation of this DragEvent
+     * object.
+     * @return Information about the {@link android.os.Parcel} representation.
+     */
     public int describeContents() {
         return 0;
     }
 
+    /**
+     * Creates a {@link android.os.Parcel} object from this DragEvent object.
+     * @param dest A {@link android.os.Parcel} object in which to put the DragEvent object.
+     * @param flags Flags to store in the Parcel.
+     */
     public void writeToParcel(Parcel dest, int flags) {
         dest.writeInt(mAction);
         dest.writeFloat(mX);
@@ -304,6 +473,9 @@ public static final int ACTION_DRAG_EXITED = 6;
         }
     }
 
+    /**
+     * A container for creating a DragEvent from a Parcel.
+     */
     public static final Parcelable.Creator<DragEvent> CREATOR =
         new Parcelable.Creator<DragEvent>() {
         public DragEvent createFromParcel(Parcel in) {