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 24 import com.android.internal.view.IDragAndDropPermissions; 25 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 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> 105 * <td style="text-align: center;"> </td> 106 * <td style="text-align: center;"> </td> 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> 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> 125 */ 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; 133 IDragAndDropPermissions mDragAndDropPermissions; 134 135 Object mLocalState; 136 boolean mDragResult; 137 boolean mEventHandlerWasCalled; 138 139 private DragEvent mNext; 140 private RuntimeException mRecycledLocation; 141 private boolean mRecycled; 142 143 private static final int MAX_RECYCLED = 10; 144 private static final Object gRecyclerLock = new Object(); 145 private static int gRecyclerUsed = 0; 146 private static DragEvent gRecyclerTop = null; 147 148 /** 149 * Action constant returned by {@link #getAction()}: Signals the start of a 150 * drag and drop operation. The View should return {@code true} from its 151 * {@link View#onDragEvent(DragEvent) onDragEvent()} handler method or 152 * {@link View.OnDragListener#onDrag(View,DragEvent) OnDragListener.onDrag()} listener 153 * if it can accept a drop. The onDragEvent() or onDrag() methods usually inspect the metadata 154 * from {@link #getClipDescription()} to determine if they can accept the data contained in 155 * this drag. For an operation that doesn't represent data transfer, these methods may 156 * perform other actions to determine whether or not the View should accept the data. 157 * If the View wants to indicate that it is a valid drop target, it can also react by 158 * changing its appearance. 159 * <p> 160 * Views added or becoming visible for the first time during a drag operation receive this 161 * event when they are added or becoming visible. 162 * </p> 163 * <p> 164 * A View only receives further drag events for the drag operation if it returns {@code true} 165 * in response to ACTION_DRAG_STARTED. 166 * </p> 167 * @see #ACTION_DRAG_ENDED 168 * @see #getX() 169 * @see #getY() 170 */ 171 public static final int ACTION_DRAG_STARTED = 1; 172 173 /** 174 * Action constant returned by {@link #getAction()}: Sent to a View after 175 * {@link #ACTION_DRAG_ENTERED} while the drag shadow is still within the View object's bounding 176 * box, but not within a descendant view that can accept the data. The {@link #getX()} and 177 * {@link #getY()} methods supply 178 * the X and Y position of of the drag point within the View object's bounding box. 179 * <p> 180 * A View receives an {@link #ACTION_DRAG_ENTERED} event before receiving any 181 * ACTION_DRAG_LOCATION events. 182 * </p> 183 * <p> 184 * The system stops sending ACTION_DRAG_LOCATION events to a View once the user moves the 185 * drag shadow out of the View object's bounding box or into a descendant view that can accept 186 * the data. If the user moves the drag shadow back into the View object's bounding box or out 187 * of a descendant view that can accept the data, the View receives an ACTION_DRAG_ENTERED again 188 * before receiving any more ACTION_DRAG_LOCATION events. 189 * </p> 190 * @see #ACTION_DRAG_ENTERED 191 * @see #getX() 192 * @see #getY() 193 */ 194 public static final int ACTION_DRAG_LOCATION = 2; 195 196 /** 197 * Action constant returned by {@link #getAction()}: Signals to a View that the user 198 * has released the drag shadow, and the drag point is within the bounding box of the View and 199 * not within a descendant view that can accept the data. 200 * The View should retrieve the data from the DragEvent by calling {@link #getClipData()}. 201 * The methods {@link #getX()} and {@link #getY()} return the X and Y position of the drop point 202 * within the View object's bounding box. 203 * <p> 204 * The View should return {@code true} from its {@link View#onDragEvent(DragEvent)} 205 * handler or {@link View.OnDragListener#onDrag(View,DragEvent) OnDragListener.onDrag()} 206 * listener if it accepted the drop, and {@code false} if it ignored the drop. 207 * </p> 208 * <p> 209 * The View can also react to this action by changing its appearance. 210 * </p> 211 * @see #getClipData() 212 * @see #getX() 213 * @see #getY() 214 */ 215 public static final int ACTION_DROP = 3; 216 217 /** 218 * Action constant returned by {@link #getAction()}: Signals to a View that the drag and drop 219 * operation has concluded. A View that changed its appearance during the operation should 220 * return to its usual drawing state in response to this event. 221 * <p> 222 * All views with listeners that returned boolean <code>true</code> for the ACTION_DRAG_STARTED 223 * event will receive the ACTION_DRAG_ENDED event even if they are not currently visible when 224 * the drag ends. Views removed during the drag operation won't receive the ACTION_DRAG_ENDED 225 * event. 226 * </p> 227 * <p> 228 * The View object can call {@link #getResult()} to see the result of the operation. 229 * If a View returned {@code true} in response to {@link #ACTION_DROP}, then 230 * getResult() returns {@code true}, otherwise it returns {@code false}. 231 * </p> 232 * @see #ACTION_DRAG_STARTED 233 * @see #getResult() 234 */ 235 public static final int ACTION_DRAG_ENDED = 4; 236 237 /** 238 * Action constant returned by {@link #getAction()}: Signals to a View that the drag point has 239 * entered the bounding box of the View. 240 * <p> 241 * If the View can accept a drop, it can react to ACTION_DRAG_ENTERED 242 * by changing its appearance in a way that tells the user that the View is the current 243 * drop target. 244 * </p> 245 * The system stops sending ACTION_DRAG_LOCATION events to a View once the user moves the 246 * drag shadow out of the View object's bounding box or into a descendant view that can accept 247 * the data. If the user moves the drag shadow back into the View object's bounding box or out 248 * of a descendant view that can accept the data, the View receives an ACTION_DRAG_ENTERED again 249 * before receiving any more ACTION_DRAG_LOCATION events. 250 * </p> 251 * @see #ACTION_DRAG_ENTERED 252 * @see #ACTION_DRAG_LOCATION 253 */ 254 public static final int ACTION_DRAG_ENTERED = 5; 255 256 /** 257 * Action constant returned by {@link #getAction()}: Signals that the user has moved the 258 * drag shadow out of the bounding box of the View or into a descendant view that can accept 259 * the data. 260 * The View can react by changing its appearance in a way that tells the user that 261 * View is no longer the immediate drop target. 262 * <p> 263 * After the system sends an ACTION_DRAG_EXITED event to the View, the View receives no more 264 * ACTION_DRAG_LOCATION events until the user drags the drag shadow back over the View. 265 * </p> 266 * 267 */ 268 public static final int ACTION_DRAG_EXITED = 6; 269 270 private DragEvent() { 271 } 272 273 private void init(int action, float x, float y, ClipDescription description, ClipData data, 274 IDragAndDropPermissions dragAndDropPermissions, Object localState, boolean result) { 275 mAction = action; 276 mX = x; 277 mY = y; 278 mClipDescription = description; 279 mClipData = data; 280 this.mDragAndDropPermissions = dragAndDropPermissions; 281 mLocalState = localState; 282 mDragResult = result; 283 } 284 285 static DragEvent obtain() { 286 return DragEvent.obtain(0, 0f, 0f, null, null, null, null, false); 287 } 288 289 /** @hide */ 290 public static DragEvent obtain(int action, float x, float y, Object localState, 291 ClipDescription description, ClipData data, 292 IDragAndDropPermissions dragAndDropPermissions, boolean result) { 293 final DragEvent ev; 294 synchronized (gRecyclerLock) { 295 if (gRecyclerTop == null) { 296 ev = new DragEvent(); 297 ev.init(action, x, y, description, data, dragAndDropPermissions, localState, 298 result); 299 return ev; 300 } 301 ev = gRecyclerTop; 302 gRecyclerTop = ev.mNext; 303 gRecyclerUsed -= 1; 304 } 305 ev.mRecycledLocation = null; 306 ev.mRecycled = false; 307 ev.mNext = null; 308 309 ev.init(action, x, y, description, data, dragAndDropPermissions, localState, result); 310 311 return ev; 312 } 313 314 /** @hide */ 315 public static DragEvent obtain(DragEvent source) { 316 return obtain(source.mAction, source.mX, source.mY, source.mLocalState, 317 source.mClipDescription, source.mClipData, source.mDragAndDropPermissions, 318 source.mDragResult); 319 } 320 321 /** 322 * Inspect the action value of this event. 323 * @return One of the following action constants, in the order in which they usually occur 324 * during a drag and drop operation: 325 * <ul> 326 * <li>{@link #ACTION_DRAG_STARTED}</li> 327 * <li>{@link #ACTION_DRAG_ENTERED}</li> 328 * <li>{@link #ACTION_DRAG_LOCATION}</li> 329 * <li>{@link #ACTION_DROP}</li> 330 * <li>{@link #ACTION_DRAG_EXITED}</li> 331 * <li>{@link #ACTION_DRAG_ENDED}</li> 332 * </ul> 333 */ 334 public int getAction() { 335 return mAction; 336 } 337 338 /** 339 * Gets the X coordinate of the drag point. The value is only valid if the event action is 340 * {@link #ACTION_DRAG_STARTED}, {@link #ACTION_DRAG_LOCATION} or {@link #ACTION_DROP}. 341 * @return The current drag point's X coordinate 342 */ 343 public float getX() { 344 return mX; 345 } 346 347 /** 348 * Gets the Y coordinate of the drag point. The value is only valid if the event action is 349 * {@link #ACTION_DRAG_STARTED}, {@link #ACTION_DRAG_LOCATION} or {@link #ACTION_DROP}. 350 * @return The current drag point's Y coordinate 351 */ 352 public float getY() { 353 return mY; 354 } 355 356 /** 357 * Returns the {@link android.content.ClipData} object sent to the system as part of the call 358 * to 359 * {@link android.view.View#startDragAndDrop(ClipData,View.DragShadowBuilder,Object,int) 360 * startDragAndDrop()}. 361 * This method only returns valid data if the event action is {@link #ACTION_DROP}. 362 * @return The ClipData sent to the system by startDragAndDrop(). 363 */ 364 public ClipData getClipData() { 365 return mClipData; 366 } 367 368 /** 369 * Returns the {@link android.content.ClipDescription} object contained in the 370 * {@link android.content.ClipData} object sent to the system as part of the call to 371 * {@link android.view.View#startDragAndDrop(ClipData,View.DragShadowBuilder,Object,int) 372 * startDragAndDrop()}. 373 * The drag handler or listener for a View can use the metadata in this object to decide if the 374 * View can accept the dragged View object's data. 375 * <p> 376 * This method returns valid data for all event actions except for {@link #ACTION_DRAG_ENDED}. 377 * @return The ClipDescription that was part of the ClipData sent to the system by 378 * startDragAndDrop(). 379 */ 380 public ClipDescription getClipDescription() { 381 return mClipDescription; 382 } 383 384 /** @hide */ 385 public IDragAndDropPermissions getDragAndDropPermissions() { 386 return mDragAndDropPermissions; 387 } 388 389 /** 390 * Returns the local state object sent to the system as part of the call to 391 * {@link android.view.View#startDragAndDrop(ClipData,View.DragShadowBuilder,Object,int) 392 * startDragAndDrop()}. 393 * The object is intended to provide local information about the drag and drop operation. For 394 * example, it can indicate whether the drag and drop operation is a copy or a move. 395 * <p> 396 * The local state is available only to views in the activity which has started the drag 397 * operation. In all other activities this method will return null 398 * </p> 399 * <p> 400 * This method returns valid data for all event actions except for {@link #ACTION_DRAG_ENDED}. 401 * </p> 402 * @return The local state object sent to the system by startDragAndDrop(). 403 */ 404 public Object getLocalState() { 405 return mLocalState; 406 } 407 408 /** 409 * <p> 410 * Returns an indication of the result of the drag and drop operation. 411 * This method only returns valid data if the action type is {@link #ACTION_DRAG_ENDED}. 412 * The return value depends on what happens after the user releases the drag shadow. 413 * </p> 414 * <p> 415 * If the user releases the drag shadow on a View that can accept a drop, the system sends an 416 * {@link #ACTION_DROP} event to the View object's drag event listener. If the listener 417 * returns {@code true}, then getResult() will return {@code true}. 418 * If the listener returns {@code false}, then getResult() returns {@code false}. 419 * </p> 420 * <p> 421 * Notice that getResult() also returns {@code false} if no {@link #ACTION_DROP} is sent. This 422 * happens, for example, when the user releases the drag shadow over an area outside of the 423 * application. In this case, the system sends out {@link #ACTION_DRAG_ENDED} for the current 424 * operation, but never sends out {@link #ACTION_DROP}. 425 * </p> 426 * @return {@code true} if a drag event listener returned {@code true} in response to 427 * {@link #ACTION_DROP}. If the system did not send {@link #ACTION_DROP} before 428 * {@link #ACTION_DRAG_ENDED}, or if the listener returned {@code false} in response to 429 * {@link #ACTION_DROP}, then {@code false} is returned. 430 */ 431 public boolean getResult() { 432 return mDragResult; 433 } 434 435 /** 436 * Recycle the DragEvent, to be re-used by a later caller. After calling 437 * this function you must never touch the event again. 438 * 439 * @hide 440 */ 441 public final void recycle() { 442 // Ensure recycle is only called once! 443 if (TRACK_RECYCLED_LOCATION) { 444 if (mRecycledLocation != null) { 445 throw new RuntimeException(toString() + " recycled twice!", mRecycledLocation); 446 } 447 mRecycledLocation = new RuntimeException("Last recycled here"); 448 } else { 449 if (mRecycled) { 450 throw new RuntimeException(toString() + " recycled twice!"); 451 } 452 mRecycled = true; 453 } 454 455 mClipData = null; 456 mClipDescription = null; 457 mLocalState = null; 458 mEventHandlerWasCalled = false; 459 460 synchronized (gRecyclerLock) { 461 if (gRecyclerUsed < MAX_RECYCLED) { 462 gRecyclerUsed++; 463 mNext = gRecyclerTop; 464 gRecyclerTop = this; 465 } 466 } 467 } 468 469 /** 470 * Returns a string containing a concise, human-readable representation of this DragEvent 471 * object. 472 * @return A string representation of the DragEvent object. 473 */ 474 @Override 475 public String toString() { 476 return "DragEvent{" + Integer.toHexString(System.identityHashCode(this)) 477 + " action=" + mAction + " @ (" + mX + ", " + mY + ") desc=" + mClipDescription 478 + " data=" + mClipData + " local=" + mLocalState + " result=" + mDragResult 479 + "}"; 480 } 481 482 /* Parcelable interface */ 483 484 /** 485 * Returns information about the {@link android.os.Parcel} representation of this DragEvent 486 * object. 487 * @return Information about the {@link android.os.Parcel} representation. 488 */ 489 public int describeContents() { 490 return 0; 491 } 492 493 /** 494 * Creates a {@link android.os.Parcel} object from this DragEvent object. 495 * @param dest A {@link android.os.Parcel} object in which to put the DragEvent object. 496 * @param flags Flags to store in the Parcel. 497 */ 498 public void writeToParcel(Parcel dest, int flags) { 499 dest.writeInt(mAction); 500 dest.writeFloat(mX); 501 dest.writeFloat(mY); 502 dest.writeInt(mDragResult ? 1 : 0); 503 if (mClipData == null) { 504 dest.writeInt(0); 505 } else { 506 dest.writeInt(1); 507 mClipData.writeToParcel(dest, flags); 508 } 509 if (mClipDescription == null) { 510 dest.writeInt(0); 511 } else { 512 dest.writeInt(1); 513 mClipDescription.writeToParcel(dest, flags); 514 } 515 if (mDragAndDropPermissions == null) { 516 dest.writeInt(0); 517 } else { 518 dest.writeInt(1); 519 dest.writeStrongBinder(mDragAndDropPermissions.asBinder()); 520 } 521 } 522 523 /** 524 * A container for creating a DragEvent from a Parcel. 525 */ 526 public static final Parcelable.Creator<DragEvent> CREATOR = 527 new Parcelable.Creator<DragEvent>() { 528 public DragEvent createFromParcel(Parcel in) { 529 DragEvent event = DragEvent.obtain(); 530 event.mAction = in.readInt(); 531 event.mX = in.readFloat(); 532 event.mY = in.readFloat(); 533 event.mDragResult = (in.readInt() != 0); 534 if (in.readInt() != 0) { 535 event.mClipData = ClipData.CREATOR.createFromParcel(in); 536 } 537 if (in.readInt() != 0) { 538 event.mClipDescription = ClipDescription.CREATOR.createFromParcel(in); 539 } 540 if (in.readInt() != 0) { 541 event.mDragAndDropPermissions = 542 IDragAndDropPermissions.Stub.asInterface(in.readStrongBinder());; 543 } 544 return event; 545 } 546 547 public DragEvent[] newArray(int size) { 548 return new DragEvent[size]; 549 } 550 }; 551 } 552