Loading core/java/android/view/DragEvent.java +250 −78 Original line number Diff line number Diff line Loading @@ -21,7 +21,100 @@ import android.content.ClipDescription; import android.os.Parcel; import android.os.Parcelable; /** !!! TODO: real docs */ //TODO: Improve Javadoc /** * 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. * <p> * View objects that receive a DragEvent call {@link #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 {@link #ACTION_DRAG_ENTERED} action type by * by changing one or more colors in its displayed image. * </p> * <p> * 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. * </p> * <p> * Most methods return valid data only for certain event actions. This is summarized in the * following table. Each possible {@link #getAction()} value is listed in the first column. The * other columns indicate which method or methods return valid data for that getAction() value: * </p> * <table> * <tr> * <th scope="col">getAction() Value</th> * <th scope="col">getClipDescription()</th> * <th scope="col">getLocalState()</th> * <th scope="col">getX()</th> * <th scope="col">getY()</th> * <th scope="col">getClipData()</th> * <th scope="col">getResult()</th> * </tr> * <tr> * <td>ACTION_DRAG_STARTED</td> * <td style="text-align: center;">X</td> * <td style="text-align: center;">X</td> * <td style="text-align: center;">X</td> * <td style="text-align: center;">X</td> * <td style="text-align: center;"> </td> * <td style="text-align: center;"> </td> * </tr> * <tr> * <td>ACTION_DRAG_ENTERED</td> * <td style="text-align: center;">X</td> * <td style="text-align: center;">X</td> * <td style="text-align: center;"> </td> * <td style="text-align: center;"> </td> * <td style="text-align: center;"> </td> * <td style="text-align: center;"> </td> * </tr> * <tr> * <td>ACTION_DRAG_LOCATION</td> * <td style="text-align: center;">X</td> * <td style="text-align: center;">X</td> * <td style="text-align: center;">X</td> * <td style="text-align: center;">X</td> * <td style="text-align: center;"> </td> * <td style="text-align: center;"> </td> * </tr> * <tr> * <td>ACTION_DRAG_EXITED</td> * <td style="text-align: center;">X</td> * <td style="text-align: center;">X</td> * <td style="text-align: center;"> </td> * <td style="text-align: center;"> </td> * <td style="text-align: center;"> </td> * <td style="text-align: center;"> </td> * </tr> * <tr> * <td>ACTION_DROP</td> * <td style="text-align: center;">X</td> * <td style="text-align: center;">X</td> * <td style="text-align: center;">X</td> * <td style="text-align: center;">X</td> * <td style="text-align: center;">X</td> * <td style="text-align: center;"> </td> * </tr> * <tr> * <td>ACTION_DRAG_ENDED</td> * <td style="text-align: center;">X</td> * <td style="text-align: center;">X</td> * <td style="text-align: center;"> </td> * <td style="text-align: center;"> </td> * <td style="text-align: center;"> </td> * <td style="text-align: center;">X</td> * </tr> * </table> * <p> * The {@link android.view.DragEvent#getAction()}, * {@link android.view.DragEvent#describeContents()}, * {@link android.view.DragEvent#writeToParcel(Parcel,int)}, and * {@link android.view.DragEvent#toString()} methods always return valid data. * </p> */ public class DragEvent implements Parcelable { private static final boolean TRACK_RECYCLED_LOCATION = false; Loading @@ -42,87 +135,111 @@ public class DragEvent implements Parcelable { private static DragEvent gRecyclerTop = null; /** * Action constant returned by {@link #getAction()}. Delivery of a DragEvent whose * action is ACTION_DRAG_STARTED means that a drag operation has been initiated. The * view receiving this DragEvent should inspect the metadata of the dragged content, * available via {@link #getClipDescription()}, and return {@code true} from * {@link View#onDragEvent(DragEvent)} if the view is prepared to accept a drop of * that clip data. If the view chooses to present a visual indication that it is * a valid target of the ongoing drag, then it should draw that indication in response * to this event. * Action constant returned by {@link #getAction()}: Signals the start of a * drag and drop operation. The View should return {@code true} from its * {@link View#onDragEvent(DragEvent) onDragEvent()} handler method or * {@link View.View.OnDragListener#onDrag(View,DragEvent) OnDragListener.onDrag()} listener * if it can accept a drop. The onDragEvent() or onDrag() methods usually inspect the metadata * from {@link #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. * <p> * A view will only receive ACTION_DRAG_ENTERED, ACTION_DRAG_LOCATION, ACTION_DRAG_EXITED, * and ACTION_DRAG_LOCATION events if it returns {@code true} in response to the * ACTION_DRAG_STARTED event. * A View only receives further drag events if it returns {@code true} in response to * ACTION_DRAG_STARTED. * </p> * @see #ACTION_DRAG_ENDED */ public static final int ACTION_DRAG_STARTED = 1; /** * Action constant returned by {@link #getAction()}. Delivery of a DragEvent whose * action is ACTION_DRAG_LOCATION means that the drag operation is currently hovering * over the view. The {@link #getX()} and {@link #getY()} methods supply the location * of the drag point within the view's coordinate system. * Action constant returned by {@link #getAction()}: Sent to a View after * {@link #ACTION_DRAG_ENTERED} if the drag shadow is still within the View object's bounding * box. The {@link #getX()} and {@link #getY()} methods supply * the X and Y position of of the drag point within the View object's bounding box. * <p> * A view will receive an ACTION_DRAG_ENTERED event before receiving any * ACTION_DRAG_LOCATION events. If the drag point leaves the view, then an * ACTION_DRAG_EXITED event is delivered to the view, after which no more * ACTION_DRAG_LOCATION events will be sent (unless the drag re-enters the view, * of course). * A View receives an {@link #ACTION_DRAG_ENTERED} event before receiving any * ACTION_DRAG_LOCATION events. * </p> * <p> * 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. * </p> * @see #ACTION_DRAG_ENTERED * @see #getX() * @see #getY() */ public static final int ACTION_DRAG_LOCATION = 2; /** * Action constant returned by {@link #getAction()}. Delivery of a DragEvent whose * action is ACTION_DROP means that the dragged content has been dropped on this view. * The view should retrieve the content via {@link #getClipData()} and act on it * appropriately. The {@link #getX()} and {@link #getY()} methods supply the location * of the drop point within the view's coordinate system. * Action constant returned by {@link #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 {@link #getClipData()}. * The methods {@link #getX()} and {@link #getY()} return the X and Y position of the drop point * within the View object's bounding box. * <p> * The View should return {@code true} from its {@link View#onDragEvent(DragEvent)} * handler or {@link View.View.OnDragListener#onDrag(View,DragEvent) OnDragListener.onDrag()} * listener if it accepted the drop, and {@code false} if it ignored the drop. * </p> * <p> * The view should return {@code true} from its {@link View#onDragEvent(DragEvent)} * method in response to this event if it accepted the content, and {@code false} * if it ignored the drop. * The View can also react to this action by changing its appearance. * </p> * @see #getClipData() * @see #getX() * @see #getY() */ public static final int ACTION_DROP = 3; /** * Action constant returned by {@link #getAction()}. Delivery of a DragEvent whose * action is ACTION_DRAG_ENDED means that the drag operation has concluded. A view * that is drawing a visual indication of drag acceptance should return to its usual * drawing state in response to this event. * Action constant returned by {@link #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. * <p> * 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. * ACTION_DRAG_ENDED event even if they are not currently visible when the drag ends. * </p> * <p> * The View object can call {@link #getResult()} to see the result of the operation. * If a View returned {@code true} in response to {@link #ACTION_DROP}, then * getResult() returns {@code true}, otherwise it returns {@code false}. * </p> * @see #ACTION_DRAG_STARTED * @see #getResult() */ public static final int ACTION_DRAG_ENDED = 4; /** * Action constant returned by {@link #getAction()}. Delivery of a DragEvent whose * action is ACTION_DRAG_ENTERED means that the drag point has entered the view's * bounds. If the view changed its visual state in response to the ACTION_DRAG_ENTERED * event, it should return to its normal drag-in-progress visual state in response to * this event. * Action constant returned by {@link #getAction()}: Signals to a View that the drag point has * entered the bounding box of the View. * <p> * A view will receive an ACTION_DRAG_ENTERED event before receiving any * ACTION_DRAG_LOCATION events. If the drag point leaves the view, then an * ACTION_DRAG_EXITED event is delivered to the view, after which no more * ACTION_DRAG_LOCATION events will be sent (unless the drag re-enters the view, * of course). * 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. * </p> * 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. * </p> * @see #ACTION_DRAG_ENTERED * @see #ACTION_DRAG_LOCATION */ public static final int ACTION_DRAG_ENTERED = 5; /** * Action constant returned by {@link #getAction()}. Delivery of a DragEvent whose * action is ACTION_DRAG_ENTERED means that the drag point has entered the view's * bounds. If the view chooses to present a visual indication that it will receive * the drop if it occurs now, then it should draw that indication in response to * this event. * Action constant returned by {@link #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. * <p> * A view will receive an ACTION_DRAG_ENTERED event before receiving any * ACTION_DRAG_LOCATION events. If the drag point leaves the view, then an * ACTION_DRAG_EXITED event is delivered to the view, after which no more * ACTION_DRAG_LOCATION events will be sent (unless the drag re-enters the view, * of course). * 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. * </p> * */ public static final int ACTION_DRAG_EXITED = 6; Loading Loading @@ -175,64 +292,101 @@ public static final int ACTION_DRAG_EXITED = 6; /** * Inspect the action value of this event. * @return One of {@link #ACTION_DRAG_STARTED}, {@link #ACTION_DRAG_ENDED}, * {@link #ACTION_DROP}, {@link #ACTION_DRAG_ENTERED}, {@link #ACTION_DRAG_EXITED}, * or {@link #ACTION_DRAG_LOCATION}. * @return One of the following action constants, in the order in which they usually occur * during a drag and drop operation: * <ul> * <li>{@link #ACTION_DRAG_STARTED}</li> * <li>{@link #ACTION_DRAG_ENTERED}</li> * <li>{@link #ACTION_DRAG_LOCATION}</li> * <li>{@link #ACTION_DROP}</li> * <li>{@link #ACTION_DRAG_EXITED}</li> * <li>{@link #ACTION_DRAG_ENDED}</li> * </ul> */ public int getAction() { return mAction; } /** * For ACTION_DRAG_LOCATION and ACTION_DROP events, returns the x coordinate of the * drag point. * @return The current drag point's x coordinate, when relevant. * Gets the X coordinate of the drag point. The value is only valid if the event action is * {@link #ACTION_DRAG_LOCATION} or {@link #ACTION_DROP}. * @return The current drag point's Y coordinate */ public float getX() { return mX; } /** * For ACTION_DRAG_LOCATION and ACTION_DROP events, returns the y coordinate of the * drag point. * @return The current drag point's y coordinate, when relevant. * Gets the Y coordinate of the drag point. The value is valid if the * event action is {@link #ACTION_DRAG_ENTERED}, {@link #ACTION_DRAG_LOCATION}, * {@link #ACTION_DROP}, or {@link #ACTION_DRAG_EXITED}. * @return The current drag point's Y coordinate */ public float getY() { return mY; } /** * Provides the data payload of the drag operation. This payload is only available * for events whose action value is ACTION_DROP. * @return The ClipData containing the data being dropped on the view. * Returns the {@link android.content.ClipData} object sent to the system as part of the call * to * {@link android.view.View#startDrag(ClipData,View.DragShadowBuilder,Object,int) startDrag()}. * This method only returns valid data if the event action is {@link #ACTION_DROP}. * @return The ClipData sent to the system by startDrag(). */ public ClipData getClipData() { return mClipData; } /** * Provides a description of the drag operation's data payload. This payload is * available for all DragEvents other than ACTION_DROP. * @return A ClipDescription describing the contents of the data being dragged. * Returns the {@link android.content.ClipDescription} object contained in the * {@link android.content.ClipData} object sent to the system as part of the call to * {@link android.view.View#startDrag(ClipData,View.DragShadowBuilder,Object,int) 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. * <p> * This method returns valid data for all event actions. * @return The ClipDescription that was part of the ClipData sent to the system by startDrag(). */ public ClipDescription getClipDescription() { return mClipDescription; } /** * Provides the local state object passed as the {@code myLocalState} parameter to * View.startDrag(). The object will always be null here if the application receiving * the DragEvent is not the one that started the drag. * Returns the local state object sent to the system as part of the call to * {@link android.view.View#startDrag(ClipData,View.DragShadowBuilder,Object,int) 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. * <p> * This method returns valid data for all event actions. * </p> * @return The local state object sent to the system by startDrag(). */ public Object getLocalState() { return mLocalState; } /** * Provides an indication of whether the drag operation concluded successfully. * This method is only available on ACTION_DRAG_ENDED events. * @return {@code true} if the drag operation ended with an accepted drop; {@code false} * otherwise. * <p> * Returns an indication of the result of the drag and drop operation. * This method only returns valid data if the action type is {@link #ACTION_DRAG_ENDED}. * The return value depends on what happens after the user releases the drag shadow. * </p> * <p> * If the user releases the drag shadow on a View that can accept a drop, the system sends an * {@link #ACTION_DROP} event to the View object's drag event listener. If the listener * returns {@code true}, then getResult() will return {@code true}. * If the listener returns {@code false}, then getResult() returns {@code false}. * </p> * <p> * Notice that getResult() also returns {@code false} if no {@link #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 {@link #ACTION_DRAG_ENDED} for the current * operation, but never sends out {@link #ACTION_DROP}. * </p> * @return {@code true} if a drag event listener returned {@code true} in response to * {@link #ACTION_DROP}. If the system did not send {@link #ACTION_DROP} before * {@link #ACTION_DRAG_ENDED}, or if the listener returned {@code false} in response to * {@link #ACTION_DROP}, then {@code false} is returned. */ public boolean getResult() { return mDragResult; Loading Loading @@ -271,6 +425,11 @@ public static final int ACTION_DRAG_EXITED = 6; } } /** * Returns a string containing a concise, human-readable representation of this DragEvent * object. * @return A string representation of the DragEvent object. */ @Override public String toString() { return "DragEvent{" + Integer.toHexString(System.identityHashCode(this)) Loading @@ -281,10 +440,20 @@ public static final int ACTION_DRAG_EXITED = 6; /* Parcelable interface */ /** * Returns information about the {@link android.os.Parcel} representation of this DragEvent * object. * @return Information about the {@link android.os.Parcel} representation. */ public int describeContents() { return 0; } /** * Creates a {@link android.os.Parcel} object from this DragEvent object. * @param dest A {@link android.os.Parcel} object in which to put the DragEvent object. * @param flags Flags to store in the Parcel. */ public void writeToParcel(Parcel dest, int flags) { dest.writeInt(mAction); dest.writeFloat(mX); Loading @@ -304,6 +473,9 @@ public static final int ACTION_DRAG_EXITED = 6; } } /** * A container for creating a DragEvent from a Parcel. */ public static final Parcelable.Creator<DragEvent> CREATOR = new Parcelable.Creator<DragEvent>() { public DragEvent createFromParcel(Parcel in) { Loading core/java/android/view/View.java +256 −216 File changed.Preview size limit exceeded, changes collapsed. Show changes Loading
core/java/android/view/DragEvent.java +250 −78 Original line number Diff line number Diff line Loading @@ -21,7 +21,100 @@ import android.content.ClipDescription; import android.os.Parcel; import android.os.Parcelable; /** !!! TODO: real docs */ //TODO: Improve Javadoc /** * 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. * <p> * View objects that receive a DragEvent call {@link #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 {@link #ACTION_DRAG_ENTERED} action type by * by changing one or more colors in its displayed image. * </p> * <p> * 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. * </p> * <p> * Most methods return valid data only for certain event actions. This is summarized in the * following table. Each possible {@link #getAction()} value is listed in the first column. The * other columns indicate which method or methods return valid data for that getAction() value: * </p> * <table> * <tr> * <th scope="col">getAction() Value</th> * <th scope="col">getClipDescription()</th> * <th scope="col">getLocalState()</th> * <th scope="col">getX()</th> * <th scope="col">getY()</th> * <th scope="col">getClipData()</th> * <th scope="col">getResult()</th> * </tr> * <tr> * <td>ACTION_DRAG_STARTED</td> * <td style="text-align: center;">X</td> * <td style="text-align: center;">X</td> * <td style="text-align: center;">X</td> * <td style="text-align: center;">X</td> * <td style="text-align: center;"> </td> * <td style="text-align: center;"> </td> * </tr> * <tr> * <td>ACTION_DRAG_ENTERED</td> * <td style="text-align: center;">X</td> * <td style="text-align: center;">X</td> * <td style="text-align: center;"> </td> * <td style="text-align: center;"> </td> * <td style="text-align: center;"> </td> * <td style="text-align: center;"> </td> * </tr> * <tr> * <td>ACTION_DRAG_LOCATION</td> * <td style="text-align: center;">X</td> * <td style="text-align: center;">X</td> * <td style="text-align: center;">X</td> * <td style="text-align: center;">X</td> * <td style="text-align: center;"> </td> * <td style="text-align: center;"> </td> * </tr> * <tr> * <td>ACTION_DRAG_EXITED</td> * <td style="text-align: center;">X</td> * <td style="text-align: center;">X</td> * <td style="text-align: center;"> </td> * <td style="text-align: center;"> </td> * <td style="text-align: center;"> </td> * <td style="text-align: center;"> </td> * </tr> * <tr> * <td>ACTION_DROP</td> * <td style="text-align: center;">X</td> * <td style="text-align: center;">X</td> * <td style="text-align: center;">X</td> * <td style="text-align: center;">X</td> * <td style="text-align: center;">X</td> * <td style="text-align: center;"> </td> * </tr> * <tr> * <td>ACTION_DRAG_ENDED</td> * <td style="text-align: center;">X</td> * <td style="text-align: center;">X</td> * <td style="text-align: center;"> </td> * <td style="text-align: center;"> </td> * <td style="text-align: center;"> </td> * <td style="text-align: center;">X</td> * </tr> * </table> * <p> * The {@link android.view.DragEvent#getAction()}, * {@link android.view.DragEvent#describeContents()}, * {@link android.view.DragEvent#writeToParcel(Parcel,int)}, and * {@link android.view.DragEvent#toString()} methods always return valid data. * </p> */ public class DragEvent implements Parcelable { private static final boolean TRACK_RECYCLED_LOCATION = false; Loading @@ -42,87 +135,111 @@ public class DragEvent implements Parcelable { private static DragEvent gRecyclerTop = null; /** * Action constant returned by {@link #getAction()}. Delivery of a DragEvent whose * action is ACTION_DRAG_STARTED means that a drag operation has been initiated. The * view receiving this DragEvent should inspect the metadata of the dragged content, * available via {@link #getClipDescription()}, and return {@code true} from * {@link View#onDragEvent(DragEvent)} if the view is prepared to accept a drop of * that clip data. If the view chooses to present a visual indication that it is * a valid target of the ongoing drag, then it should draw that indication in response * to this event. * Action constant returned by {@link #getAction()}: Signals the start of a * drag and drop operation. The View should return {@code true} from its * {@link View#onDragEvent(DragEvent) onDragEvent()} handler method or * {@link View.View.OnDragListener#onDrag(View,DragEvent) OnDragListener.onDrag()} listener * if it can accept a drop. The onDragEvent() or onDrag() methods usually inspect the metadata * from {@link #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. * <p> * A view will only receive ACTION_DRAG_ENTERED, ACTION_DRAG_LOCATION, ACTION_DRAG_EXITED, * and ACTION_DRAG_LOCATION events if it returns {@code true} in response to the * ACTION_DRAG_STARTED event. * A View only receives further drag events if it returns {@code true} in response to * ACTION_DRAG_STARTED. * </p> * @see #ACTION_DRAG_ENDED */ public static final int ACTION_DRAG_STARTED = 1; /** * Action constant returned by {@link #getAction()}. Delivery of a DragEvent whose * action is ACTION_DRAG_LOCATION means that the drag operation is currently hovering * over the view. The {@link #getX()} and {@link #getY()} methods supply the location * of the drag point within the view's coordinate system. * Action constant returned by {@link #getAction()}: Sent to a View after * {@link #ACTION_DRAG_ENTERED} if the drag shadow is still within the View object's bounding * box. The {@link #getX()} and {@link #getY()} methods supply * the X and Y position of of the drag point within the View object's bounding box. * <p> * A view will receive an ACTION_DRAG_ENTERED event before receiving any * ACTION_DRAG_LOCATION events. If the drag point leaves the view, then an * ACTION_DRAG_EXITED event is delivered to the view, after which no more * ACTION_DRAG_LOCATION events will be sent (unless the drag re-enters the view, * of course). * A View receives an {@link #ACTION_DRAG_ENTERED} event before receiving any * ACTION_DRAG_LOCATION events. * </p> * <p> * 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. * </p> * @see #ACTION_DRAG_ENTERED * @see #getX() * @see #getY() */ public static final int ACTION_DRAG_LOCATION = 2; /** * Action constant returned by {@link #getAction()}. Delivery of a DragEvent whose * action is ACTION_DROP means that the dragged content has been dropped on this view. * The view should retrieve the content via {@link #getClipData()} and act on it * appropriately. The {@link #getX()} and {@link #getY()} methods supply the location * of the drop point within the view's coordinate system. * Action constant returned by {@link #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 {@link #getClipData()}. * The methods {@link #getX()} and {@link #getY()} return the X and Y position of the drop point * within the View object's bounding box. * <p> * The View should return {@code true} from its {@link View#onDragEvent(DragEvent)} * handler or {@link View.View.OnDragListener#onDrag(View,DragEvent) OnDragListener.onDrag()} * listener if it accepted the drop, and {@code false} if it ignored the drop. * </p> * <p> * The view should return {@code true} from its {@link View#onDragEvent(DragEvent)} * method in response to this event if it accepted the content, and {@code false} * if it ignored the drop. * The View can also react to this action by changing its appearance. * </p> * @see #getClipData() * @see #getX() * @see #getY() */ public static final int ACTION_DROP = 3; /** * Action constant returned by {@link #getAction()}. Delivery of a DragEvent whose * action is ACTION_DRAG_ENDED means that the drag operation has concluded. A view * that is drawing a visual indication of drag acceptance should return to its usual * drawing state in response to this event. * Action constant returned by {@link #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. * <p> * 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. * ACTION_DRAG_ENDED event even if they are not currently visible when the drag ends. * </p> * <p> * The View object can call {@link #getResult()} to see the result of the operation. * If a View returned {@code true} in response to {@link #ACTION_DROP}, then * getResult() returns {@code true}, otherwise it returns {@code false}. * </p> * @see #ACTION_DRAG_STARTED * @see #getResult() */ public static final int ACTION_DRAG_ENDED = 4; /** * Action constant returned by {@link #getAction()}. Delivery of a DragEvent whose * action is ACTION_DRAG_ENTERED means that the drag point has entered the view's * bounds. If the view changed its visual state in response to the ACTION_DRAG_ENTERED * event, it should return to its normal drag-in-progress visual state in response to * this event. * Action constant returned by {@link #getAction()}: Signals to a View that the drag point has * entered the bounding box of the View. * <p> * A view will receive an ACTION_DRAG_ENTERED event before receiving any * ACTION_DRAG_LOCATION events. If the drag point leaves the view, then an * ACTION_DRAG_EXITED event is delivered to the view, after which no more * ACTION_DRAG_LOCATION events will be sent (unless the drag re-enters the view, * of course). * 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. * </p> * 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. * </p> * @see #ACTION_DRAG_ENTERED * @see #ACTION_DRAG_LOCATION */ public static final int ACTION_DRAG_ENTERED = 5; /** * Action constant returned by {@link #getAction()}. Delivery of a DragEvent whose * action is ACTION_DRAG_ENTERED means that the drag point has entered the view's * bounds. If the view chooses to present a visual indication that it will receive * the drop if it occurs now, then it should draw that indication in response to * this event. * Action constant returned by {@link #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. * <p> * A view will receive an ACTION_DRAG_ENTERED event before receiving any * ACTION_DRAG_LOCATION events. If the drag point leaves the view, then an * ACTION_DRAG_EXITED event is delivered to the view, after which no more * ACTION_DRAG_LOCATION events will be sent (unless the drag re-enters the view, * of course). * 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. * </p> * */ public static final int ACTION_DRAG_EXITED = 6; Loading Loading @@ -175,64 +292,101 @@ public static final int ACTION_DRAG_EXITED = 6; /** * Inspect the action value of this event. * @return One of {@link #ACTION_DRAG_STARTED}, {@link #ACTION_DRAG_ENDED}, * {@link #ACTION_DROP}, {@link #ACTION_DRAG_ENTERED}, {@link #ACTION_DRAG_EXITED}, * or {@link #ACTION_DRAG_LOCATION}. * @return One of the following action constants, in the order in which they usually occur * during a drag and drop operation: * <ul> * <li>{@link #ACTION_DRAG_STARTED}</li> * <li>{@link #ACTION_DRAG_ENTERED}</li> * <li>{@link #ACTION_DRAG_LOCATION}</li> * <li>{@link #ACTION_DROP}</li> * <li>{@link #ACTION_DRAG_EXITED}</li> * <li>{@link #ACTION_DRAG_ENDED}</li> * </ul> */ public int getAction() { return mAction; } /** * For ACTION_DRAG_LOCATION and ACTION_DROP events, returns the x coordinate of the * drag point. * @return The current drag point's x coordinate, when relevant. * Gets the X coordinate of the drag point. The value is only valid if the event action is * {@link #ACTION_DRAG_LOCATION} or {@link #ACTION_DROP}. * @return The current drag point's Y coordinate */ public float getX() { return mX; } /** * For ACTION_DRAG_LOCATION and ACTION_DROP events, returns the y coordinate of the * drag point. * @return The current drag point's y coordinate, when relevant. * Gets the Y coordinate of the drag point. The value is valid if the * event action is {@link #ACTION_DRAG_ENTERED}, {@link #ACTION_DRAG_LOCATION}, * {@link #ACTION_DROP}, or {@link #ACTION_DRAG_EXITED}. * @return The current drag point's Y coordinate */ public float getY() { return mY; } /** * Provides the data payload of the drag operation. This payload is only available * for events whose action value is ACTION_DROP. * @return The ClipData containing the data being dropped on the view. * Returns the {@link android.content.ClipData} object sent to the system as part of the call * to * {@link android.view.View#startDrag(ClipData,View.DragShadowBuilder,Object,int) startDrag()}. * This method only returns valid data if the event action is {@link #ACTION_DROP}. * @return The ClipData sent to the system by startDrag(). */ public ClipData getClipData() { return mClipData; } /** * Provides a description of the drag operation's data payload. This payload is * available for all DragEvents other than ACTION_DROP. * @return A ClipDescription describing the contents of the data being dragged. * Returns the {@link android.content.ClipDescription} object contained in the * {@link android.content.ClipData} object sent to the system as part of the call to * {@link android.view.View#startDrag(ClipData,View.DragShadowBuilder,Object,int) 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. * <p> * This method returns valid data for all event actions. * @return The ClipDescription that was part of the ClipData sent to the system by startDrag(). */ public ClipDescription getClipDescription() { return mClipDescription; } /** * Provides the local state object passed as the {@code myLocalState} parameter to * View.startDrag(). The object will always be null here if the application receiving * the DragEvent is not the one that started the drag. * Returns the local state object sent to the system as part of the call to * {@link android.view.View#startDrag(ClipData,View.DragShadowBuilder,Object,int) 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. * <p> * This method returns valid data for all event actions. * </p> * @return The local state object sent to the system by startDrag(). */ public Object getLocalState() { return mLocalState; } /** * Provides an indication of whether the drag operation concluded successfully. * This method is only available on ACTION_DRAG_ENDED events. * @return {@code true} if the drag operation ended with an accepted drop; {@code false} * otherwise. * <p> * Returns an indication of the result of the drag and drop operation. * This method only returns valid data if the action type is {@link #ACTION_DRAG_ENDED}. * The return value depends on what happens after the user releases the drag shadow. * </p> * <p> * If the user releases the drag shadow on a View that can accept a drop, the system sends an * {@link #ACTION_DROP} event to the View object's drag event listener. If the listener * returns {@code true}, then getResult() will return {@code true}. * If the listener returns {@code false}, then getResult() returns {@code false}. * </p> * <p> * Notice that getResult() also returns {@code false} if no {@link #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 {@link #ACTION_DRAG_ENDED} for the current * operation, but never sends out {@link #ACTION_DROP}. * </p> * @return {@code true} if a drag event listener returned {@code true} in response to * {@link #ACTION_DROP}. If the system did not send {@link #ACTION_DROP} before * {@link #ACTION_DRAG_ENDED}, or if the listener returned {@code false} in response to * {@link #ACTION_DROP}, then {@code false} is returned. */ public boolean getResult() { return mDragResult; Loading Loading @@ -271,6 +425,11 @@ public static final int ACTION_DRAG_EXITED = 6; } } /** * Returns a string containing a concise, human-readable representation of this DragEvent * object. * @return A string representation of the DragEvent object. */ @Override public String toString() { return "DragEvent{" + Integer.toHexString(System.identityHashCode(this)) Loading @@ -281,10 +440,20 @@ public static final int ACTION_DRAG_EXITED = 6; /* Parcelable interface */ /** * Returns information about the {@link android.os.Parcel} representation of this DragEvent * object. * @return Information about the {@link android.os.Parcel} representation. */ public int describeContents() { return 0; } /** * Creates a {@link android.os.Parcel} object from this DragEvent object. * @param dest A {@link android.os.Parcel} object in which to put the DragEvent object. * @param flags Flags to store in the Parcel. */ public void writeToParcel(Parcel dest, int flags) { dest.writeInt(mAction); dest.writeFloat(mX); Loading @@ -304,6 +473,9 @@ public static final int ACTION_DRAG_EXITED = 6; } } /** * A container for creating a DragEvent from a Parcel. */ public static final Parcelable.Creator<DragEvent> CREATOR = new Parcelable.Creator<DragEvent>() { public DragEvent createFromParcel(Parcel in) { Loading
core/java/android/view/View.java +256 −216 File changed.Preview size limit exceeded, changes collapsed. Show changes
