public class DragEvent extends Object implements Parcelable
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.
Parcelable.ClassLoaderCreator<T>, Parcelable.Creator<T>
Modifier and Type | Field and Description |
---|---|
static int |
ACTION_DRAG_ENDED
Action constant returned by
getAction() : Signals to a View that the drag and drop
operation has concluded. |
static 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. |
static 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. |
static 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. |
static int |
ACTION_DRAG_STARTED
Action constant returned by
getAction() : Signals the start of a
drag and drop operation. |
static 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. |
static Parcelable.Creator<DragEvent> |
CREATOR
A container for creating a DragEvent from a Parcel.
|
CONTENTS_FILE_DESCRIPTOR, PARCELABLE_WRITE_RETURN_VALUE
Modifier and Type | Method and Description |
---|---|
int |
describeContents()
Returns information about the
Parcel representation of this DragEvent
object. |
int |
getAction()
Inspect the action value of this event.
|
ClipData |
getClipData()
Returns the
ClipData object sent to the system as part of the call
to
startDrag() . |
ClipDescription |
getClipDescription()
Returns the
ClipDescription object contained in the
ClipData object sent to the system as part of the call to
startDrag() . |
Object |
getLocalState()
Returns the local state object sent to the system as part of the call to
startDrag() . |
boolean |
getResult()
Returns an indication of the result of the drag and drop operation.
|
float |
getX()
Gets the X coordinate of the drag point.
|
float |
getY()
Gets the Y coordinate of the drag point.
|
static DragEvent |
obtain(DragEvent source) |
static DragEvent |
obtain(int action,
float x,
float y,
Object localState,
ClipDescription description,
ClipData data,
boolean result) |
void |
recycle()
Recycle the DragEvent, to be re-used by a later caller.
|
String |
toString()
Returns a string containing a concise, human-readable representation of this DragEvent
object.
|
void |
writeToParcel(Parcel dest,
int flags)
Creates a
Parcel object from this DragEvent object. |
public static final int ACTION_DRAG_STARTED
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_DRAG_ENDED
,
Constant Field Valuespublic static final int ACTION_DRAG_LOCATION
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_DRAG_ENTERED
,
getX()
,
getY()
,
Constant Field Valuespublic static final int ACTION_DROP
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 View.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.
getClipData()
,
getX()
,
getY()
,
Constant Field Valuespublic static final int ACTION_DRAG_ENDED
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_DRAG_STARTED
,
getResult()
,
Constant Field Valuespublic static final int ACTION_DRAG_ENTERED
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.public static final int ACTION_DRAG_EXITED
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.
public static final Parcelable.Creator<DragEvent> CREATOR
public static DragEvent obtain(int action, float x, float y, Object localState, ClipDescription description, ClipData data, boolean result)
public int getAction()
public float getX()
ACTION_DRAG_LOCATION
or ACTION_DROP
.public float getY()
ACTION_DRAG_ENTERED
, ACTION_DRAG_LOCATION
,
ACTION_DROP
, or ACTION_DRAG_EXITED
.public ClipData getClipData()
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
.public ClipDescription getClipDescription()
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.
public Object getLocalState()
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.
public boolean getResult()
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.public final void recycle()
public String toString()
public int describeContents()
Parcel
representation of this DragEvent
object.describeContents
in interface Parcelable
Parcel
representation.public void writeToParcel(Parcel dest, int flags)
Parcel
object from this DragEvent object.writeToParcel
in interface Parcelable
dest
- A Parcel
object in which to put the DragEvent object.flags
- Flags to store in the Parcel.