Java tutorial
/* * Copyright (C) 2010 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package android.view; import android.annotation.UnsupportedAppUsage; import android.content.ClipData; import android.content.ClipDescription; import android.os.Parcel; import android.os.Parcelable; import com.android.internal.view.IDragAndDropPermissions; //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 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;"> </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#getLocalState()} * {@link android.view.DragEvent#describeContents()}, * {@link android.view.DragEvent#writeToParcel(Parcel,int)}, and * {@link android.view.DragEvent#toString()} methods always return valid data. * </p> * * <div class="special reference"> * <h3>Developer Guides</h3> * <p>For a guide to implementing drag and drop features, read the * <a href="{@docRoot}guide/topics/ui/drag-drop.html">Drag and Drop</a> developer guide.</p> * </div> */ public class DragEvent implements Parcelable { private static final boolean TRACK_RECYCLED_LOCATION = false; int mAction; float mX, mY; @UnsupportedAppUsage ClipDescription mClipDescription; @UnsupportedAppUsage ClipData mClipData; IDragAndDropPermissions mDragAndDropPermissions; Object mLocalState; boolean mDragResult; boolean mEventHandlerWasCalled; private DragEvent mNext; private RuntimeException mRecycledLocation; private boolean mRecycled; private static final int MAX_RECYCLED = 10; private static final Object gRecyclerLock = new Object(); private static int gRecyclerUsed = 0; private static DragEvent gRecyclerTop = null; /** * 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.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 data. * If the View wants to indicate that it is a valid drop target, it can also react by * changing its appearance. * <p> * Views added or becoming visible for the first time during a drag operation receive this * event when they are added or becoming visible. * </p> * <p> * A View only receives further drag events for the drag operation if it returns {@code true} * in response to ACTION_DRAG_STARTED. * </p> * @see #ACTION_DRAG_ENDED * @see #getX() * @see #getY() */ public static final int ACTION_DRAG_STARTED = 1; /** * Action constant returned by {@link #getAction()}: Sent to a View after * {@link #ACTION_DRAG_ENTERED} while the drag shadow is still within the View object's bounding * box, but not within a descendant view that can accept the data. 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 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 or into a descendant view that can accept * the data. If the user moves the drag shadow back into the View object's bounding box or out * of a descendant view that can accept the data, 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()}: Signals to a View that the user * has released the drag shadow, and the drag point is within the bounding box of the View and * not within a descendant view that can accept the data. * 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.OnDragListener#onDrag(View,DragEvent) OnDragListener.onDrag()} * listener if it accepted the drop, and {@code false} if it ignored the drop. * </p> * <p> * 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()}: 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 with listeners that returned boolean <code>true</code> for the ACTION_DRAG_STARTED * event will receive the ACTION_DRAG_ENDED event even if they are not currently visible when * the drag ends. Views removed during the drag operation won't receive the ACTION_DRAG_ENDED * event. * </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()}: Signals to a View that the drag point has * entered the bounding box of the View. * <p> * 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 or into a descendant view that can accept * the data. If the user moves the drag shadow back into the View object's bounding box or out * of a descendant view that can accept the data, 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()}: Signals that the user has moved the * drag shadow out of the bounding box of the View or into a descendant view that can accept * the data. * 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> * 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; private DragEvent() { } private void init(int action, float x, float y, ClipDescription description, ClipData data, IDragAndDropPermissions dragAndDropPermissions, Object localState, boolean result) { mAction = action; mX = x; mY = y; mClipDescription = description; mClipData = data; this.mDragAndDropPermissions = dragAndDropPermissions; mLocalState = localState; mDragResult = result; } static DragEvent obtain() { return DragEvent.obtain(0, 0f, 0f, null, null, null, null, false); } /** @hide */ public static DragEvent obtain(int action, float x, float y, Object localState, ClipDescription description, ClipData data, IDragAndDropPermissions dragAndDropPermissions, boolean result) { final DragEvent ev; synchronized (gRecyclerLock) { if (gRecyclerTop == null) { ev = new DragEvent(); ev.init(action, x, y, description, data, dragAndDropPermissions, localState, result); return ev; } ev = gRecyclerTop; gRecyclerTop = ev.mNext; gRecyclerUsed -= 1; } ev.mRecycledLocation = null; ev.mRecycled = false; ev.mNext = null; ev.init(action, x, y, description, data, dragAndDropPermissions, localState, result); return ev; } /** @hide */ @UnsupportedAppUsage public static DragEvent obtain(DragEvent source) { return obtain(source.mAction, source.mX, source.mY, source.mLocalState, source.mClipDescription, source.mClipData, source.mDragAndDropPermissions, source.mDragResult); } /** * Inspect the action value of this event. * @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; } /** * Gets the X coordinate of the drag point. The value is only valid if the event action is * {@link #ACTION_DRAG_STARTED}, {@link #ACTION_DRAG_LOCATION} or {@link #ACTION_DROP}. * @return The current drag point's X coordinate */ public float getX() { return mX; } /** * Gets the Y coordinate of the drag point. The value is only valid if the event action is * {@link #ACTION_DRAG_STARTED}, {@link #ACTION_DRAG_LOCATION} or {@link #ACTION_DROP}. * @return The current drag point's Y coordinate */ public float getY() { return mY; } /** * Returns the {@link android.content.ClipData} object sent to the system as part of the call * to * {@link android.view.View#startDragAndDrop(ClipData,View.DragShadowBuilder,Object,int) * startDragAndDrop()}. * This method only returns valid data if the event action is {@link #ACTION_DROP}. * @return The ClipData sent to the system by startDragAndDrop(). */ public ClipData getClipData() { return mClipData; } /** * 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#startDragAndDrop(ClipData,View.DragShadowBuilder,Object,int) * startDragAndDrop()}. * 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 except for {@link #ACTION_DRAG_ENDED}. * @return The ClipDescription that was part of the ClipData sent to the system by * startDragAndDrop(). */ public ClipDescription getClipDescription() { return mClipDescription; } /** @hide */ public IDragAndDropPermissions getDragAndDropPermissions() { return mDragAndDropPermissions; } /** * Returns the local state object sent to the system as part of the call to * {@link android.view.View#startDragAndDrop(ClipData,View.DragShadowBuilder,Object,int) * startDragAndDrop()}. * 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> * The local state is available only to views in the activity which has started the drag * operation. In all other activities this method will return null * </p> * <p> * This method returns valid data for all event actions. * </p> * @return The local state object sent to the system by startDragAndDrop(). */ public Object getLocalState() { return mLocalState; } /** * <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; } /** * Recycle the DragEvent, to be re-used by a later caller. After calling * this function you must never touch the event again. * * @hide */ public final void recycle() { // Ensure recycle is only called once! if (TRACK_RECYCLED_LOCATION) { if (mRecycledLocation != null) { throw new RuntimeException(toString() + " recycled twice!", mRecycledLocation); } mRecycledLocation = new RuntimeException("Last recycled here"); } else { if (mRecycled) { throw new RuntimeException(toString() + " recycled twice!"); } mRecycled = true; } mClipData = null; mClipDescription = null; mLocalState = null; mEventHandlerWasCalled = false; synchronized (gRecyclerLock) { if (gRecyclerUsed < MAX_RECYCLED) { gRecyclerUsed++; mNext = gRecyclerTop; gRecyclerTop = this; } } } /** * 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)) + " action=" + mAction + " @ (" + mX + ", " + mY + ") desc=" + mClipDescription + " data=" + mClipData + " local=" + mLocalState + " result=" + mDragResult + "}"; } /* 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); dest.writeFloat(mY); dest.writeInt(mDragResult ? 1 : 0); if (mClipData == null) { dest.writeInt(0); } else { dest.writeInt(1); mClipData.writeToParcel(dest, flags); } if (mClipDescription == null) { dest.writeInt(0); } else { dest.writeInt(1); mClipDescription.writeToParcel(dest, flags); } if (mDragAndDropPermissions == null) { dest.writeInt(0); } else { dest.writeInt(1); dest.writeStrongBinder(mDragAndDropPermissions.asBinder()); } } /** * 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) { DragEvent event = DragEvent.obtain(); event.mAction = in.readInt(); event.mX = in.readFloat(); event.mY = in.readFloat(); event.mDragResult = (in.readInt() != 0); if (in.readInt() != 0) { event.mClipData = ClipData.CREATOR.createFromParcel(in); } if (in.readInt() != 0) { event.mClipDescription = ClipDescription.CREATOR.createFromParcel(in); } if (in.readInt() != 0) { event.mDragAndDropPermissions = IDragAndDropPermissions.Stub.asInterface(in.readStrongBinder()); ; } return event; } public DragEvent[] newArray(int size) { return new DragEvent[size]; } }; }