A View initiates a drag-and-drop operation (hereafter just called a "drag")
by calling its startDrag(ClipData) method. Within the processing of that
call, two callbacks are made into the originating View. The first is to
onMeasureDragThumbnail(). Similarly to the core onMeasure() method, this
callback must respond by calling setDragThumbnailDimension(width, height) to
declare the size of the drag thumbnail image that should be used. Following
this, the View's onDrawDragThumbnail(canvas) method will be invoked to
actually produce the bits of the thumbnail image.
If all goes well, startDrag() will return 'true', and the drag is off and
running. (The other arguments to startDrag() provide reconciliation between
the current finger position and where the thumbnail should be placed on
the screen relative to it.)
Potential receipients of the ClipData behind the drag are notified by a
new dispatch mechanism, roughly parallel to motion event dispatch. The core
routine is the View's onDragEvent(event) callback, with the mechanics of
dispatch itself being routed through dispatchDragEvent(event) -- as in
the case of motion events, the dispatch logic is in ViewGroup, with leaf
View objects not needing to consider the dispatch flow.
Several different event 'actions' are delivered through this dispatch
mechanism:
ACTION_DRAG_STARTED: this event is propagated to every View in every window
(including windows created during the course of a drag). It serves as a
global notification that a drag has started with a payload whose matching
ClipDescription is supplied with the event. A View that is prepared to
consume the data described in this event should return 'true' from their
onDragEvent() method, and ideally will also make some visible on-screen
indication that they are a potential target of the drop.
ACTION_DRAG_ENTERED: this event is sent once when the drag point
enters the View's bounds. It is an opportunity for the View to set up
feedback that they are the one who will see the drop if the finger goes
up now.
ACTION_DRAG_LOCATION: when the drag point is over a given View, that
View will receive a stream of DRAG_LOCATION events, providing an
opportunity for the View to show visual feedback tied to the drag point.
ACTION_DRAG_EXITED: like DRAG_ENTERED, but called when the drag point
leaves the View's bounds. The View should undo any visuals meant to
emphasize their being the hovered-over target.
ACTION_DROP: when the drag ends at a given point, the View under that
point is sent this event, with the full ClipData of the payload.
ACTION_DRAG_ENDED: paralleling the DRAG_STARTED action, this is the global
broadcast that the drag has ended and all Views should return to their
normal visual state. This happens after the DROP event.
Change-Id: Ia8d0fb1516bce8c735d87ffd101af0976d7e84b6
a53146c556