Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge "Revised the OnDragListener and onDragEvent API documentation." am: 629810015f

Browse Source 
Original change: https://android-review.googlesource.com/c/platform/frameworks/base/+/1907031

Change-Id: I3f3c073dd801654f37244e274c3f6ecbb25c957d
This commit is contained in:
Jon Eckenrode
2021-12-15 16:15:34 +00:00
committed by Automerger Merge Worker
parent 321501ea9d 629810015f
commit b38f3d7744
1 changed files with 42 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files

80
core/java/android/view/View.java
View File

@@ -26843,43 +26843,37 @@ public class View implements Drawable.Callback, KeyEvent.Callback,
* {@link android.view.View#startDragAndDrop(ClipData,DragShadowBuilder,Object,int) * {@link android.view.View#startDragAndDrop(ClipData,DragShadowBuilder,Object,int)
* startDragAndDrop()}. * startDragAndDrop()}.
* <p> * <p>
* When the system calls this method, it passes a * The system calls this method and passes a {@link DragEvent} object in response to drag and
* {@link android.view.DragEvent} object. A call to * drop events. This method can then call {@link DragEvent#getAction()} to determine the state
* {@link android.view.DragEvent#getAction()} returns one of the action type constants defined * of the drag and drop operation.
* in DragEvent. The method uses these to determine what is happening in the drag and drop
* operation.
* </p>
* <p> * <p>
* The default implementation returns false, except if an {@link OnReceiveContentListener} * The default implementation returns {@code false} unless an {@link OnReceiveContentListener}
* is {@link #setOnReceiveContentListener set} for this view. If an * has been set for this view (see {@link #setOnReceiveContentListener}), in which case
* {@link OnReceiveContentListener} is set, the default implementation... * the default implementation does the following:
* <ul> * <ul>
* <li>returns true for an * <li>Returns {@code true} for an
* {@link android.view.DragEvent#ACTION_DRAG_STARTED ACTION_DRAG_STARTED} event * {@link DragEvent#ACTION_DRAG_STARTED ACTION_DRAG_STARTED} event
* <li>calls {@link #performReceiveContent} for an * <li>Calls {@link #performReceiveContent} for an
* {@link android.view.DragEvent#ACTION_DROP ACTION_DROP} event * {@link DragEvent#ACTION_DROP ACTION_DROP} event
* <li>returns true for an {@link android.view.DragEvent#ACTION_DROP ACTION_DROP} event, if * <li>Returns {@code true} for an {@link DragEvent#ACTION_DROP ACTION_DROP} event if the
* the listener consumed some or all of the content * {@code OnReceiveContentListener} consumed some or all of the content
* </ul> * </ul>
* </p>
* *
* @param event The {@link android.view.DragEvent} sent by the system. * @param event The {@link DragEvent} object sent by the system. The
* The {@link android.view.DragEvent#getAction()} method returns an action type constant defined * {@link DragEvent#getAction()} method returns an action type constant that indicates the
* in DragEvent, indicating the type of drag event represented by this object. * type of drag event represented by this object.
* @return {@code true} if the method was successful, otherwise {@code false}. * @return {@code true} if the method successfully handled the drag event, otherwise
* {@code false}.
* <p> * <p>
* The method should return {@code true} in response to an action type of * The method must return {@code true} in response to an
* {@link android.view.DragEvent#ACTION_DRAG_STARTED} to receive drag events for the current * {@link DragEvent#ACTION_DRAG_STARTED ACTION_DRAG_STARTED} action type to continue to
* operation. * receive drag events for the current drag and drop operation.
* </p>
* <p> * <p>
* The method should also return {@code true} in response to an action type of * The method should return {@code true} in response to an
* {@link android.view.DragEvent#ACTION_DROP} if it consumed the drop, or * {@link DragEvent#ACTION_DROP ACTION_DROP} action type if the dropped data was consumed
* {@code false} if it didn't. * (at least partially); {@code false}, if none of the data was consumed.
* </p>
* <p> * <p>
* For all other events, the return value is ignored. * For all other events, the return value is {@code false}.
* </p>
*/ */
public boolean onDragEvent(DragEvent event) { public boolean onDragEvent(DragEvent event) {
if (mListenerInfo == null || mListenerInfo.mOnReceiveContentListener == null) { if (mListenerInfo == null || mListenerInfo.mOnReceiveContentListener == null) {
@@ -28844,27 +28838,27 @@ public class View implements Drawable.Callback, KeyEvent.Callback,
} }
/** /**
* Interface definition for a callback to be invoked when a drag is being dispatched * Interface definition for a listener that's invoked when a drag event is dispatched to this
* to this view. The callback will be invoked before the hosting view's own * view. The listener is invoked before the view's own
* onDrag(event) method. If the listener wants to fall back to the hosting view's * {@link #onDragEvent(DragEvent)} method. To fall back to the view's
* onDrag(event) behavior, it should return 'false' from this callback. * {@code onDragEvent(DragEvent)} behavior, return {@code false} from the listener method.
* *
* <div class="special reference"> * <div class="special reference">
* <h3>Developer Guides</h3> * <h3>Developer Guides</h3>
* <p>For a guide to implementing drag and drop features, read the * <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> * <a href="{@docRoot}guide/topics/ui/drag-drop.html">Drag and drop</a> developer guide.</p>
* </div> * </div>
*/ */
public interface OnDragListener { public interface OnDragListener {
/** /**
* Called when a drag event is dispatched to a view. This allows listeners * Called when a drag event is dispatched to a view. Enables listeners to override the
* to get a chance to override base View behavior. * base behavior provided by {@link #onDragEvent(DragEvent)}.
* *
* @param v The View that received the drag event. * @param v The {@code View} that received the drag event.
* @param event The {@link android.view.DragEvent} object for the drag event. * @param event The event object for the drag event.
* @return {@code true} if the drag event was handled successfully, or {@code false} * @return {@code true} if the drag event was handled successfully; {@code false}, if the
* if the drag event was not handled. Note that {@code false} will trigger the View * drag event was not handled. <b>Note:</b> A {@code false} return value triggers the
* to call its {@link #onDragEvent(DragEvent) onDragEvent()} handler. * view's {@link #onDragEvent(DragEvent)} handler.
*/ */
boolean onDrag(View v, DragEvent event); boolean onDrag(View v, DragEvent event);
} }