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.