1 page.title=Drag and Drop 2 page.tags=clipdata,dragevent,onlongclicklistener 3 @jd:body 4 5 <div id="qv-wrapper"> 6 <div id="qv"> 7 <h2>Quickview</h2> 8 <ul> 9 <li> 10 Allow users to move data within your Activity layout using graphical gestures. 11 </li> 12 <li> 13 Supports operations besides data movement. 14 </li> 15 <li> 16 Only works within a single application. 17 </li> 18 <li> 19 Requires API 11. 20 </li> 21 </ul> 22 <h2>In this document</h2> 23 <ol> 24 <li> 25 <a href="#AboutDragging">Overview</a> 26 <ol> 27 <li> 28 <a href="#DragDropLifecycle">The drag/drop process</a> 29 </li> 30 <li> 31 <a href="#AboutDragListeners">The drag event listener and callback method</a> 32 </li> 33 <li> 34 <a href="#AboutDragEvent">Drag events</a> 35 </li> 36 <li> 37 <a href="#AboutDragShadowBuilder"> 38 The drag shadow</a> 39 </li> 40 </ol> 41 </li> 42 <li> 43 <a href="#DesignDragOperation">Designing a Drag and Drop Operation</a> 44 <ol> 45 <li> 46 <a href="#StartDrag">Starting a drag</a> 47 </li> 48 <li> 49 <a href="#HandleStart">Responding to a drag start</a> 50 </li> 51 <li> 52 <a href="#HandleDuring">Handling events during the drag</a> 53 </li> 54 <li> 55 <a href="#HandleDrop">Responding to a drop</a> 56 </li> 57 <li> 58 <a href="#HandleEnd">Responding to a drag end</a> 59 </li> 60 <li> 61 <a href="#RespondEventSample">Responding to drag events: an example</a> 62 </li> 63 </ol> 64 </li> 65 </ol> 66 <h2>Key classes</h2> 67 <ol> 68 <li> 69 {@link android.view.View View} 70 </li> 71 <li> 72 {@link android.view.View.OnLongClickListener OnLongClickListener} 73 </li> 74 <li> 75 {@link android.view.View.OnDragListener OnDragListener} 76 </li> 77 <li> 78 {@link android.view.DragEvent DragEvent} 79 </li> 80 <li> 81 {@link android.view.View.DragShadowBuilder DragShadowBuilder} 82 </li> 83 <li> 84 {@link android.content.ClipData ClipData} 85 </li> 86 <li> 87 {@link android.content.ClipDescription ClipDescription} 88 </li> 89 </ol> 90 <h2>Related Samples</h2> 91 <ol> 92 <li> 93 <a href="{@docRoot}resources/samples/HoneycombGallery/index.html"> 94 Honeycomb Gallery</a>. 95 </li> 96 <li> 97 <a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/DragAndDropDemo.html"> 98 DragAndDropDemo.java</a> and 99 <a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/DraggableDot.html"> 100 DraggableDot.java</a> in <a href="{@docRoot}resources/samples/ApiDemos/index.html">Api Demos</a>. 101 </li> 102 </ol> 103 <h2>See also</h2> 104 <ol> 105 <li> 106 <a href="{@docRoot}guide/topics/providers/content-providers.html">Content Providers</a> 107 </li> 108 <li> 109 <a href="{@docRoot}guide/topics/ui/ui-events.html">Input Events</a> 110 </li> 111 </ol> 112 </div> 113 </div> 114 <p> 115 With the Android drag/drop framework, you can allow your users to move data 116 from one View to another View in the current layout using a graphical drag and drop gesture. 117 The framework includes a drag event class, drag listeners, and helper methods and classes. 118 </p> 119 <p> 120 Although the framework is primarily designed for data movement, you can use 121 it for other UI actions. For example, you could create an app that mixes colors when the user 122 drags a color icon over another icon. The rest of this topic, however, describes the 123 framework in terms of data movement. 124 </p> 125 <h2 id="AboutDragging">Overview</h2> 126 <p> 127 A drag and drop operation starts when the user makes some gesture that you recognize as a 128 signal to start dragging data. In response, your application tells the system that the drag is 129 starting. The system calls back to your application to get a representation of the data 130 being dragged. As the user's finger moves this representation (a "drag shadow") 131 over the current layout, the system sends drag events to the drag event listener objects and 132 drag event callback methods associated with the {@link android.view.View} objects in the layout. 133 Once the user releases the drag shadow, the system ends the drag operation. 134 </p> 135 <p> 136 You create a drag event listener object ("listeners") from a class that implements 137 {@link android.view.View.OnDragListener}. You set the drag event listener object for a View 138 with the View object's 139 {@link android.view.View#setOnDragListener(View.OnDragListener) setOnDragListener()} method. 140 Each View object also has a {@link android.view.View#onDragEvent(DragEvent) onDragEvent()} 141 callback method. Both of these are described in more detail in the section 142 <a href="#AboutDragListeners">The drag event listener and callback method</a>. 143 </p> 144 <p class="note"> 145 <strong>Note</strong>: For the sake of simplicity, the following sections refer to the routine 146 that receives drag events as the "drag event listener", even though it may actually 147 be a callback method. 148 </p> 149 <p> 150 When you start a drag, you include both the data you are moving and metadata describing this 151 data as part of the call to the system. During the drag, the system sends drag events to the 152 drag event listeners or callback methods of each View in the layout. The listeners or callback 153 methods can use the metadata to decide if they want to accept the data when it is dropped. 154 If the user drops the data over a View object, and that View object's listener or callback 155 method has previously told the system that it wants to accept the data, then the system sends 156 the data to the listener or callback method in a drag event. 157 </p> 158 <p> 159 Your application tells the system to start a drag by calling the 160 {@link android.view.View#startDrag(ClipData,View.DragShadowBuilder,Object,int) startDrag()} 161 method. This tells the system to start sending drag events. The method also sends the data that 162 you are dragging. 163 </p> 164 <p> 165 You can call 166 {@link android.view.View#startDrag(ClipData,View.DragShadowBuilder,Object,int) startDrag()} 167 for any attached View in the current layout. The system only uses the View object to get access 168 to global settings in your layout. 169 </p> 170 <p> 171 Once your application calls 172 {@link android.view.View#startDrag(ClipData,View.DragShadowBuilder,Object,int) startDrag()}, 173 the rest of the process uses events that the system sends to the View objects in your current 174 layout. 175 </p> 176 <h3 id="DragDropLifecycle">The drag/drop process</h3> 177 <p> 178 There are basically four steps or states in the drag and drop process: 179 </p> 180 <dl> 181 <dt> 182 <em>Started</em> 183 </dt> 184 <dd> 185 In response to the user's gesture to begin a drag, your application calls 186 {@link android.view.View#startDrag(ClipData,View.DragShadowBuilder,Object,int) startDrag()} 187 to tell the system to start a drag. The arguments 188 {@link android.view.View#startDrag(ClipData,View.DragShadowBuilder,Object,int) startDrag()} 189 provide the data to be dragged, metadata for this data, and a callback for drawing the 190 drag shadow. 191 <p> 192 The system first responds by calling back to your application to get a drag shadow. It 193 then displays the drag shadow on the device. 194 </p> 195 <p> 196 Next, the system sends a drag event with action type 197 {@link android.view.DragEvent#ACTION_DRAG_STARTED} to the drag event listeners for 198 all the View objects in the current layout. To continue to receive drag events, 199 including a possible drop event, a drag event listener must return <code>true</code>. 200 This registers the listener with the system. Only registered listeners continue to 201 receive drag events. At this point, listeners can also change the appearance of their 202 View object to show that the listener can accept a drop event. 203 </p> 204 <p> 205 If the drag event listener returns <code>false</code>, then it will not receive drag 206 events for the current operation until the system sends a drag event with action type 207 {@link android.view.DragEvent#ACTION_DRAG_ENDED}. By sending <code>false</code>, the 208 listener tells the system that it is not interested in the drag operation and 209 does not want to accept the dragged data. 210 </p> 211 </dd> 212 <dt> 213 <em>Continuing</em> 214 </dt> 215 <dd> 216 The user continues the drag. As the drag shadow intersects the bounding box of a View 217 object, the system sends one or more drag events to the View object's drag event 218 listener (if it is registered to receive events). The listener may choose to 219 alter its View object's appearance in response to the event. For example, if the event 220 indicates that the drag shadow has entered the bounding box of the View 221 (action type {@link android.view.DragEvent#ACTION_DRAG_ENTERED}), the listener 222 can react by highlighting its View. 223 </dd> 224 <dt> 225 <em>Dropped</em> 226 </dt> 227 <dd> 228 The user releases the drag shadow within the bounding box of a View that can accept the 229 data, but not within its descendant view that can accept the data. The system sends the View 230 object's listener a drag event with action type 231 {@link android.view.DragEvent#ACTION_DROP}. The drag event contains the data that was 232 passed to the system in the call to 233 {@link android.view.View#startDrag(ClipData,View.DragShadowBuilder,Object,int) startDrag()} 234 that started the operation. The listener is expected to return boolean <code>true</code> to 235 the system if code for accepting the drop succeeds. 236 <p> 237 Note that this step only occurs if the user drops the drag shadow within the bounding 238 box of a View whose listener is registered to receive drag events. If the user releases 239 the drag shadow in any other situation, no {@link android.view.DragEvent#ACTION_DROP} 240 drag event is sent. 241 </p> 242 </dd> 243 <dt> 244 <em>Ended</em> 245 </dt> 246 <dd> 247 After the user releases the drag shadow, and after the system sends out (if necessary) 248 a drag event with action type {@link android.view.DragEvent#ACTION_DROP}, the system sends 249 out a drag event with action type {@link android.view.DragEvent#ACTION_DRAG_ENDED} to 250 indicate that the drag operation is over. This is done regardless of where the user released 251 the drag shadow. The event is sent to every listener that is registered to receive drag 252 events, even if the listener received the {@link android.view.DragEvent#ACTION_DROP} event. 253 </dd> 254 </dl> 255 <p> 256 Each of these four steps is described in more detail in the section 257 <a href="#DesignDragOperation">Designing a Drag and Drop Operation</a>. 258 </p> 259 <h3 id="AboutDragListeners">The drag event listener and callback method</h3> 260 <p> 261 A View receives drag events with either a drag event listener that implements 262 {@link android.view.View.OnDragListener} or with its 263 {@link android.view.View#onDragEvent(DragEvent)} callback method. 264 When the system calls the method or listener, it passes to them 265 a {@link android.view.DragEvent} object. 266 </p> 267 <p> 268 You will probably want to use the listener in most cases. When you design UIs, you usually 269 don't subclass View classes, but using the callback method forces you to do this in order to 270 override the method. In comparison, you can implement one listener class and then use it with 271 several different View objects. You can also implement it as an anonymous inline class. To 272 set the listener for a View object, call 273 {@link android.view.View#setOnDragListener(android.view.View.OnDragListener) setOnDragListener()}. 274 </p> 275 <p> 276 You can have both a listener and a callback method for View object. If this occurs, 277 the system first calls the listener. The system doesn't call the callback method unless the 278 listener returns <code>false</code>. 279 </p> 280 <p> 281 The combination of the {@link android.view.View#onDragEvent(DragEvent)} method and 282 {@link android.view.View.OnDragListener} is analogous to the combination 283 of the {@link android.view.View#onTouchEvent(MotionEvent) onTouchEvent()} and 284 {@link android.view.View.OnTouchListener} used with touch events. 285 </p> 286 <h3 id="AboutDragEvent">Drag events</h3> 287 <p> 288 The system sends out a drag event in the form of a {@link android.view.DragEvent} object. The 289 object contains an action type that tells the listener what is happening in the drag/drop 290 process. The object contains other data, depending on the action type. 291 </p> 292 <p> 293 To get the action type, a listener calls {@link android.view.DragEvent#getAction()}. There 294 are six possible values, defined by constants in the {@link android.view.DragEvent} class. These 295 are listed in <a href="#table1">table 1</a>. 296 </p> 297 <p> 298 The {@link android.view.DragEvent} object also contains the data that your application provided 299 to the system in the call to 300 {@link android.view.View#startDrag(ClipData,View.DragShadowBuilder,Object,int) startDrag()}. 301 Some of the data is valid only for certain action types. The data that is valid for each action 302 type is summarized in <a href="#table2">table 2</a>. It is also described in detail with 303 the event for which it is valid in the section 304 <a href="#DesignDragOperation">Designing a Drag and Drop Operation</a>. 305 </p> 306 <p class="table-caption" id="table1"> 307 <strong>Table 1.</strong> DragEvent action types 308 </p> 309 <table> 310 <tr> 311 <th scope="col">getAction() value</th> 312 <th scope="col">Meaning</th> 313 </tr> 314 <tr> 315 <td>{@link android.view.DragEvent#ACTION_DRAG_STARTED}</td> 316 <td> 317 A View object's drag event listener receives this event action type just after the 318 application calls 319 {@link android.view.View#startDrag(ClipData,View.DragShadowBuilder,Object,int) startDrag()} and 320 gets a drag shadow. 321 <p> 322 If the listener wants to continue receiving drag events for this operation, it must 323 return boolean <code>true</code> to the system. 324 </p> 325 </td> 326 </tr> 327 <tr> 328 <td>{@link android.view.DragEvent#ACTION_DRAG_ENTERED}</td> 329 <td> 330 A View object's drag event listener receives this event action type when the drag shadow 331 has just entered the bounding box of the View. This is the first event action type the 332 listener receives when the drag shadow enters the bounding box. 333 </td> 334 </tr> 335 <tr> 336 <td>{@link android.view.DragEvent#ACTION_DRAG_LOCATION}</td> 337 <td> 338 A View object's drag event listener receives this event action type after it receives a 339 {@link android.view.DragEvent#ACTION_DRAG_ENTERED} event while the drag shadow is 340 still within the bounding box of the View and not within a descendant view that can 341 accept the data. 342 </td> 343 </tr> 344 <tr> 345 <td>{@link android.view.DragEvent#ACTION_DRAG_EXITED}</td> 346 <td> 347 A View object's drag event listener receives this event action type after it receives a 348 {@link android.view.DragEvent#ACTION_DRAG_ENTERED} and at least one 349 {@link android.view.DragEvent#ACTION_DRAG_LOCATION} event, and after the user has moved 350 the drag shadow outside the bounding box of the View or into a descendant view that can 351 accept the data. 352 </td> 353 </tr> 354 <tr> 355 <td>{@link android.view.DragEvent#ACTION_DROP}</td> 356 <td> 357 A View object's drag event listener receives this event action type when the user 358 releases the drag shadow over the View object. This action type is only sent to a View 359 object's listener if the listener returned boolean <code>true</code> in response to the 360 {@link android.view.DragEvent#ACTION_DRAG_STARTED} drag event. This action type is not 361 sent if the user releases the drag shadow on a View whose listener is not registered, 362 or if the user releases the drag shadow on anything that is not part of the current 363 layout. 364 <p> 365 The listener is expected to return boolean <code>true</code> if it successfully 366 processes the drop. Otherwise, it should return <code>false</code>. 367 </p> 368 </td> 369 </tr> 370 <tr> 371 <td>{@link android.view.DragEvent#ACTION_DRAG_ENDED}</td> 372 <td> 373 A View object's drag event listener receives this event action type 374 when the system is ending the drag operation. This action type is not necessarily 375 preceded by an {@link android.view.DragEvent#ACTION_DROP} event. If the system sent 376 a {@link android.view.DragEvent#ACTION_DROP}, receiving the 377 {@link android.view.DragEvent#ACTION_DRAG_ENDED} action type does not imply that the 378 drop operation succeeded. The listener must call 379 {@link android.view.DragEvent#getResult()} to get the value that was 380 returned in response to {@link android.view.DragEvent#ACTION_DROP}. If an 381 {@link android.view.DragEvent#ACTION_DROP} event was not sent, then 382 {@link android.view.DragEvent#getResult()} returns <code>false</code>. 383 </td> 384 </tr> 385 </table> 386 <p class="table-caption" id="table2"> 387 <strong>Table 2.</strong> Valid DragEvent data by action type</p> 388 <table> 389 <tr> 390 <th scope="col">{@link android.view.DragEvent#getAction()} value</th> 391 <th scope="col">{@link android.view.DragEvent#getClipDescription()} value</th> 392 <th scope="col">{@link android.view.DragEvent#getLocalState()} value</th> 393 <th scope="col">{@link android.view.DragEvent#getX()} value</th> 394 <th scope="col">{@link android.view.DragEvent#getY()} value</th> 395 <th scope="col">{@link android.view.DragEvent#getClipData()} value</th> 396 <th scope="col">{@link android.view.DragEvent#getResult()} value</th> 397 </tr> 398 <tr> 399 <td>{@link android.view.DragEvent#ACTION_DRAG_STARTED}</td> 400 <td style="text-align: center;">X</td> 401 <td style="text-align: center;">X</td> 402 <td style="text-align: center;">X</td> 403 <td style="text-align: center;">X</td> 404 <td style="text-align: center;"> </td> 405 <td style="text-align: center;"> </td> 406 </tr> 407 <tr> 408 <td>{@link android.view.DragEvent#ACTION_DRAG_ENTERED}</td> 409 <td style="text-align: center;">X</td> 410 <td style="text-align: center;">X</td> 411 <td style="text-align: center;">X</td> 412 <td style="text-align: center;">X</td> 413 <td style="text-align: center;"> </td> 414 <td style="text-align: center;"> </td> 415 </tr> 416 <tr> 417 <td>{@link android.view.DragEvent#ACTION_DRAG_LOCATION}</td> 418 <td style="text-align: center;">X</td> 419 <td style="text-align: center;">X</td> 420 <td style="text-align: center;">X</td> 421 <td style="text-align: center;">X</td> 422 <td style="text-align: center;"> </td> 423 <td style="text-align: center;"> </td> 424 </tr> 425 <tr> 426 <td>{@link android.view.DragEvent#ACTION_DRAG_EXITED}</td> 427 <td style="text-align: center;">X</td> 428 <td style="text-align: center;">X</td> 429 <td style="text-align: center;"> </td> 430 <td style="text-align: center;"> </td> 431 <td style="text-align: center;"> </td> 432 <td style="text-align: center;"> </td> 433 </tr> 434 <tr> 435 <td>{@link android.view.DragEvent#ACTION_DROP}</td> 436 <td style="text-align: center;">X</td> 437 <td style="text-align: center;">X</td> 438 <td style="text-align: center;">X</td> 439 <td style="text-align: center;">X</td> 440 <td style="text-align: center;">X</td> 441 <td style="text-align: center;"> </td> 442 </tr> 443 <tr> 444 <td>{@link android.view.DragEvent#ACTION_DRAG_ENDED}</td> 445 <td style="text-align: center;">X</td> 446 <td style="text-align: center;">X</td> 447 <td style="text-align: center;"> </td> 448 <td style="text-align: center;"> </td> 449 <td style="text-align: center;"> </td> 450 <td style="text-align: center;">X</td> 451 </tr> 452 </table> 453 <p> 454 The {@link android.view.DragEvent#getAction()}, 455 {@link android.view.DragEvent#describeContents()}, 456 {@link android.view.DragEvent#writeToParcel(Parcel,int) writeToParcel()}, and 457 {@link android.view.DragEvent#toString()} methods always return valid data. 458 </p> 459 <p> 460 If a method does not contain valid data for a particular action type, it returns either 461 <code>null</code> or 0, depending on its result type. 462 </p> 463 <h3 id="AboutDragShadowBuilder"> 464 The drag shadow 465 </h3> 466 <p> 467 During a drag and drop operation, the system displays a image that the user drags. 468 For data movement, this image represents the data being dragged. For other operations, the 469 image represents some aspect of the drag operation. 470 </p> 471 <p> 472 The image is called a drag shadow. You create it with methods you declare for a 473 {@link android.view.View.DragShadowBuilder} object, and then pass it to the system when you 474 start a drag using 475 {@link android.view.View#startDrag(ClipData,View.DragShadowBuilder,Object,int) startDrag()}. 476 As part of its response to 477 {@link android.view.View#startDrag(ClipData,View.DragShadowBuilder,Object,int) startDrag()}, 478 the system invokes the callback methods you've defined in 479 {@link android.view.View.DragShadowBuilder} to obtain a drag shadow. 480 </p> 481 <p> 482 The {@link android.view.View.DragShadowBuilder} class has two constructors: 483 </p> 484 <dl> 485 <dt>{@link android.view.View.DragShadowBuilder#View.DragShadowBuilder(View)}</dt> 486 <dd> 487 This constructor accepts any of your application's 488 {@link android.view.View} objects. The constructor stores the View object 489 in the {@link android.view.View.DragShadowBuilder} object, so during 490 the callback you can access it as you construct your drag shadow. 491 It doesn't have to be associated with the View (if any) that the user 492 selected to start the drag operation. 493 <p> 494 If you use this constructor, you don't have to extend 495 {@link android.view.View.DragShadowBuilder} or override its methods. By default, 496 you will get a drag shadow that has the same appearance as the View you pass as an 497 argument, centered under the location where the user is touching the screen. 498 </p> 499 </dd> 500 <dt>{@link android.view.View.DragShadowBuilder#View.DragShadowBuilder()}</dt> 501 <dd> 502 If you use this constructor, no View object is available in the 503 {@link android.view.View.DragShadowBuilder} object (the field is set to <code>null</code>). 504 If you use this constructor, and you don't extend 505 {@link android.view.View.DragShadowBuilder} or override its methods, 506 you will get an invisible drag shadow. 507 The system does <em>not</em> give an error. 508 </dd> 509 </dl> 510 <p> 511 The {@link android.view.View.DragShadowBuilder} class has two methods: 512 </p> 513 <dl> 514 <dt> 515 {@link android.view.View.DragShadowBuilder#onProvideShadowMetrics(Point,Point) onProvideShadowMetrics()} 516 </dt> 517 <dd> 518 The system calls this method immediately after you call 519 {@link android.view.View#startDrag(ClipData,View.DragShadowBuilder,Object,int) startDrag()}. Use it 520 to send to the system the dimensions and touch point of the drag shadow. The method has two 521 arguments: 522 <dl> 523 <dt><em>dimensions</em></dt> 524 <dd> 525 A {@link android.graphics.Point} object. The drag shadow width goes in 526 {@link android.graphics.Point#x} and its height goes in 527 {@link android.graphics.Point#y}. 528 </dd> 529 <dt><em>touch_point</em></dt> 530 <dd> 531 A {@link android.graphics.Point} object. The touch point is the location within the 532 drag shadow that should be under the user's finger during the drag. Its X 533 position goes in {@link android.graphics.Point#x} and its Y position goes in 534 {@link android.graphics.Point#y} 535 </dd> 536 </dl> 537 </dd> 538 <dt> 539 {@link android.view.View.DragShadowBuilder#onDrawShadow(Canvas) onDrawShadow()} 540 </dt> 541 <dd> 542 Immediately after the call to 543 {@link android.view.View.DragShadowBuilder#onProvideShadowMetrics(Point,Point) onProvideShadowMetrics()} 544 the system calls 545 {@link android.view.View.DragShadowBuilder#onDrawShadow(Canvas) onDrawShadow()} to get the 546 drag shadow itself. The method has a single argument, a {@link android.graphics.Canvas} 547 object that the system constructs from the parameters you provide in 548 {@link android.view.View.DragShadowBuilder#onProvideShadowMetrics(Point,Point) onProvideShadowMetrics()} 549 Use it to draw the drag shadow in the provided {@link android.graphics.Canvas} object. 550 </dd> 551 </dl> 552 <p> 553 To improve performance, you should keep the size of the drag shadow small. For a single item, 554 you may want to use a icon. For a multiple selection, you may want to use icons in a stack 555 rather than full images spread out over the screen. 556 </p> 557 <h2 id="DesignDragOperation">Designing a Drag and Drop Operation</h2> 558 <p> 559 This section shows step-by-step how to start a drag, how to respond to events during 560 the drag, how respond to a drop event, and how to end the drag and drop operation. 561 </p> 562 <h3 id="StartDrag">Starting a drag</h3> 563 <p> 564 The user starts a drag with a drag gesture, usually a long press, on a View object. 565 In response, you should do the following: 566 </p> 567 <ol> 568 <li> 569 As necessary, create a {@link android.content.ClipData} and 570 {@link android.content.ClipData.Item} for the data being moved. As part of the 571 ClipData object, supply metadata that is stored in a {@link android.content.ClipDescription} 572 object within the ClipData. For a drag and drop operation that does not represent data 573 movement, you may want to use <code>null</code> instead of an actual object. 574 <p> 575 For example, this code snippet shows how to respond to a long press on a ImageView 576 by creating a ClipData object that contains the tag or label of an 577 ImageView. Following this snippet, the next snippet shows how to override the methods in 578 {@link android.view.View.DragShadowBuilder}: 579 </p> 580 <pre> 581 // Create a string for the ImageView label 582 private static final String IMAGEVIEW_TAG = "icon bitmap" 583 584 // Creates a new ImageView 585 ImageView imageView = new ImageView(this); 586 587 // Sets the bitmap for the ImageView from an icon bit map (defined elsewhere) 588 imageView.setImageBitmap(mIconBitmap); 589 590 // Sets the tag 591 imageView.setTag(IMAGEVIEW_TAG); 592 593 ... 594 595 // Sets a long click listener for the ImageView using an anonymous listener object that 596 // implements the OnLongClickListener interface 597 imageView.setOnLongClickListener(new View.OnLongClickListener() { 598 599 // Defines the one method for the interface, which is called when the View is long-clicked 600 public boolean onLongClick(View v) { 601 602 // Create a new ClipData. 603 // This is done in two steps to provide clarity. The convenience method 604 // ClipData.newPlainText() can create a plain text ClipData in one step. 605 606 // Create a new ClipData.Item from the ImageView object's tag 607 ClipData.Item item = new ClipData.Item(v.getTag()); 608 609 // Create a new ClipData using the tag as a label, the plain text MIME type, and 610 // the already-created item. This will create a new ClipDescription object within the 611 // ClipData, and set its MIME type entry to "text/plain" 612 ClipData dragData = new ClipData(v.getTag(),ClipData.MIMETYPE_TEXT_PLAIN,item); 613 614 // Instantiates the drag shadow builder. 615 View.DragShadowBuilder myShadow = new MyDragShadowBuilder(imageView); 616 617 // Starts the drag 618 619 v.startDrag(dragData, // the data to be dragged 620 myShadow, // the drag shadow builder 621 null, // no need to use local data 622 0 // flags (not currently used, set to 0) 623 ); 624 625 } 626 } 627 </pre> 628 </li> 629 <li> 630 The following code snippet defines {@code myDragShadowBuilder} 631 It creates a drag shadow for dragging a TextView as a small gray rectangle: 632 <pre> 633 private static class MyDragShadowBuilder extends View.DragShadowBuilder { 634 635 // The drag shadow image, defined as a drawable thing 636 private static Drawable shadow; 637 638 // Defines the constructor for myDragShadowBuilder 639 public MyDragShadowBuilder(View v) { 640 641 // Stores the View parameter passed to myDragShadowBuilder. 642 super(v); 643 644 // Creates a draggable image that will fill the Canvas provided by the system. 645 shadow = new ColorDrawable(Color.LTGRAY); 646 } 647 648 // Defines a callback that sends the drag shadow dimensions and touch point back to the 649 // system. 650 @Override 651 public void onProvideShadowMetrics (Point size, Point touch) { 652 // Defines local variables 653 private int width, height; 654 655 // Sets the width of the shadow to half the width of the original View 656 width = getView().getWidth() / 2; 657 658 // Sets the height of the shadow to half the height of the original View 659 height = getView().getHeight() / 2; 660 661 // The drag shadow is a ColorDrawable. This sets its dimensions to be the same as the 662 // Canvas that the system will provide. As a result, the drag shadow will fill the 663 // Canvas. 664 shadow.setBounds(0, 0, width, height); 665 666 // Sets the size parameter's width and height values. These get back to the system 667 // through the size parameter. 668 size.set(width, height); 669 670 // Sets the touch point's position to be in the middle of the drag shadow 671 touch.set(width / 2, height / 2); 672 } 673 674 // Defines a callback that draws the drag shadow in a Canvas that the system constructs 675 // from the dimensions passed in onProvideShadowMetrics(). 676 @Override 677 public void onDrawShadow(Canvas canvas) { 678 679 // Draws the ColorDrawable in the Canvas passed in from the system. 680 shadow.draw(canvas); 681 } 682 } 683 </pre> 684 <p class="note"> 685 <strong>Note:</strong> Remember that you don't have to extend 686 {@link android.view.View.DragShadowBuilder}. The constructor 687 {@link android.view.View.DragShadowBuilder#View.DragShadowBuilder(View)} creates a 688 default drag shadow that's the same size as the View argument passed to it, with the 689 touch point centered in the drag shadow. 690 </p> 691 </li> 692 </ol> 693 <h3 id="HandleStart">Responding to a drag start</h3> 694 <p> 695 During the drag operation, the system dispatches drag events to the drag event listeners 696 of the View objects in the current layout. The listeners should react 697 by calling {@link android.view.DragEvent#getAction()} to get the action type. 698 At the start of a drag, this methods returns {@link android.view.DragEvent#ACTION_DRAG_STARTED}. 699 </p> 700 <p> 701 In response to an event with the action type {@link android.view.DragEvent#ACTION_DRAG_STARTED}, 702 a listener should do the following: 703 </p> 704 <ol> 705 <li> 706 Call {@link android.view.DragEvent#getClipDescription()} to get the 707 {@link android.content.ClipDescription}. Use the MIME type methods in 708 {@link android.content.ClipDescription} to see if the listener can accept the data being 709 dragged. 710 <p> 711 If the drag and drop operation does not represent data movement, this may not be 712 necessary. 713 </p> 714 </li> 715 <li> 716 If the listener can accept a drop, it should return <code>true</code>. This tells 717 the system to continue to send drag events to the listener. 718 If it can't accept a drop, it should return <code>false</code>, and the system 719 will stop sending drag events for the current drag operation. 720 </li> 721 </ol> 722 <p> 723 Note that for an {@link android.view.DragEvent#ACTION_DRAG_STARTED} event, these 724 the following {@link android.view.DragEvent} methods are not valid: 725 {@link android.view.DragEvent#getClipData()}, {@link android.view.DragEvent#getX()}, 726 {@link android.view.DragEvent#getY()}, and {@link android.view.DragEvent#getResult()}. 727 </p> 728 <h3 id="HandleDuring">Handling events during the drag</h3> 729 <p> 730 During the drag, listeners that returned <code>true</code> in response to 731 the {@link android.view.DragEvent#ACTION_DRAG_STARTED} drag event continue to receive drag 732 events. The types of drag events a listener receives during the drag depend on the location of 733 the drag shadow and the visibility of the listener's View. 734 </p> 735 <p> 736 During the drag, listeners primarily use drag events to decide if they should change the 737 appearance of their View. 738 </p> 739 <p> 740 During the drag, {@link android.view.DragEvent#getAction()} returns one of three 741 values: 742 </p> 743 <ul> 744 <li> 745 {@link android.view.DragEvent#ACTION_DRAG_ENTERED}: 746 The listener receives this when the touch point 747 (the point on the screen underneath the user's finger) has entered the bounding box of the 748 listener's View. 749 </li> 750 <li> 751 {@link android.view.DragEvent#ACTION_DRAG_LOCATION}: Once the listener receives an 752 {@link android.view.DragEvent#ACTION_DRAG_ENTERED} event, and before it receives an 753 A{@link android.view.DragEvent#ACTION_DRAG_EXITED} event, it receives a new 754 {@link android.view.DragEvent#ACTION_DRAG_LOCATION} event every time the touch point moves. 755 The {@link android.view.DragEvent#getX()} and {@link android.view.DragEvent#getY()} methods 756 return the X and Y coordinates of the touch point. 757 </li> 758 <li> 759 {@link android.view.DragEvent#ACTION_DRAG_EXITED}: This event is sent to a listener that 760 previously received {@link android.view.DragEvent#ACTION_DRAG_ENTERED}, after 761 the drag shadow is no longer within the bounding box of the listener's View or it's within 762 the bounding box of a descendant view that can accept the data. 763 </li> 764 </ul> 765 <p> 766 The listener does not need to react to any of these action types. If the listener returns a 767 value to the system, it is ignored. Here are some guidelines for responding to each of 768 these action types: 769 </p> 770 <ul> 771 <li> 772 In response to {@link android.view.DragEvent#ACTION_DRAG_ENTERED} or 773 {@link android.view.DragEvent#ACTION_DRAG_LOCATION}, the listener can change the appearance 774 of the View to indicate that it is about to receive a drop. 775 </li> 776 <li> 777 An event with the action type {@link android.view.DragEvent#ACTION_DRAG_LOCATION} contains 778 valid data for {@link android.view.DragEvent#getX()} and 779 {@link android.view.DragEvent#getY()}, corresponding to the location of the touch point. 780 The listener may want to use this information to alter the appearance of that part of the 781 View that is at the touch point. The listener can also use this information 782 to determine the exact position where the user is going to drop the drag shadow. 783 </li> 784 <li> 785 In response to {@link android.view.DragEvent#ACTION_DRAG_EXITED}, the listener should reset 786 any appearance changes it applied in response to 787 {@link android.view.DragEvent#ACTION_DRAG_ENTERED} or 788 {@link android.view.DragEvent#ACTION_DRAG_LOCATION}. This indicates to the user that 789 the View is no longer an imminent drop target. 790 </li> 791 </ul> 792 <h3 id="HandleDrop">Responding to a drop</h3> 793 <p> 794 When the user releases the drag shadow on a View in the application, and that View previously 795 reported that it could accept the content being dragged, the system dispatches a drag event 796 to that View with the action type {@link android.view.DragEvent#ACTION_DROP}. The listener 797 should do the following: 798 </p> 799 <ol> 800 <li> 801 Call {@link android.view.DragEvent#getClipData()} to get the 802 {@link android.content.ClipData} object that was originally supplied in the call 803 to 804 {@link android.view.View#startDrag(ClipData, View.DragShadowBuilder, Object, int) startDrag()} 805 and store it. If the drag and drop operation does not represent data movement, 806 this may not be necessary. 807 </li> 808 <li> 809 Return boolean <code>true</code> to indicate that the drop was processed successfully, or 810 boolean <code>false</code> if it was not. The returned value becomes the value returned by 811 {@link android.view.DragEvent#getResult()} for an 812 {@link android.view.DragEvent#ACTION_DRAG_ENDED} event. 813 <p> 814 Note that if the system does not send out an {@link android.view.DragEvent#ACTION_DROP} 815 event, the value of {@link android.view.DragEvent#getResult()} for an 816 {@link android.view.DragEvent#ACTION_DRAG_ENDED} event is <code>false</code>. 817 </p> 818 </li> 819 </ol> 820 <p> 821 For an {@link android.view.DragEvent#ACTION_DROP} event, 822 {@link android.view.DragEvent#getX()} and {@link android.view.DragEvent#getY()} 823 return the X and Y position of the drag point at the moment of the drop, using the coordinate 824 system of the View that received the drop. 825 </p> 826 <p> 827 The system does allow the user to release the drag shadow on a View whose listener is not 828 receiving drag events. It will also allow the user to release the drag shadow 829 on empty regions of the application's UI, or on areas outside of your application. 830 In all of these cases, the system does not send an event with action type 831 {@link android.view.DragEvent#ACTION_DROP}, although it does send out an 832 {@link android.view.DragEvent#ACTION_DRAG_ENDED} event. 833 </p> 834 <h3 id="HandleEnd">Responding to a drag end</h3> 835 <p> 836 Immediately after the user releases the drag shadow, the system sends a 837 drag event to all of the drag event listeners in your application, with an action type of 838 {@link android.view.DragEvent#ACTION_DRAG_ENDED}. This indicates that the drag operation is 839 over. 840 </p> 841 <p> 842 Each listener should do the following: 843 </p> 844 <ol> 845 <li> 846 If listener changed its View object's appearance during the operation, it should reset the 847 View to its default appearance. This is a visual indication to the user that the operation 848 is over. 849 </li> 850 <li> 851 The listener can optionally call {@link android.view.DragEvent#getResult()} to find out more 852 about the operation. If a listener returned <code>true</code> in response to an event of 853 action type {@link android.view.DragEvent#ACTION_DROP}, then 854 {@link android.view.DragEvent#getResult()} will return boolean <code>true</code>. In all 855 other cases, {@link android.view.DragEvent#getResult()} returns boolean <code>false</code>, 856 including any case in which the system did not send out a 857 {@link android.view.DragEvent#ACTION_DROP} event. 858 </li> 859 <li> 860 The listener should return boolean <code>true</code> to the system. 861 </li> 862 </ol> 863 <p> 864 </p> 865 <h3 id="RespondEventSample">Responding to drag events: an example</h3> 866 <p> 867 All drag events are initially received by your drag event method or listener. The following 868 code snippet is a simple example of reacting to drag events in a listener: 869 </p> 870 <pre> 871 // Creates a new drag event listener 872 mDragListen = new myDragEventListener(); 873 874 View imageView = new ImageView(this); 875 876 // Sets the drag event listener for the View 877 imageView.setOnDragListener(mDragListen); 878 879 ... 880 881 protected class myDragEventListener implements View.OnDragListener { 882 883 // This is the method that the system calls when it dispatches a drag event to the 884 // listener. 885 public boolean onDrag(View v, DragEvent event) { 886 887 // Defines a variable to store the action type for the incoming event 888 final int action = event.getAction(); 889 890 // Handles each of the expected events 891 switch(action) { 892 893 case DragEvent.ACTION_DRAG_STARTED: 894 895 // Determines if this View can accept the dragged data 896 if (event.getClipDescription().hasMimeType(ClipDescription.MIMETYPE_TEXT_PLAIN)) { 897 898 // As an example of what your application might do, 899 // applies a blue color tint to the View to indicate that it can accept 900 // data. 901 v.setColorFilter(Color.BLUE); 902 903 // Invalidate the view to force a redraw in the new tint 904 v.invalidate(); 905 906 // returns true to indicate that the View can accept the dragged data. 907 return true; 908 909 } 910 911 // Returns false. During the current drag and drop operation, this View will 912 // not receive events again until ACTION_DRAG_ENDED is sent. 913 return false; 914 915 case DragEvent.ACTION_DRAG_ENTERED: 916 917 // Applies a green tint to the View. Return true; the return value is ignored. 918 919 v.setColorFilter(Color.GREEN); 920 921 // Invalidate the view to force a redraw in the new tint 922 v.invalidate(); 923 924 return true; 925 926 case DragEvent.ACTION_DRAG_LOCATION: 927 928 // Ignore the event 929 return true; 930 931 case DragEvent.ACTION_DRAG_EXITED: 932 933 // Re-sets the color tint to blue. Returns true; the return value is ignored. 934 v.setColorFilter(Color.BLUE); 935 936 // Invalidate the view to force a redraw in the new tint 937 v.invalidate(); 938 939 return true; 940 941 case DragEvent.ACTION_DROP: 942 943 // Gets the item containing the dragged data 944 ClipData.Item item = event.getClipData().getItemAt(0); 945 946 // Gets the text data from the item. 947 dragData = item.getText(); 948 949 // Displays a message containing the dragged data. 950 Toast.makeText(this, "Dragged data is " + dragData, Toast.LENGTH_LONG); 951 952 // Turns off any color tints 953 v.clearColorFilter(); 954 955 // Invalidates the view to force a redraw 956 v.invalidate(); 957 958 // Returns true. DragEvent.getResult() will return true. 959 return true; 960 961 case DragEvent.ACTION_DRAG_ENDED: 962 963 // Turns off any color tinting 964 v.clearColorFilter(); 965 966 // Invalidates the view to force a redraw 967 v.invalidate(); 968 969 // Does a getResult(), and displays what happened. 970 if (event.getResult()) { 971 Toast.makeText(this, "The drop was handled.", Toast.LENGTH_LONG); 972 973 } else { 974 Toast.makeText(this, "The drop didn't work.", Toast.LENGTH_LONG); 975 976 } 977 978 // returns true; the value is ignored. 979 return true; 980 981 // An unknown action type was received. 982 default: 983 Log.e("DragDrop Example","Unknown action type received by OnDragListener."); 984 break; 985 } 986 987 return false; 988 } 989 }; 990 </pre> 991
