java.lang.Object | |
↳ | android.view.DragEvent |
Represents an event that is sent out by the system at various times during a drag and drop operation. It is a complex data structure that contains several important pieces of data about the operation and the underlying data.
View objects that receive a DragEvent call getAction()
, which returns
an action type that indicates the state of the drag and drop operation. This allows a View
object to react to a change in state by changing its appearance or performing other actions.
For example, a View can react to the ACTION_DRAG_ENTERED
action type by
by changing one or more colors in its displayed image.
During a drag and drop operation, the system displays an image that the user drags. This image is called a drag shadow. Several action types reflect the position of the drag shadow relative to the View receiving the event.
Most methods return valid data only for certain event actions. This is summarized in the
following table. Each possible getAction()
value is listed in the first column. The
other columns indicate which method or methods return valid data for that getAction() value:
getAction() Value | getClipDescription() | getLocalState() | getX() | getY() | getClipData() | getResult() |
---|---|---|---|---|---|---|
ACTION_DRAG_STARTED | X | X | X | X | ||
ACTION_DRAG_ENTERED | X | X | ||||
ACTION_DRAG_LOCATION | X | X | X | X | ||
ACTION_DRAG_EXITED | X | X | ||||
ACTION_DROP | X | X | X | X | X | |
ACTION_DRAG_ENDED | X | X | X |
The getAction()
,
describeContents()
,
writeToParcel(Parcel, int)
, and
toString()
methods always return valid data.
For a guide to implementing drag and drop features, read the Drag and Drop developer guide.
Constants | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
int | ACTION_DRAG_ENDED | Action constant returned by getAction() : Signals to a View that the drag and drop
operation has concluded. |
|||||||||
int | ACTION_DRAG_ENTERED | Action constant returned by getAction() : Signals to a View that the drag point has
entered the bounding box of the View. |
|||||||||
int | ACTION_DRAG_EXITED | Action constant returned by getAction() : Signals that the user has moved the
drag shadow outside the bounding box of the View. |
|||||||||
int | ACTION_DRAG_LOCATION | Action constant returned by getAction() : Sent to a View after
ACTION_DRAG_ENTERED if the drag shadow is still within the View object's bounding
box. |
|||||||||
int | ACTION_DRAG_STARTED | Action constant returned by getAction() : Signals the start of a
drag and drop operation. |
|||||||||
int | ACTION_DROP | Action constant returned by getAction() : Signals to a View that the user
has released the drag shadow, and the drag point is within the bounding box of the View. |
[Expand]
Inherited Constants | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From interface
android.os.Parcelable
|
Fields | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
CREATOR | A container for creating a DragEvent from a Parcel. |
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Returns information about the
Parcel representation of this DragEvent
object. | |||||||||||
Inspect the action value of this event.
| |||||||||||
Returns the
ClipData object sent to the system as part of the call
to
startDrag() . | |||||||||||
Returns the
ClipDescription object contained in the
ClipData object sent to the system as part of the call to
startDrag() . | |||||||||||
Returns the local state object sent to the system as part of the call to
startDrag() . | |||||||||||
Returns an indication of the result of the drag and drop operation. | |||||||||||
Gets the X coordinate of the drag point.
| |||||||||||
Gets the Y coordinate of the drag point.
| |||||||||||
Returns a string containing a concise, human-readable representation of this DragEvent
object.
| |||||||||||
Creates a
Parcel object from this DragEvent object. |
[Expand]
Inherited Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
java.lang.Object
| |||||||||||
From interface
android.os.Parcelable
|
Action constant returned by getAction()
: Signals to a View that the drag and drop
operation has concluded. A View that changed its appearance during the operation should
return to its usual drawing state in response to this event.
All views that received an ACTION_DRAG_STARTED event will receive the ACTION_DRAG_ENDED event even if they are not currently visible when the drag ends.
The View object can call getResult()
to see the result of the operation.
If a View returned true
in response to ACTION_DROP
, then
getResult() returns true
, otherwise it returns false
.
Action constant returned by getAction()
: Signals to a View that the drag point has
entered the bounding box of the View.
If the View can accept a drop, it can react to ACTION_DRAG_ENTERED by changing its appearance in a way that tells the user that the View is the current drop target.
The system stops sending ACTION_DRAG_LOCATION events to a View once the user moves the drag shadow out of the View object's bounding box. If the user moves the drag shadow back into the View object's bounding box, the View receives an ACTION_DRAG_ENTERED again before receiving any more ACTION_DRAG_LOCATION events.Action constant returned by getAction()
: Signals that the user has moved the
drag shadow outside the bounding box of the View.
The View can react by changing its appearance in a way that tells the user that
View is no longer the immediate drop target.
After the system sends an ACTION_DRAG_EXITED event to the View, the View receives no more ACTION_DRAG_LOCATION events until the user drags the drag shadow back over the View.
Action constant returned by getAction()
: Sent to a View after
ACTION_DRAG_ENTERED
if the drag shadow is still within the View object's bounding
box. The getX()
and getY()
methods supply
the X and Y position of of the drag point within the View object's bounding box.
A View receives an ACTION_DRAG_ENTERED
event before receiving any
ACTION_DRAG_LOCATION events.
The system stops sending ACTION_DRAG_LOCATION events to a View once the user moves the drag shadow out of the View object's bounding box. If the user moves the drag shadow back into the View object's bounding box, the View receives an ACTION_DRAG_ENTERED again before receiving any more ACTION_DRAG_LOCATION events.
Action constant returned by getAction()
: Signals the start of a
drag and drop operation. The View should return true
from its
onDragEvent()
handler method or
OnDragListener.onDrag()
listener
if it can accept a drop. The onDragEvent() or onDrag() methods usually inspect the metadata
from getClipDescription()
to determine if they can accept the data contained in
this drag. For an operation that doesn't represent data transfer, these methods may
perform other actions to determine whether or not the View should accept the drag.
If the View wants to indicate that it is a valid drop target, it can also react by
changing its appearance.
A View only receives further drag events if it returns true
in response to
ACTION_DRAG_STARTED.
Action constant returned by getAction()
: Signals to a View that the user
has released the drag shadow, and the drag point is within the bounding box of the View.
The View should retrieve the data from the DragEvent by calling getClipData()
.
The methods getX()
and getY()
return the X and Y position of the drop point
within the View object's bounding box.
The View should return true
from its onDragEvent(DragEvent)
handler or OnDragListener.onDrag()
listener if it accepted the drop, and false
if it ignored the drop.
The View can also react to this action by changing its appearance.
A container for creating a DragEvent from a Parcel.
Inspect the action value of this event.
Returns the ClipData
object sent to the system as part of the call
to
startDrag()
.
This method only returns valid data if the event action is ACTION_DROP
.
Returns the ClipDescription
object contained in the
ClipData
object sent to the system as part of the call to
startDrag()
.
The drag handler or listener for a View can use the metadata in this object to decide if the
View can accept the dragged View object's data.
This method returns valid data for all event actions.
Returns the local state object sent to the system as part of the call to
startDrag()
.
The object is intended to provide local information about the drag and drop operation. For
example, it can indicate whether the drag and drop operation is a copy or a move.
This method returns valid data for all event actions.
Returns an indication of the result of the drag and drop operation.
This method only returns valid data if the action type is ACTION_DRAG_ENDED
.
The return value depends on what happens after the user releases the drag shadow.
If the user releases the drag shadow on a View that can accept a drop, the system sends an
ACTION_DROP
event to the View object's drag event listener. If the listener
returns true
, then getResult() will return true
.
If the listener returns false
, then getResult() returns false
.
Notice that getResult() also returns false
if no ACTION_DROP
is sent. This
happens, for example, when the user releases the drag shadow over an area outside of the
application. In this case, the system sends out ACTION_DRAG_ENDED
for the current
operation, but never sends out ACTION_DROP
.
true
if a drag event listener returned true
in response to
ACTION_DROP
. If the system did not send ACTION_DROP
before
ACTION_DRAG_ENDED
, or if the listener returned false
in response to
ACTION_DROP
, then false
is returned.
Gets the X coordinate of the drag point. The value is only valid if the event action is
ACTION_DRAG_LOCATION
or ACTION_DROP
.
Gets the Y coordinate of the drag point. The value is valid if the
event action is ACTION_DRAG_ENTERED
, ACTION_DRAG_LOCATION
,
ACTION_DROP
, or ACTION_DRAG_EXITED
.
Returns a string containing a concise, human-readable representation of this DragEvent object.