Christopher Tate | a53146c | 2010-09-07 11:57:52 -0700 | [diff] [blame] | 1 | /* |
| 2 | * Copyright (C) 2010 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 android.view; |
| 18 | |
| 19 | import android.content.ClipData; |
| 20 | import android.content.ClipDescription; |
| 21 | import android.os.Parcel; |
| 22 | import android.os.Parcelable; |
| 23 | |
Vladislav Kaznacheev | 377c328 | 2016-04-20 14:22:23 -0700 | [diff] [blame] | 24 | import com.android.internal.view.IDragAndDropPermissions; |
Vladislav Kaznacheev | 9149d2b | 2015-12-15 12:16:28 -0800 | [diff] [blame] | 25 | |
Joe Malin | 32736f0 | 2011-01-19 16:14:20 -0800 | [diff] [blame] | 26 | //TODO: Improve Javadoc |
| 27 | /** |
| 28 | * Represents an event that is sent out by the system at various times during a drag and drop |
| 29 | * operation. It is a complex data structure that contains several important pieces of data about |
| 30 | * the operation and the underlying data. |
| 31 | * <p> |
| 32 | * View objects that receive a DragEvent call {@link #getAction()}, which returns |
| 33 | * an action type that indicates the state of the drag and drop operation. This allows a View |
| 34 | * object to react to a change in state by changing its appearance or performing other actions. |
| 35 | * For example, a View can react to the {@link #ACTION_DRAG_ENTERED} action type by |
| 36 | * by changing one or more colors in its displayed image. |
| 37 | * </p> |
| 38 | * <p> |
| 39 | * During a drag and drop operation, the system displays an image that the user drags. This image |
| 40 | * is called a drag shadow. Several action types reflect the position of the drag shadow relative |
| 41 | * to the View receiving the event. |
| 42 | * </p> |
| 43 | * <p> |
| 44 | * Most methods return valid data only for certain event actions. This is summarized in the |
| 45 | * following table. Each possible {@link #getAction()} value is listed in the first column. The |
| 46 | * other columns indicate which method or methods return valid data for that getAction() value: |
| 47 | * </p> |
| 48 | * <table> |
| 49 | * <tr> |
| 50 | * <th scope="col">getAction() Value</th> |
| 51 | * <th scope="col">getClipDescription()</th> |
| 52 | * <th scope="col">getLocalState()</th> |
| 53 | * <th scope="col">getX()</th> |
| 54 | * <th scope="col">getY()</th> |
| 55 | * <th scope="col">getClipData()</th> |
| 56 | * <th scope="col">getResult()</th> |
| 57 | * </tr> |
| 58 | * <tr> |
| 59 | * <td>ACTION_DRAG_STARTED</td> |
| 60 | * <td style="text-align: center;">X</td> |
| 61 | * <td style="text-align: center;">X</td> |
| 62 | * <td style="text-align: center;">X</td> |
| 63 | * <td style="text-align: center;">X</td> |
| 64 | * <td style="text-align: center;"> </td> |
| 65 | * <td style="text-align: center;"> </td> |
| 66 | * </tr> |
| 67 | * <tr> |
| 68 | * <td>ACTION_DRAG_ENTERED</td> |
| 69 | * <td style="text-align: center;">X</td> |
| 70 | * <td style="text-align: center;">X</td> |
| 71 | * <td style="text-align: center;"> </td> |
| 72 | * <td style="text-align: center;"> </td> |
| 73 | * <td style="text-align: center;"> </td> |
| 74 | * <td style="text-align: center;"> </td> |
| 75 | * </tr> |
| 76 | * <tr> |
| 77 | * <td>ACTION_DRAG_LOCATION</td> |
| 78 | * <td style="text-align: center;">X</td> |
| 79 | * <td style="text-align: center;">X</td> |
| 80 | * <td style="text-align: center;">X</td> |
| 81 | * <td style="text-align: center;">X</td> |
| 82 | * <td style="text-align: center;"> </td> |
| 83 | * <td style="text-align: center;"> </td> |
| 84 | * </tr> |
| 85 | * <tr> |
| 86 | * <td>ACTION_DRAG_EXITED</td> |
| 87 | * <td style="text-align: center;">X</td> |
| 88 | * <td style="text-align: center;">X</td> |
| 89 | * <td style="text-align: center;"> </td> |
| 90 | * <td style="text-align: center;"> </td> |
| 91 | * <td style="text-align: center;"> </td> |
| 92 | * <td style="text-align: center;"> </td> |
| 93 | * </tr> |
| 94 | * <tr> |
| 95 | * <td>ACTION_DROP</td> |
| 96 | * <td style="text-align: center;">X</td> |
| 97 | * <td style="text-align: center;">X</td> |
| 98 | * <td style="text-align: center;">X</td> |
| 99 | * <td style="text-align: center;">X</td> |
| 100 | * <td style="text-align: center;">X</td> |
| 101 | * <td style="text-align: center;"> </td> |
| 102 | * </tr> |
| 103 | * <tr> |
| 104 | * <td>ACTION_DRAG_ENDED</td> |
Vladislav Kaznacheev | 3067bc6 | 2016-07-11 13:52:22 -0700 | [diff] [blame] | 105 | * <td style="text-align: center;"> </td> |
| 106 | * <td style="text-align: center;"> </td> |
Joe Malin | 32736f0 | 2011-01-19 16:14:20 -0800 | [diff] [blame] | 107 | * <td style="text-align: center;"> </td> |
| 108 | * <td style="text-align: center;"> </td> |
| 109 | * <td style="text-align: center;"> </td> |
| 110 | * <td style="text-align: center;">X</td> |
| 111 | * </tr> |
| 112 | * </table> |
| 113 | * <p> |
| 114 | * The {@link android.view.DragEvent#getAction()}, |
| 115 | * {@link android.view.DragEvent#describeContents()}, |
| 116 | * {@link android.view.DragEvent#writeToParcel(Parcel,int)}, and |
| 117 | * {@link android.view.DragEvent#toString()} methods always return valid data. |
| 118 | * </p> |
Joe Fernandez | 558459f | 2011-10-13 16:47:36 -0700 | [diff] [blame] | 119 | * |
| 120 | * <div class="special reference"> |
| 121 | * <h3>Developer Guides</h3> |
| 122 | * <p>For a guide to implementing drag and drop features, read the |
| 123 | * <a href="{@docRoot}guide/topics/ui/drag-drop.html">Drag and Drop</a> developer guide.</p> |
| 124 | * </div> |
Joe Malin | 32736f0 | 2011-01-19 16:14:20 -0800 | [diff] [blame] | 125 | */ |
Christopher Tate | a53146c | 2010-09-07 11:57:52 -0700 | [diff] [blame] | 126 | public class DragEvent implements Parcelable { |
| 127 | private static final boolean TRACK_RECYCLED_LOCATION = false; |
| 128 | |
| 129 | int mAction; |
| 130 | float mX, mY; |
| 131 | ClipDescription mClipDescription; |
| 132 | ClipData mClipData; |
Vladislav Kaznacheev | 377c328 | 2016-04-20 14:22:23 -0700 | [diff] [blame] | 133 | IDragAndDropPermissions mDragAndDropPermissions; |
Vladislav Kaznacheev | ede5f54 | 2015-07-15 18:04:04 -0700 | [diff] [blame] | 134 | |
Christopher Tate | 407b4e9 | 2010-11-30 17:14:08 -0800 | [diff] [blame] | 135 | Object mLocalState; |
Chris Tate | d4533f1 | 2010-10-19 15:15:08 -0700 | [diff] [blame] | 136 | boolean mDragResult; |
Christopher Tate | a53146c | 2010-09-07 11:57:52 -0700 | [diff] [blame] | 137 | |
| 138 | private DragEvent mNext; |
| 139 | private RuntimeException mRecycledLocation; |
| 140 | private boolean mRecycled; |
| 141 | |
| 142 | private static final int MAX_RECYCLED = 10; |
| 143 | private static final Object gRecyclerLock = new Object(); |
| 144 | private static int gRecyclerUsed = 0; |
| 145 | private static DragEvent gRecyclerTop = null; |
| 146 | |
| 147 | /** |
Joe Malin | 32736f0 | 2011-01-19 16:14:20 -0800 | [diff] [blame] | 148 | * Action constant returned by {@link #getAction()}: Signals the start of a |
| 149 | * drag and drop operation. The View should return {@code true} from its |
| 150 | * {@link View#onDragEvent(DragEvent) onDragEvent()} handler method or |
Vladislav Kaznacheev | 9149d2b | 2015-12-15 12:16:28 -0800 | [diff] [blame] | 151 | * {@link View.OnDragListener#onDrag(View,DragEvent) OnDragListener.onDrag()} listener |
Joe Malin | 32736f0 | 2011-01-19 16:14:20 -0800 | [diff] [blame] | 152 | * if it can accept a drop. The onDragEvent() or onDrag() methods usually inspect the metadata |
| 153 | * from {@link #getClipDescription()} to determine if they can accept the data contained in |
| 154 | * this drag. For an operation that doesn't represent data transfer, these methods may |
| 155 | * perform other actions to determine whether or not the View should accept the drag. |
| 156 | * If the View wants to indicate that it is a valid drop target, it can also react by |
| 157 | * changing its appearance. |
Christopher Tate | 855e4c9 | 2010-11-19 14:55:12 -0800 | [diff] [blame] | 158 | * <p> |
Joe Malin | 32736f0 | 2011-01-19 16:14:20 -0800 | [diff] [blame] | 159 | * A View only receives further drag events if it returns {@code true} in response to |
| 160 | * ACTION_DRAG_STARTED. |
| 161 | * </p> |
| 162 | * @see #ACTION_DRAG_ENDED |
Vladislav Kaznacheev | c244970 | 2016-05-16 12:57:15 -0700 | [diff] [blame] | 163 | * @see #getX() |
| 164 | * @see #getY() |
Christopher Tate | a53146c | 2010-09-07 11:57:52 -0700 | [diff] [blame] | 165 | */ |
| 166 | public static final int ACTION_DRAG_STARTED = 1; |
Christopher Tate | a53146c | 2010-09-07 11:57:52 -0700 | [diff] [blame] | 167 | |
Christopher Tate | 855e4c9 | 2010-11-19 14:55:12 -0800 | [diff] [blame] | 168 | /** |
Joe Malin | 32736f0 | 2011-01-19 16:14:20 -0800 | [diff] [blame] | 169 | * Action constant returned by {@link #getAction()}: Sent to a View after |
| 170 | * {@link #ACTION_DRAG_ENTERED} if the drag shadow is still within the View object's bounding |
| 171 | * box. The {@link #getX()} and {@link #getY()} methods supply |
| 172 | * the X and Y position of of the drag point within the View object's bounding box. |
Christopher Tate | 855e4c9 | 2010-11-19 14:55:12 -0800 | [diff] [blame] | 173 | * <p> |
Joe Malin | 32736f0 | 2011-01-19 16:14:20 -0800 | [diff] [blame] | 174 | * A View receives an {@link #ACTION_DRAG_ENTERED} event before receiving any |
| 175 | * ACTION_DRAG_LOCATION events. |
| 176 | * </p> |
| 177 | * <p> |
| 178 | * The system stops sending ACTION_DRAG_LOCATION events to a View once the user moves the |
| 179 | * drag shadow out of the View object's bounding box. If the user moves the drag shadow back |
| 180 | * into the View object's bounding box, the View receives an ACTION_DRAG_ENTERED again before |
| 181 | * receiving any more ACTION_DRAG_LOCATION events. |
| 182 | * </p> |
| 183 | * @see #ACTION_DRAG_ENTERED |
| 184 | * @see #getX() |
| 185 | * @see #getY() |
Christopher Tate | 855e4c9 | 2010-11-19 14:55:12 -0800 | [diff] [blame] | 186 | */ |
| 187 | public static final int ACTION_DRAG_LOCATION = 2; |
| 188 | |
| 189 | /** |
Joe Malin | 32736f0 | 2011-01-19 16:14:20 -0800 | [diff] [blame] | 190 | * Action constant returned by {@link #getAction()}: Signals to a View that the user |
| 191 | * has released the drag shadow, and the drag point is within the bounding box of the View. |
| 192 | * The View should retrieve the data from the DragEvent by calling {@link #getClipData()}. |
| 193 | * The methods {@link #getX()} and {@link #getY()} return the X and Y position of the drop point |
| 194 | * within the View object's bounding box. |
Christopher Tate | 855e4c9 | 2010-11-19 14:55:12 -0800 | [diff] [blame] | 195 | * <p> |
Joe Malin | 32736f0 | 2011-01-19 16:14:20 -0800 | [diff] [blame] | 196 | * The View should return {@code true} from its {@link View#onDragEvent(DragEvent)} |
Vladislav Kaznacheev | 9149d2b | 2015-12-15 12:16:28 -0800 | [diff] [blame] | 197 | * handler or {@link View.OnDragListener#onDrag(View,DragEvent) OnDragListener.onDrag()} |
Joe Malin | 32736f0 | 2011-01-19 16:14:20 -0800 | [diff] [blame] | 198 | * listener if it accepted the drop, and {@code false} if it ignored the drop. |
| 199 | * </p> |
| 200 | * <p> |
| 201 | * The View can also react to this action by changing its appearance. |
| 202 | * </p> |
| 203 | * @see #getClipData() |
| 204 | * @see #getX() |
| 205 | * @see #getY() |
Christopher Tate | 855e4c9 | 2010-11-19 14:55:12 -0800 | [diff] [blame] | 206 | */ |
| 207 | public static final int ACTION_DROP = 3; |
| 208 | |
| 209 | /** |
Joe Malin | 32736f0 | 2011-01-19 16:14:20 -0800 | [diff] [blame] | 210 | * Action constant returned by {@link #getAction()}: Signals to a View that the drag and drop |
| 211 | * operation has concluded. A View that changed its appearance during the operation should |
| 212 | * return to its usual drawing state in response to this event. |
Christopher Tate | 855e4c9 | 2010-11-19 14:55:12 -0800 | [diff] [blame] | 213 | * <p> |
| 214 | * All views that received an ACTION_DRAG_STARTED event will receive the |
Joe Malin | 32736f0 | 2011-01-19 16:14:20 -0800 | [diff] [blame] | 215 | * ACTION_DRAG_ENDED event even if they are not currently visible when the drag ends. |
| 216 | * </p> |
| 217 | * <p> |
| 218 | * The View object can call {@link #getResult()} to see the result of the operation. |
| 219 | * If a View returned {@code true} in response to {@link #ACTION_DROP}, then |
| 220 | * getResult() returns {@code true}, otherwise it returns {@code false}. |
| 221 | * </p> |
| 222 | * @see #ACTION_DRAG_STARTED |
| 223 | * @see #getResult() |
Christopher Tate | 855e4c9 | 2010-11-19 14:55:12 -0800 | [diff] [blame] | 224 | */ |
| 225 | public static final int ACTION_DRAG_ENDED = 4; |
| 226 | |
| 227 | /** |
Joe Malin | 32736f0 | 2011-01-19 16:14:20 -0800 | [diff] [blame] | 228 | * Action constant returned by {@link #getAction()}: Signals to a View that the drag point has |
| 229 | * entered the bounding box of the View. |
Christopher Tate | 855e4c9 | 2010-11-19 14:55:12 -0800 | [diff] [blame] | 230 | * <p> |
Joe Malin | 32736f0 | 2011-01-19 16:14:20 -0800 | [diff] [blame] | 231 | * If the View can accept a drop, it can react to ACTION_DRAG_ENTERED |
| 232 | * by changing its appearance in a way that tells the user that the View is the current |
| 233 | * drop target. |
| 234 | * </p> |
| 235 | * The system stops sending ACTION_DRAG_LOCATION events to a View once the user moves the |
| 236 | * drag shadow out of the View object's bounding box. If the user moves the drag shadow back |
| 237 | * into the View object's bounding box, the View receives an ACTION_DRAG_ENTERED again before |
| 238 | * receiving any more ACTION_DRAG_LOCATION events. |
| 239 | * </p> |
| 240 | * @see #ACTION_DRAG_ENTERED |
| 241 | * @see #ACTION_DRAG_LOCATION |
Christopher Tate | 855e4c9 | 2010-11-19 14:55:12 -0800 | [diff] [blame] | 242 | */ |
| 243 | public static final int ACTION_DRAG_ENTERED = 5; |
| 244 | |
| 245 | /** |
Joe Malin | 32736f0 | 2011-01-19 16:14:20 -0800 | [diff] [blame] | 246 | * Action constant returned by {@link #getAction()}: Signals that the user has moved the |
| 247 | * drag shadow outside the bounding box of the View. |
| 248 | * The View can react by changing its appearance in a way that tells the user that |
| 249 | * View is no longer the immediate drop target. |
Christopher Tate | 855e4c9 | 2010-11-19 14:55:12 -0800 | [diff] [blame] | 250 | * <p> |
Joe Malin | 32736f0 | 2011-01-19 16:14:20 -0800 | [diff] [blame] | 251 | * After the system sends an ACTION_DRAG_EXITED event to the View, the View receives no more |
| 252 | * ACTION_DRAG_LOCATION events until the user drags the drag shadow back over the View. |
| 253 | * </p> |
| 254 | * |
Christopher Tate | 855e4c9 | 2010-11-19 14:55:12 -0800 | [diff] [blame] | 255 | */ |
Joe Malin | 32736f0 | 2011-01-19 16:14:20 -0800 | [diff] [blame] | 256 | public static final int ACTION_DRAG_EXITED = 6; |
Christopher Tate | 855e4c9 | 2010-11-19 14:55:12 -0800 | [diff] [blame] | 257 | |
Christopher Tate | 2c095f3 | 2010-10-04 14:13:40 -0700 | [diff] [blame] | 258 | private DragEvent() { |
Christopher Tate | a53146c | 2010-09-07 11:57:52 -0700 | [diff] [blame] | 259 | } |
| 260 | |
Chris Tate | d4533f1 | 2010-10-19 15:15:08 -0700 | [diff] [blame] | 261 | private void init(int action, float x, float y, ClipDescription description, ClipData data, |
Vladislav Kaznacheev | 377c328 | 2016-04-20 14:22:23 -0700 | [diff] [blame] | 262 | IDragAndDropPermissions dragAndDropPermissions, Object localState, boolean result) { |
Chris Tate | c02c7af | 2010-10-20 18:55:13 -0700 | [diff] [blame] | 263 | mAction = action; |
| 264 | mX = x; |
| 265 | mY = y; |
| 266 | mClipDescription = description; |
| 267 | mClipData = data; |
Vladislav Kaznacheev | 377c328 | 2016-04-20 14:22:23 -0700 | [diff] [blame] | 268 | this.mDragAndDropPermissions = dragAndDropPermissions; |
Christopher Tate | 7fb8b56 | 2011-01-20 13:46:41 -0800 | [diff] [blame] | 269 | mLocalState = localState; |
Chris Tate | d4533f1 | 2010-10-19 15:15:08 -0700 | [diff] [blame] | 270 | mDragResult = result; |
Chris Tate | c02c7af | 2010-10-20 18:55:13 -0700 | [diff] [blame] | 271 | } |
| 272 | |
Christopher Tate | 2c095f3 | 2010-10-04 14:13:40 -0700 | [diff] [blame] | 273 | static DragEvent obtain() { |
Vladislav Kaznacheev | ede5f54 | 2015-07-15 18:04:04 -0700 | [diff] [blame] | 274 | return DragEvent.obtain(0, 0f, 0f, null, null, null, null, false); |
Christopher Tate | a53146c | 2010-09-07 11:57:52 -0700 | [diff] [blame] | 275 | } |
| 276 | |
Christopher Tate | 855e4c9 | 2010-11-19 14:55:12 -0800 | [diff] [blame] | 277 | /** @hide */ |
Christopher Tate | 407b4e9 | 2010-11-30 17:14:08 -0800 | [diff] [blame] | 278 | public static DragEvent obtain(int action, float x, float y, Object localState, |
Vladislav Kaznacheev | 377c328 | 2016-04-20 14:22:23 -0700 | [diff] [blame] | 279 | ClipDescription description, ClipData data, |
| 280 | IDragAndDropPermissions dragAndDropPermissions, boolean result) { |
Christopher Tate | a53146c | 2010-09-07 11:57:52 -0700 | [diff] [blame] | 281 | final DragEvent ev; |
| 282 | synchronized (gRecyclerLock) { |
| 283 | if (gRecyclerTop == null) { |
Chris Tate | c02c7af | 2010-10-20 18:55:13 -0700 | [diff] [blame] | 284 | ev = new DragEvent(); |
Vladislav Kaznacheev | 377c328 | 2016-04-20 14:22:23 -0700 | [diff] [blame] | 285 | ev.init(action, x, y, description, data, dragAndDropPermissions, localState, |
| 286 | result); |
Chris Tate | c02c7af | 2010-10-20 18:55:13 -0700 | [diff] [blame] | 287 | return ev; |
Christopher Tate | a53146c | 2010-09-07 11:57:52 -0700 | [diff] [blame] | 288 | } |
| 289 | ev = gRecyclerTop; |
| 290 | gRecyclerTop = ev.mNext; |
| 291 | gRecyclerUsed -= 1; |
| 292 | } |
| 293 | ev.mRecycledLocation = null; |
| 294 | ev.mRecycled = false; |
| 295 | ev.mNext = null; |
| 296 | |
Vladislav Kaznacheev | 377c328 | 2016-04-20 14:22:23 -0700 | [diff] [blame] | 297 | ev.init(action, x, y, description, data, dragAndDropPermissions, localState, result); |
Christopher Tate | a53146c | 2010-09-07 11:57:52 -0700 | [diff] [blame] | 298 | |
| 299 | return ev; |
| 300 | } |
| 301 | |
Christopher Tate | 855e4c9 | 2010-11-19 14:55:12 -0800 | [diff] [blame] | 302 | /** @hide */ |
Christopher Tate | 2c095f3 | 2010-10-04 14:13:40 -0700 | [diff] [blame] | 303 | public static DragEvent obtain(DragEvent source) { |
Christopher Tate | 407b4e9 | 2010-11-30 17:14:08 -0800 | [diff] [blame] | 304 | return obtain(source.mAction, source.mX, source.mY, source.mLocalState, |
Vladislav Kaznacheev | 377c328 | 2016-04-20 14:22:23 -0700 | [diff] [blame] | 305 | source.mClipDescription, source.mClipData, source.mDragAndDropPermissions, |
Vladislav Kaznacheev | ede5f54 | 2015-07-15 18:04:04 -0700 | [diff] [blame] | 306 | source.mDragResult); |
Christopher Tate | 2c095f3 | 2010-10-04 14:13:40 -0700 | [diff] [blame] | 307 | } |
| 308 | |
Christopher Tate | 855e4c9 | 2010-11-19 14:55:12 -0800 | [diff] [blame] | 309 | /** |
| 310 | * Inspect the action value of this event. |
Joe Malin | 32736f0 | 2011-01-19 16:14:20 -0800 | [diff] [blame] | 311 | * @return One of the following action constants, in the order in which they usually occur |
| 312 | * during a drag and drop operation: |
| 313 | * <ul> |
| 314 | * <li>{@link #ACTION_DRAG_STARTED}</li> |
| 315 | * <li>{@link #ACTION_DRAG_ENTERED}</li> |
| 316 | * <li>{@link #ACTION_DRAG_LOCATION}</li> |
| 317 | * <li>{@link #ACTION_DROP}</li> |
| 318 | * <li>{@link #ACTION_DRAG_EXITED}</li> |
| 319 | * <li>{@link #ACTION_DRAG_ENDED}</li> |
| 320 | * </ul> |
Christopher Tate | 855e4c9 | 2010-11-19 14:55:12 -0800 | [diff] [blame] | 321 | */ |
Christopher Tate | a53146c | 2010-09-07 11:57:52 -0700 | [diff] [blame] | 322 | public int getAction() { |
| 323 | return mAction; |
| 324 | } |
| 325 | |
Christopher Tate | 855e4c9 | 2010-11-19 14:55:12 -0800 | [diff] [blame] | 326 | /** |
Joe Malin | 32736f0 | 2011-01-19 16:14:20 -0800 | [diff] [blame] | 327 | * Gets the X coordinate of the drag point. The value is only valid if the event action is |
Vladislav Kaznacheev | c244970 | 2016-05-16 12:57:15 -0700 | [diff] [blame] | 328 | * {@link #ACTION_DRAG_STARTED}, {@link #ACTION_DRAG_LOCATION} or {@link #ACTION_DROP}. |
| 329 | * @return The current drag point's X coordinate |
Christopher Tate | 855e4c9 | 2010-11-19 14:55:12 -0800 | [diff] [blame] | 330 | */ |
Christopher Tate | a53146c | 2010-09-07 11:57:52 -0700 | [diff] [blame] | 331 | public float getX() { |
| 332 | return mX; |
| 333 | } |
| 334 | |
Christopher Tate | 855e4c9 | 2010-11-19 14:55:12 -0800 | [diff] [blame] | 335 | /** |
Vladislav Kaznacheev | c244970 | 2016-05-16 12:57:15 -0700 | [diff] [blame] | 336 | * Gets the Y coordinate of the drag point. The value is only valid if the event action is |
| 337 | * {@link #ACTION_DRAG_STARTED}, {@link #ACTION_DRAG_LOCATION} or {@link #ACTION_DROP}. |
Joe Malin | 32736f0 | 2011-01-19 16:14:20 -0800 | [diff] [blame] | 338 | * @return The current drag point's Y coordinate |
Christopher Tate | 855e4c9 | 2010-11-19 14:55:12 -0800 | [diff] [blame] | 339 | */ |
Christopher Tate | a53146c | 2010-09-07 11:57:52 -0700 | [diff] [blame] | 340 | public float getY() { |
| 341 | return mY; |
| 342 | } |
| 343 | |
Christopher Tate | 855e4c9 | 2010-11-19 14:55:12 -0800 | [diff] [blame] | 344 | /** |
Joe Malin | 32736f0 | 2011-01-19 16:14:20 -0800 | [diff] [blame] | 345 | * Returns the {@link android.content.ClipData} object sent to the system as part of the call |
| 346 | * to |
| 347 | * {@link android.view.View#startDrag(ClipData,View.DragShadowBuilder,Object,int) startDrag()}. |
| 348 | * This method only returns valid data if the event action is {@link #ACTION_DROP}. |
| 349 | * @return The ClipData sent to the system by startDrag(). |
Christopher Tate | 855e4c9 | 2010-11-19 14:55:12 -0800 | [diff] [blame] | 350 | */ |
Christopher Tate | a53146c | 2010-09-07 11:57:52 -0700 | [diff] [blame] | 351 | public ClipData getClipData() { |
| 352 | return mClipData; |
| 353 | } |
| 354 | |
Christopher Tate | 855e4c9 | 2010-11-19 14:55:12 -0800 | [diff] [blame] | 355 | /** |
Joe Malin | 32736f0 | 2011-01-19 16:14:20 -0800 | [diff] [blame] | 356 | * Returns the {@link android.content.ClipDescription} object contained in the |
| 357 | * {@link android.content.ClipData} object sent to the system as part of the call to |
| 358 | * {@link android.view.View#startDrag(ClipData,View.DragShadowBuilder,Object,int) startDrag()}. |
| 359 | * The drag handler or listener for a View can use the metadata in this object to decide if the |
| 360 | * View can accept the dragged View object's data. |
| 361 | * <p> |
Vladislav Kaznacheev | 3067bc6 | 2016-07-11 13:52:22 -0700 | [diff] [blame] | 362 | * This method returns valid data for all event actions except for {@link #ACTION_DRAG_ENDED}. |
Joe Malin | 32736f0 | 2011-01-19 16:14:20 -0800 | [diff] [blame] | 363 | * @return The ClipDescription that was part of the ClipData sent to the system by startDrag(). |
Christopher Tate | 855e4c9 | 2010-11-19 14:55:12 -0800 | [diff] [blame] | 364 | */ |
Christopher Tate | a53146c | 2010-09-07 11:57:52 -0700 | [diff] [blame] | 365 | public ClipDescription getClipDescription() { |
| 366 | return mClipDescription; |
| 367 | } |
| 368 | |
Vladislav Kaznacheev | b23a757 | 2015-12-18 12:23:43 -0800 | [diff] [blame] | 369 | /** @hide */ |
Vladislav Kaznacheev | 377c328 | 2016-04-20 14:22:23 -0700 | [diff] [blame] | 370 | public IDragAndDropPermissions getDragAndDropPermissions() { |
| 371 | return mDragAndDropPermissions; |
Vladislav Kaznacheev | ede5f54 | 2015-07-15 18:04:04 -0700 | [diff] [blame] | 372 | } |
| 373 | |
| 374 | /** |
Joe Malin | 32736f0 | 2011-01-19 16:14:20 -0800 | [diff] [blame] | 375 | * Returns the local state object sent to the system as part of the call to |
| 376 | * {@link android.view.View#startDrag(ClipData,View.DragShadowBuilder,Object,int) startDrag()}. |
| 377 | * The object is intended to provide local information about the drag and drop operation. For |
| 378 | * example, it can indicate whether the drag and drop operation is a copy or a move. |
| 379 | * <p> |
Vladislav Kaznacheev | 048f3bf | 2016-09-08 16:37:23 -0700 | [diff] [blame] | 380 | * The local state is available only to views in the activity which has started the drag |
| 381 | * operation. In all other activities this method will return null |
| 382 | * </p> |
| 383 | * <p> |
Vladislav Kaznacheev | 3067bc6 | 2016-07-11 13:52:22 -0700 | [diff] [blame] | 384 | * This method returns valid data for all event actions except for {@link #ACTION_DRAG_ENDED}. |
Joe Malin | 32736f0 | 2011-01-19 16:14:20 -0800 | [diff] [blame] | 385 | * </p> |
| 386 | * @return The local state object sent to the system by startDrag(). |
Christopher Tate | 407b4e9 | 2010-11-30 17:14:08 -0800 | [diff] [blame] | 387 | */ |
| 388 | public Object getLocalState() { |
| 389 | return mLocalState; |
| 390 | } |
| 391 | |
| 392 | /** |
Joe Malin | 32736f0 | 2011-01-19 16:14:20 -0800 | [diff] [blame] | 393 | * <p> |
| 394 | * Returns an indication of the result of the drag and drop operation. |
| 395 | * This method only returns valid data if the action type is {@link #ACTION_DRAG_ENDED}. |
| 396 | * The return value depends on what happens after the user releases the drag shadow. |
| 397 | * </p> |
| 398 | * <p> |
| 399 | * If the user releases the drag shadow on a View that can accept a drop, the system sends an |
| 400 | * {@link #ACTION_DROP} event to the View object's drag event listener. If the listener |
| 401 | * returns {@code true}, then getResult() will return {@code true}. |
| 402 | * If the listener returns {@code false}, then getResult() returns {@code false}. |
| 403 | * </p> |
| 404 | * <p> |
| 405 | * Notice that getResult() also returns {@code false} if no {@link #ACTION_DROP} is sent. This |
| 406 | * happens, for example, when the user releases the drag shadow over an area outside of the |
| 407 | * application. In this case, the system sends out {@link #ACTION_DRAG_ENDED} for the current |
| 408 | * operation, but never sends out {@link #ACTION_DROP}. |
| 409 | * </p> |
| 410 | * @return {@code true} if a drag event listener returned {@code true} in response to |
| 411 | * {@link #ACTION_DROP}. If the system did not send {@link #ACTION_DROP} before |
| 412 | * {@link #ACTION_DRAG_ENDED}, or if the listener returned {@code false} in response to |
| 413 | * {@link #ACTION_DROP}, then {@code false} is returned. |
Christopher Tate | 855e4c9 | 2010-11-19 14:55:12 -0800 | [diff] [blame] | 414 | */ |
Chris Tate | d4533f1 | 2010-10-19 15:15:08 -0700 | [diff] [blame] | 415 | public boolean getResult() { |
| 416 | return mDragResult; |
| 417 | } |
| 418 | |
Christopher Tate | a53146c | 2010-09-07 11:57:52 -0700 | [diff] [blame] | 419 | /** |
| 420 | * Recycle the DragEvent, to be re-used by a later caller. After calling |
| 421 | * this function you must never touch the event again. |
Christopher Tate | 855e4c9 | 2010-11-19 14:55:12 -0800 | [diff] [blame] | 422 | * |
| 423 | * @hide |
Christopher Tate | a53146c | 2010-09-07 11:57:52 -0700 | [diff] [blame] | 424 | */ |
| 425 | public final void recycle() { |
| 426 | // Ensure recycle is only called once! |
| 427 | if (TRACK_RECYCLED_LOCATION) { |
| 428 | if (mRecycledLocation != null) { |
| 429 | throw new RuntimeException(toString() + " recycled twice!", mRecycledLocation); |
| 430 | } |
| 431 | mRecycledLocation = new RuntimeException("Last recycled here"); |
| 432 | } else { |
| 433 | if (mRecycled) { |
| 434 | throw new RuntimeException(toString() + " recycled twice!"); |
| 435 | } |
| 436 | mRecycled = true; |
| 437 | } |
| 438 | |
| 439 | mClipData = null; |
| 440 | mClipDescription = null; |
Christopher Tate | 407b4e9 | 2010-11-30 17:14:08 -0800 | [diff] [blame] | 441 | mLocalState = null; |
Christopher Tate | a53146c | 2010-09-07 11:57:52 -0700 | [diff] [blame] | 442 | |
| 443 | synchronized (gRecyclerLock) { |
| 444 | if (gRecyclerUsed < MAX_RECYCLED) { |
| 445 | gRecyclerUsed++; |
| 446 | mNext = gRecyclerTop; |
| 447 | gRecyclerTop = this; |
| 448 | } |
| 449 | } |
| 450 | } |
| 451 | |
Joe Malin | 32736f0 | 2011-01-19 16:14:20 -0800 | [diff] [blame] | 452 | /** |
| 453 | * Returns a string containing a concise, human-readable representation of this DragEvent |
| 454 | * object. |
| 455 | * @return A string representation of the DragEvent object. |
| 456 | */ |
Christopher Tate | a53146c | 2010-09-07 11:57:52 -0700 | [diff] [blame] | 457 | @Override |
| 458 | public String toString() { |
| 459 | return "DragEvent{" + Integer.toHexString(System.identityHashCode(this)) |
| 460 | + " action=" + mAction + " @ (" + mX + ", " + mY + ") desc=" + mClipDescription |
Christopher Tate | f01af75 | 2011-01-19 16:22:07 -0800 | [diff] [blame] | 461 | + " data=" + mClipData + " local=" + mLocalState + " result=" + mDragResult |
Christopher Tate | a53146c | 2010-09-07 11:57:52 -0700 | [diff] [blame] | 462 | + "}"; |
| 463 | } |
| 464 | |
| 465 | /* Parcelable interface */ |
| 466 | |
Joe Malin | 32736f0 | 2011-01-19 16:14:20 -0800 | [diff] [blame] | 467 | /** |
| 468 | * Returns information about the {@link android.os.Parcel} representation of this DragEvent |
| 469 | * object. |
| 470 | * @return Information about the {@link android.os.Parcel} representation. |
| 471 | */ |
Christopher Tate | a53146c | 2010-09-07 11:57:52 -0700 | [diff] [blame] | 472 | public int describeContents() { |
| 473 | return 0; |
| 474 | } |
| 475 | |
Joe Malin | 32736f0 | 2011-01-19 16:14:20 -0800 | [diff] [blame] | 476 | /** |
| 477 | * Creates a {@link android.os.Parcel} object from this DragEvent object. |
| 478 | * @param dest A {@link android.os.Parcel} object in which to put the DragEvent object. |
| 479 | * @param flags Flags to store in the Parcel. |
| 480 | */ |
Christopher Tate | a53146c | 2010-09-07 11:57:52 -0700 | [diff] [blame] | 481 | public void writeToParcel(Parcel dest, int flags) { |
| 482 | dest.writeInt(mAction); |
| 483 | dest.writeFloat(mX); |
| 484 | dest.writeFloat(mY); |
Chris Tate | d4533f1 | 2010-10-19 15:15:08 -0700 | [diff] [blame] | 485 | dest.writeInt(mDragResult ? 1 : 0); |
Christopher Tate | a53146c | 2010-09-07 11:57:52 -0700 | [diff] [blame] | 486 | if (mClipData == null) { |
| 487 | dest.writeInt(0); |
| 488 | } else { |
| 489 | dest.writeInt(1); |
| 490 | mClipData.writeToParcel(dest, flags); |
| 491 | } |
| 492 | if (mClipDescription == null) { |
| 493 | dest.writeInt(0); |
| 494 | } else { |
| 495 | dest.writeInt(1); |
| 496 | mClipDescription.writeToParcel(dest, flags); |
| 497 | } |
Vladislav Kaznacheev | 377c328 | 2016-04-20 14:22:23 -0700 | [diff] [blame] | 498 | if (mDragAndDropPermissions == null) { |
Vladislav Kaznacheev | ede5f54 | 2015-07-15 18:04:04 -0700 | [diff] [blame] | 499 | dest.writeInt(0); |
| 500 | } else { |
| 501 | dest.writeInt(1); |
Vladislav Kaznacheev | 377c328 | 2016-04-20 14:22:23 -0700 | [diff] [blame] | 502 | dest.writeStrongBinder(mDragAndDropPermissions.asBinder()); |
Vladislav Kaznacheev | ede5f54 | 2015-07-15 18:04:04 -0700 | [diff] [blame] | 503 | } |
Christopher Tate | a53146c | 2010-09-07 11:57:52 -0700 | [diff] [blame] | 504 | } |
| 505 | |
Joe Malin | 32736f0 | 2011-01-19 16:14:20 -0800 | [diff] [blame] | 506 | /** |
| 507 | * A container for creating a DragEvent from a Parcel. |
| 508 | */ |
Christopher Tate | a53146c | 2010-09-07 11:57:52 -0700 | [diff] [blame] | 509 | public static final Parcelable.Creator<DragEvent> CREATOR = |
| 510 | new Parcelable.Creator<DragEvent>() { |
| 511 | public DragEvent createFromParcel(Parcel in) { |
| 512 | DragEvent event = DragEvent.obtain(); |
| 513 | event.mAction = in.readInt(); |
| 514 | event.mX = in.readFloat(); |
| 515 | event.mY = in.readFloat(); |
Chris Tate | d4533f1 | 2010-10-19 15:15:08 -0700 | [diff] [blame] | 516 | event.mDragResult = (in.readInt() != 0); |
Christopher Tate | a53146c | 2010-09-07 11:57:52 -0700 | [diff] [blame] | 517 | if (in.readInt() != 0) { |
| 518 | event.mClipData = ClipData.CREATOR.createFromParcel(in); |
| 519 | } |
| 520 | if (in.readInt() != 0) { |
| 521 | event.mClipDescription = ClipDescription.CREATOR.createFromParcel(in); |
| 522 | } |
Vladislav Kaznacheev | ede5f54 | 2015-07-15 18:04:04 -0700 | [diff] [blame] | 523 | if (in.readInt() != 0) { |
Vladislav Kaznacheev | 377c328 | 2016-04-20 14:22:23 -0700 | [diff] [blame] | 524 | event.mDragAndDropPermissions = |
| 525 | IDragAndDropPermissions.Stub.asInterface(in.readStrongBinder());; |
Vladislav Kaznacheev | ede5f54 | 2015-07-15 18:04:04 -0700 | [diff] [blame] | 526 | } |
Christopher Tate | a53146c | 2010-09-07 11:57:52 -0700 | [diff] [blame] | 527 | return event; |
| 528 | } |
| 529 | |
| 530 | public DragEvent[] newArray(int size) { |
| 531 | return new DragEvent[size]; |
| 532 | } |
| 533 | }; |
| 534 | } |