Hide DragEvent pool implementation and add docs (855e4c98) · Commits · e / os / android_frameworks_base

api/current.xml

+1 −48

Original line number	Diff line number	Diff line
		@@ -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>

core/java/android/view/DragEvent.java

+113 −3

Original line number	Diff line number	Diff line
		@@ -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;

		/**
		* 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;

		/* hide the constructor behind package scope */
		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!