From 74390f89b2e4fae32858d1673e35113365663dc6 Mon Sep 17 00:00:00 2001 From: joneckenrode Date: Wed, 1 Dec 2021 15:19:56 +0000 Subject: [PATCH] Revised the OnDragListener and onDragEvent API documentation. Test: Javadoc build Signed-off-by: joneckenrode Change-Id: I807143412b249787526c6e3f7e8a27cc7f77bf89 --- core/java/android/view/View.java | 90 +++++++++++++++----------------- 1 file changed, 42 insertions(+), 48 deletions(-) diff --git a/core/java/android/view/View.java b/core/java/android/view/View.java index f4223fb467f5..42a1220e5f41 100644 --- a/core/java/android/view/View.java +++ b/core/java/android/view/View.java @@ -26841,44 +26841,38 @@ public class View implements Drawable.Callback, KeyEvent.Callback, * Handles drag events sent by the system following a call to * {@link android.view.View#startDragAndDrop(ClipData,DragShadowBuilder,Object,int) * startDragAndDrop()}. - *

- * 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. - *

*

- * 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 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. + *

+ * 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: *

- *

* - * @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}. - *

- * 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. - *

- *

- * 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. - *

- *

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

+ * @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}. + *

+ * 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. + *

+ * 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. + *

+ * 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. * *

- *

Developer Guides

- *

For a guide to implementing drag and drop features, read the - * Drag and Drop developer guide.

+ *

Developer Guides

+ *

For a guide to implementing drag and drop features, see the + * Drag and drop developer guide.

*
*/ 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. Note: A {@code false} return value triggers the + * view's {@link #onDragEvent(DragEvent)} handler. */ boolean onDrag(View v, DragEvent event); }