Revised the OnDragListener and onDragEvent API documentation. (74390f89) · Commits · e / os / android_frameworks_base

core/java/android/view/View.java

+42 −48

Original line number	Diff line number	Diff line
		@@ -26842,43 +26842,37 @@ public class View implements Drawable.Callback, KeyEvent.Callback,
		* {@link android.view.View#startDragAndDrop(ClipData,DragShadowBuilder,Object,int)
		* startDragAndDrop()}.
		* <p>
		* When the system calls this method, it passes a
		* {@link android.view.DragEvent} object. A call to
		* {@link android.view.DragEvent#getAction()} returns one of the action type constants defined
		* in DragEvent. The method uses these to determine what is happening in the drag and drop
		* operation.
		* </p>
		* The system calls this method and passes a {@link DragEvent} object in response to drag and
		* drop events. This method can then call {@link DragEvent#getAction()} to determine the state
		* of the drag and drop operation.
		* <p>
		* The default implementation returns false, except if an {@link OnReceiveContentListener}
		* is {@link #setOnReceiveContentListener set} for this view. If an
		* {@link OnReceiveContentListener} is set, the default implementation...
		* The default implementation returns {@code false} unless an {@link OnReceiveContentListener}
		* has been set for this view (see {@link #setOnReceiveContentListener}), in which case
		* the default implementation does the following:
		* <ul>
		* <li>returns true for an
		* {@link android.view.DragEvent#ACTION_DRAG_STARTED ACTION_DRAG_STARTED} event
		* <li>calls {@link #performReceiveContent} for an
		* {@link android.view.DragEvent#ACTION_DROP ACTION_DROP} event
		* <li>returns true for an {@link android.view.DragEvent#ACTION_DROP ACTION_DROP} event, if
		* the listener consumed some or all of the content
		* <li>Returns {@code true} for an
		* {@link DragEvent#ACTION_DRAG_STARTED ACTION_DRAG_STARTED} event
		* <li>Calls {@link #performReceiveContent} for an
		* {@link DragEvent#ACTION_DROP ACTION_DROP} event
		* <li>Returns {@code true} for an {@link DragEvent#ACTION_DROP ACTION_DROP} event if the
		* {@code OnReceiveContentListener} consumed some or all of the content
		* </ul>
		* </p>
		*
		* @param event The {@link android.view.DragEvent} sent by the system.
		* The {@link android.view.DragEvent#getAction()} method returns an action type constant defined
		* in DragEvent, indicating the type of drag event represented by this object.
		* @return {@code true} if the method was successful, otherwise {@code false}.
		* @param event The {@link DragEvent} object sent by the system. The
		* {@link DragEvent#getAction()} method returns an action type constant that indicates the
		* type of drag event represented by this object.
		* @return {@code true} if the method successfully handled the drag event, otherwise
		* {@code false}.
		* <p>
		* The method should return {@code true} in response to an action type of
		* {@link android.view.DragEvent#ACTION_DRAG_STARTED} to receive drag events for the current
		* operation.
		* </p>
		* The method must return {@code true} in response to an
		* {@link DragEvent#ACTION_DRAG_STARTED ACTION_DRAG_STARTED} action type to continue to
		* receive drag events for the current drag and drop operation.
		* <p>
		* The method should also return {@code true} in response to an action type of
		* {@link android.view.DragEvent#ACTION_DROP} if it consumed the drop, or
		* {@code false} if it didn't.
		* </p>
		* The method should return {@code true} in response to an
		* {@link DragEvent#ACTION_DROP ACTION_DROP} action type if the dropped data was consumed
		* (at least partially); {@code false}, if none of the data was consumed.
		* <p>
		* For all other events, the return value is ignored.
		* </p>
		* For all other events, the return value is {@code false}.
		*/
		public boolean onDragEvent(DragEvent event) {
		if (mListenerInfo == null \|\| mListenerInfo.mOnReceiveContentListener == null) {
		@@ -28843,27 +28837,27 @@ public class View implements Drawable.Callback, KeyEvent.Callback,
		}

		/**
		* Interface definition for a callback to be invoked when a drag is being dispatched
		* to this view. The callback will be invoked before the hosting view's own
		* onDrag(event) method. If the listener wants to fall back to the hosting view's
		* onDrag(event) behavior, it should return 'false' from this callback.
		* Interface definition for a listener that's invoked when a drag event is dispatched to this
		* view. The listener is invoked before the view's own
		* {@link #onDragEvent(DragEvent)} method. To fall back to the view's
		* {@code onDragEvent(DragEvent)} behavior, return {@code false} from the listener method.
		*
		* <div class="special reference">
		* <h3>Developer Guides</h3>
		* <p>For a guide to implementing drag and drop features, read the
		* <a href="{@docRoot}guide/topics/ui/drag-drop.html">Drag and Drop</a> developer guide.</p>
		* <p>For a guide to implementing drag and drop features, see the
		* <a href="{@docRoot}guide/topics/ui/drag-drop.html">Drag and drop</a> developer guide.</p>
		* </div>
		*/
		public interface OnDragListener {
		/**
		* Called when a drag event is dispatched to a view. This allows listeners
		* to get a chance to override base View behavior.
		* Called when a drag event is dispatched to a view. Enables listeners to override the
		* base behavior provided by {@link #onDragEvent(DragEvent)}.
		*
		* @param v The View that received the drag event.
		* @param event The {@link android.view.DragEvent} object for the drag event.
		* @return {@code true} if the drag event was handled successfully, or {@code false}
		* if the drag event was not handled. Note that {@code false} will trigger the View
		* to call its {@link #onDragEvent(DragEvent) onDragEvent()} handler.
		* @param v The {@code View} that received the drag event.
		* @param event The event object for the drag event.
		* @return {@code true} if the drag event was handled successfully; {@code false}, if the
		* drag event was not handled. <b>Note:</b> A {@code false} return value triggers the
		* view's {@link #onDragEvent(DragEvent)} handler.
		*/
		boolean onDrag(View v, DragEvent event);
		}