Home | History | Annotate | Download | only in selection 
      1 /*
      2  * Copyright 2017 The Android Open Source Project
      3  *
      4  * Licensed under the Apache License, Version 2.0 (the "License");
      5  * you may not use this file except in compliance with the License.
      6  * You may obtain a copy of the License at
      7  *
      8  *      http://www.apache.org/licenses/LICENSE-2.0
      9  *
     10  * Unless required by applicable law or agreed to in writing, software
     11  * distributed under the License is distributed on an "AS IS" BASIS,
     12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     13  * See the License for the specific language governing permissions and
     14  * limitations under the License.
     15  */
     16 
     17 package androidx.recyclerview.selection;
     18 
     19 import static androidx.recyclerview.selection.ItemDetailsLookup.ItemDetails;
     20 
     21 import android.content.ClipData;
     22 import android.view.MotionEvent;
     23 import android.view.View;
     24 
     25 import androidx.annotation.NonNull;
     26 
     27 /**
     28  * Register an OnDragInitiatedListener to be notified when user intent to perform drag and drop
     29  * operations on an item or items has been detected. Handle these events using {@link View}
     30  * support for Drag and drop.
     31  *
     32  * <p>
     33  * See {@link View#startDragAndDrop(ClipData, View.DragShadowBuilder, Object, int)}
     34  * for details.
     35  */
     36 public interface OnDragInitiatedListener {
     37 
     38     /**
     39      * Called when user intent to perform a drag and drop operation has been detected.
     40      *
     41      * <p>
     42      * The following circumstances are considered to be expressing drag and drop intent:
     43      *
     44      * <ol>
     45      *     <li>Long press on selected item.</li>
     46      *     <li>Click and drag in the {@link ItemDetails#inDragRegion(MotionEvent) drag region}
     47      *     of selected item with a pointer device.</li>
     48      *     <li>Click and drag in drag region of un-selected item with a pointer device.</li>
     49      * </ol>
     50      *
     51      * <p>
     52      * The RecyclerView item at the coordinates of the MotionEvent is not supplied as a parameter
     53      * to this method as there may be multiple items selected or no items selected (as may be
     54      * the case in pointer drive drag and drop.)
     55      *
     56      * <p>
     57      * Obtain the current list of selected items from
     58      * {@link SelectionTracker#copySelection(MutableSelection)}. If there is no selection
     59      * get the item under the event using {@link ItemDetailsLookup#getItemDetails(MotionEvent)}.
     60      *
     61      * <p>
     62      * Drag region used with pointer devices is specified by
     63      * {@link ItemDetails#inDragRegion(MotionEvent)}
     64      *
     65      * <p>
     66      * See {@link android.view.View#startDragAndDrop(ClipData, View.DragShadowBuilder, Object, int)}
     67      * for details on drag and drop implementation.
     68      *
     69      * @param e the event associated with the drag.
     70      * @return true if drag and drop was initiated.
     71      */
     72     boolean onDragInitiated(@NonNull MotionEvent e);
     73 }
     74