Hide DragEvent pool implementation and add docs

Change-Id: Idaead8ab604c69d6dbc1bd5de3afa86e1fae8396

2 files changed, 114 insertions, 51 deletions

diff --git a/api/current.xml b/api/current.xml
index 2964fb0af178..3ccb4e95437c 100644
--- a/api/current.xml
+++ b/api/current.xml
@@ -194159,53 +194159,6 @@
  visibility="public"
 >
 </method>
-<method name="obtain"
- return="android.view.DragEvent"
- abstract="false"
- native="false"
- synchronized="false"
- static="true"
- final="false"
- deprecated="not deprecated"
- visibility="public"
->
-<parameter name="action" type="int">
-</parameter>
-<parameter name="x" type="float">
-</parameter>
-<parameter name="y" type="float">
-</parameter>
-<parameter name="description" type="android.content.ClipDescription">
-</parameter>
-<parameter name="data" type="android.content.ClipData">
-</parameter>
-<parameter name="result" type="boolean">
-</parameter>
-</method>
-<method name="obtain"
- return="android.view.DragEvent"
- abstract="false"
- native="false"
- synchronized="false"
- static="true"
- final="false"
- deprecated="not deprecated"
- visibility="public"
->
-<parameter name="source" type="android.view.DragEvent">
-</parameter>
-</method>
-<method name="recycle"
- return="void"
- abstract="false"
- native="false"
- synchronized="false"
- static="false"
- final="true"
- deprecated="not deprecated"
- visibility="public"
->
-</method>
 <method name="writeToParcel"
  return="void"
  abstract="false"
@@ -248181,7 +248134,7 @@
  deprecated="not deprecated"
  visibility="public"
 >
-<parameter name="t" type="T">
+<parameter name="arg0" type="T">
 </parameter>
 </method>
 </interface>
diff --git a/core/java/android/view/DragEvent.java b/core/java/android/view/DragEvent.java
index bbac14cc5c3e..07e87d673875 100644
--- a/core/java/android/view/DragEvent.java
+++ b/core/java/android/view/DragEvent.java
@@ -41,16 +41,90 @@ public class DragEvent implements Parcelable {
     private static DragEvent gRecyclerTop = null;
 
     /**
-     * action constants for DragEvent dispatch
+     * 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.
+     * <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.
      */
     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.
+     * <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).
+     */
     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.
+     * <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.
+     */
     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.
+     * <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.
+     */
     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.
+     * <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).
+     */
     public static final int ACTION_DRAG_ENTERED = 5;
-    public static final int ACTION_DRAG_EXITED = 6;
 
-    /* hide the constructor behind package scope */
+    /**
+     * 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.
+     * <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).
+     */
+public static final int ACTION_DRAG_EXITED = 6;
+
     private DragEvent() {
     }
 
@@ -68,6 +142,7 @@ public class DragEvent implements Parcelable {
         return DragEvent.obtain(0, 0f, 0f, null, null, false);
     }
 
+    /** @hide */
     public static DragEvent obtain(int action, float x, float y,
             ClipDescription description, ClipData data, boolean result) {
         final DragEvent ev;
@@ -90,31 +165,64 @@ public class DragEvent implements Parcelable {
         return ev;
     }
 
+    /** @hide */
     public static DragEvent obtain(DragEvent source) {
         return obtain(source.mAction, source.mX, source.mY,
                 source.mClipDescription, source.mClipData, source.mDragResult);
     }
 
+    /**
+     * 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}.
+     */
     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.
+     */
     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.
+     */
     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.
+     */
     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.
+     */
     public ClipDescription getClipDescription() {
         return mClipDescription;
     }
 
+    /**
+     * 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.
+     */
     public boolean getResult() {
         return mDragResult;
     }
@@ -122,6 +230,8 @@ public class DragEvent implements Parcelable {
     /**
      * Recycle the DragEvent, to be re-used by a later caller.  After calling
      * this function you must never touch the event again.
+     *
+     * @hide
      */
     public final void recycle() {
         // Ensure recycle is only called once!