sdk doc change: Copy/Paste/Drag/Drop
Change-Id: Ifb9ed554ae1a72ce6badff1c79d95c02f30525e9
diff --git a/core/java/android/view/DragEvent.java b/core/java/android/view/DragEvent.java
index 4d83891..8f491ef 100644
--- a/core/java/android/view/DragEvent.java
+++ b/core/java/android/view/DragEvent.java
@@ -21,7 +21,100 @@
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;
@@ -42,89 +135,113 @@
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)}
- * method in response to this event if it accepted the content, and {@code false}
- * if it ignored the drop.
+ * 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 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;
+ public static final int ACTION_DRAG_EXITED = 6;
private DragEvent() {
}
@@ -175,64 +292,101 @@
/**
* 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;
@@ -271,6 +425,11 @@
}
}
+ /**
+ * 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))
@@ -281,10 +440,20 @@
/* 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);
@@ -304,6 +473,9 @@
}
}
+ /**
+ * 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) {
diff --git a/core/java/android/view/View.java b/core/java/android/view/View.java
index 5e8f31a..76814c2 100644
--- a/core/java/android/view/View.java
+++ b/core/java/android/view/View.java
@@ -521,7 +521,7 @@
* The framework provides basic support for views that wish to internally
* scroll their content. This includes keeping track of the X and Y scroll
* offset as well as mechanisms for drawing scrollbars. See
- * {@link #scrollBy(int, int)}, {@link #scrollTo(int, int)}, and
+ * {@link #scrollBy(int, int)}, {@link #scrollTo(int, int)}, and
* {@link #awakenScrollBars()} for more details.
* </p>
*
@@ -1645,27 +1645,27 @@
* @hide
*/
static final int OPAQUE_MASK = 0x01800000;
-
+
/**
* Indicates a prepressed state;
* the short time between ACTION_DOWN and recognizing
* a 'real' press. Prepressed is used to recognize quick taps
* even when they are shorter than ViewConfiguration.getTapTimeout().
- *
+ *
* @hide
*/
private static final int PREPRESSED = 0x02000000;
-
+
/**
* Indicates whether the view is temporarily detached.
*
* @hide
*/
static final int CANCEL_NEXT_UP_EVENT = 0x04000000;
-
+
/**
* Indicates that we should awaken scroll bars once attached
- *
+ *
* @hide
*/
private static final int AWAKEN_SCROLL_BARS_ON_ATTACH = 0x08000000;
@@ -1720,14 +1720,14 @@
/**
* View has requested the status bar to be visible (the default).
*
- * @see #setSystemUiVisibility(int)
+ * @see #setSystemUiVisibility(int)
*/
public static final int STATUS_BAR_VISIBLE = 0;
/**
* View has requested the status bar to be visible (the default).
*
- * @see #setSystemUiVisibility(int)
+ * @see #setSystemUiVisibility(int)
*/
public static final int STATUS_BAR_HIDDEN = 0x00000001;
@@ -1854,8 +1854,8 @@
private int mPrevWidth = -1;
private int mPrevHeight = -1;
- private boolean mLastIsOpaque;
-
+ private boolean mLastIsOpaque;
+
/**
* Convenience value to check for float values that are close enough to zero to be considered
* zero.
@@ -2129,7 +2129,7 @@
private CheckForLongPress mPendingCheckForLongPress;
private CheckForTap mPendingCheckForTap = null;
private PerformClick mPerformClick;
-
+
private UnsetPressedState mUnsetPressedState;
/**
@@ -2170,7 +2170,7 @@
* Special tree observer used when mAttachInfo is null.
*/
private ViewTreeObserver mFloatingTreeObserver;
-
+
/**
* Cache the touch slop from the context that created the view.
*/
@@ -2210,11 +2210,11 @@
/**
* Indicates that the view does not have a layer.
- *
- * @see #getLayerType()
- * @see #setLayerType(int, android.graphics.Paint)
+ *
+ * @see #getLayerType()
+ * @see #setLayerType(int, android.graphics.Paint)
* @see #LAYER_TYPE_SOFTWARE
- * @see #LAYER_TYPE_HARDWARE
+ * @see #LAYER_TYPE_HARDWARE
*/
public static final int LAYER_TYPE_NONE = 0;
@@ -2222,7 +2222,7 @@
* <p>Indicates that the view has a software layer. A software layer is backed
* by a bitmap and causes the view to be rendered using Android's software
* rendering pipeline, even if hardware acceleration is enabled.</p>
- *
+ *
* <p>Software layers have various usages:</p>
* <p>When the application is not using hardware acceleration, a software layer
* is useful to apply a specific color filter and/or blending mode and/or
@@ -2238,11 +2238,11 @@
* potentially be slow (particularly when hardware acceleration is turned on
* since the layer will have to be uploaded into a hardware texture after every
* update.)</p>
- *
- * @see #getLayerType()
- * @see #setLayerType(int, android.graphics.Paint)
+ *
+ * @see #getLayerType()
+ * @see #setLayerType(int, android.graphics.Paint)
* @see #LAYER_TYPE_NONE
- * @see #LAYER_TYPE_HARDWARE
+ * @see #LAYER_TYPE_HARDWARE
*/
public static final int LAYER_TYPE_SOFTWARE = 1;
@@ -2253,7 +2253,7 @@
* rendering pipeline, but only if hardware acceleration is turned on for the
* view hierarchy. When hardware acceleration is turned off, hardware layers
* behave exactly as {@link #LAYER_TYPE_SOFTWARE software layers}.</p>
- *
+ *
* <p>A hardware layer is useful to apply a specific color filter and/or
* blending mode and/or translucency to a view and all its children.</p>
* <p>A hardware layer can be used to cache a complex view tree into a
@@ -2263,14 +2263,14 @@
* <p>A hardware layer can also be used to increase the rendering quality when
* rotation transformations are applied on a view. It can also be used to
* prevent potential clipping issues when applying 3D transforms on a view.</p>
- *
- * @see #getLayerType()
+ *
+ * @see #getLayerType()
* @see #setLayerType(int, android.graphics.Paint)
* @see #LAYER_TYPE_NONE
* @see #LAYER_TYPE_SOFTWARE
*/
public static final int LAYER_TYPE_HARDWARE = 2;
-
+
@ViewDebug.ExportedProperty(category = "drawing", mapping = {
@ViewDebug.IntToString(from = LAYER_TYPE_NONE, to = "NONE"),
@ViewDebug.IntToString(from = LAYER_TYPE_SOFTWARE, to = "SOFTWARE"),
@@ -2572,7 +2572,7 @@
break;
case R.styleable.View_onClick:
if (context.isRestricted()) {
- throw new IllegalStateException("The android:onClick attribute cannot "
+ throw new IllegalStateException("The android:onClick attribute cannot "
+ "be used within a restricted context");
}
@@ -2811,19 +2811,19 @@
initScrollCache();
final ScrollabilityCache scrollabilityCache = mScrollCache;
-
+
if (scrollabilityCache.scrollBar == null) {
scrollabilityCache.scrollBar = new ScrollBarDrawable();
}
-
+
final boolean fadeScrollbars = a.getBoolean(R.styleable.View_fadeScrollbars, true);
if (!fadeScrollbars) {
scrollabilityCache.state = ScrollabilityCache.ON;
}
scrollabilityCache.fadeScrollBars = fadeScrollbars;
-
-
+
+
scrollabilityCache.scrollBarFadeDuration = a.getInt(
R.styleable.View_scrollbarFadeDuration, ViewConfiguration
.getScrollBarFadeDuration());
@@ -2831,7 +2831,7 @@
R.styleable.View_scrollbarDefaultDelayBeforeFade,
ViewConfiguration.getScrollDefaultDelay());
-
+
scrollabilityCache.scrollBarSize = a.getDimensionPixelSize(
com.android.internal.R.styleable.View_scrollbarSize,
ViewConfiguration.get(mContext).getScaledScrollBarSize());
@@ -3067,8 +3067,11 @@
}
/**
- * Register a callback to be invoked when a drag event is sent to this view.
- * @param l The drag listener to attach to this view
+ * Register a drag event listener callback object for this View. The parameter is
+ * an implementation of {@link android.view.View.OnDragListener}. To send a drag event to a
+ * View, the system calls the
+ * {@link android.view.View.OnDragListener#onDrag(View,DragEvent)} method.
+ * @param l An implementation of {@link android.view.View.OnDragListener}.
*/
public void setOnDragListener(OnDragListener l) {
mOnDragListener = l;
@@ -3279,7 +3282,7 @@
if (mOnFocusChangeListener != null) {
mOnFocusChangeListener.onFocusChange(this, gainFocus);
}
-
+
if (mAttachInfo != null) {
mAttachInfo.mKeyDispatchState.reset(this);
}
@@ -4427,7 +4430,7 @@
public KeyEvent.DispatcherState getKeyDispatcherState() {
return mAttachInfo != null ? mAttachInfo.mKeyDispatchState : null;
}
-
+
/**
* Dispatch a key event before it is processed by any input method
* associated with the view hierarchy. This can be used to intercept
@@ -4505,7 +4508,7 @@
*
* @param event The motion event to be filtered.
* @return True if the event should be dispatched, false if the event should be dropped.
- *
+ *
* @see #getFilterTouchesWhenObscured
*/
public boolean onFilterTouchEventForSecurity(MotionEvent event) {
@@ -4612,7 +4615,7 @@
* a View moves out of the screen, it might receives a display hint indicating
* the view is not displayed. Applications should not <em>rely</em> on this hint
* as there is no guarantee that they will receive one.
- *
+ *
* @param hint A hint about whether or not this view is displayed:
* {@link #VISIBLE} or {@link #INVISIBLE}.
*/
@@ -4625,7 +4628,7 @@
* a View moves out of the screen, it might receives a display hint indicating
* the view is not displayed. Applications should not <em>rely</em> on this hint
* as there is no guarantee that they will receive one.
- *
+ *
* @param hint A hint about whether or not this view is displayed:
* {@link #VISIBLE} or {@link #INVISIBLE}.
*/
@@ -5078,7 +5081,7 @@
mPrivateFlags |= PRESSED;
refreshDrawableState();
}
-
+
if (!mHasPerformedLongPress) {
// This is a tap, so remove the longpress check
removeLongPressCallback();
@@ -5581,7 +5584,7 @@
/**
* Returns true if the transform matrix is the identity matrix.
* Recomputes the matrix if necessary.
- *
+ *
* @return True if the transform matrix is the identity matrix, false otherwise.
*/
final boolean hasIdentityMatrix() {
@@ -5922,16 +5925,16 @@
/**
* <p>Sets the opacity of the view. This is a value from 0 to 1, where 0 means the view is
* completely transparent and 1 means the view is completely opaque.</p>
- *
+ *
* <p>If this view overrides {@link #onSetAlpha(int)} to return true, then this view is
* responsible for applying the opacity itself. Otherwise, calling this method is
* equivalent to calling {@link #setLayerType(int, android.graphics.Paint)} and
- * setting a hardware layer.</p>
+ * setting a hardware layer.</p>
*
* @param alpha The opacity of the view.
*
- * @see #setLayerType(int, android.graphics.Paint)
- *
+ * @see #setLayerType(int, android.graphics.Paint)
+ *
* @attr ref android.R.styleable#View_alpha
*/
public void setAlpha(float alpha) {
@@ -6197,7 +6200,7 @@
/**
* The visual x position of this view, in pixels. This is equivalent to the
* {@link #setTranslationX(float) translationX} property plus the current
- * {@link #getLeft() left} property.
+ * {@link #getLeft() left} property.
*
* @return The visual x position of this view, in pixels.
*/
@@ -6594,7 +6597,7 @@
* provides animated scrolling, the start delay should equal the duration of
* the scrolling animation.
* </p>
- *
+ *
* <p>
* The animation starts only if at least one of the scrollbars is enabled,
* as specified by {@link #isHorizontalScrollBarEnabled()} and
@@ -6603,17 +6606,17 @@
* started, this method calls {@link #invalidate()}; in that case the caller
* should not call {@link #invalidate()}.
* </p>
- *
+ *
* <p>
* This method should be invoked everytime a subclass directly updates the
* scroll parameters.
* </p>
- *
+ *
* @param startDelay the delay, in milliseconds, after which the animation
* should start; when the delay is 0, the animation starts
* immediately
* @return true if the animation is played, false otherwise
- *
+ *
* @see #scrollBy(int, int)
* @see #scrollTo(int, int)
* @see #isHorizontalScrollBarEnabled()
@@ -6624,7 +6627,7 @@
protected boolean awakenScrollBars(int startDelay) {
return awakenScrollBars(startDelay, true);
}
-
+
/**
* <p>
* Trigger the scrollbars to draw. When invoked this method starts an
@@ -6632,30 +6635,30 @@
* provides animated scrolling, the start delay should equal the duration of
* the scrolling animation.
* </p>
- *
+ *
* <p>
* The animation starts only if at least one of the scrollbars is enabled,
* as specified by {@link #isHorizontalScrollBarEnabled()} and
* {@link #isVerticalScrollBarEnabled()}. When the animation is started,
* this method returns true, and false otherwise. If the animation is
- * started, this method calls {@link #invalidate()} if the invalidate parameter
+ * started, this method calls {@link #invalidate()} if the invalidate parameter
* is set to true; in that case the caller
* should not call {@link #invalidate()}.
* </p>
- *
+ *
* <p>
* This method should be invoked everytime a subclass directly updates the
* scroll parameters.
* </p>
- *
+ *
* @param startDelay the delay, in milliseconds, after which the animation
* should start; when the delay is 0, the animation starts
* immediately
- *
+ *
* @param invalidate Wheter this method should call invalidate
- *
+ *
* @return true if the animation is played, false otherwise
- *
+ *
* @see #scrollBy(int, int)
* @see #scrollTo(int, int)
* @see #isHorizontalScrollBarEnabled()
@@ -6665,7 +6668,7 @@
*/
protected boolean awakenScrollBars(int startDelay, boolean invalidate) {
final ScrollabilityCache scrollCache = mScrollCache;
-
+
if (scrollCache == null || !scrollCache.fadeScrollBars) {
return false;
}
@@ -6798,7 +6801,7 @@
public void invalidate() {
invalidate(true);
}
-
+
/**
* This is where the invalidate() work actually happens. A full invalidate()
* causes the drawing cache to be invalidated, but this function can be called with
@@ -6860,7 +6863,7 @@
((View) mParent).mPrivateFlags |= INVALIDATED;
}
}
-
+
/**
* Used to indicate that the parent of this view should be invalidated. This functionality
* is used to force the parent to rebuild its display list (when hardware-accelerated),
@@ -7289,12 +7292,12 @@
protected void recomputePadding() {
setPadding(mUserPaddingLeft, mPaddingTop, mUserPaddingRight, mUserPaddingBottom);
}
-
+
/**
* Define whether scrollbars will fade when the view is not scrolling.
- *
+ *
* @param fadeScrollbars wheter to enable fading
- *
+ *
*/
public void setScrollbarFadingEnabled(boolean fadeScrollbars) {
initScrollCache();
@@ -7306,17 +7309,17 @@
scrollabilityCache.state = ScrollabilityCache.ON;
}
}
-
+
/**
- *
+ *
* Returns true if scrollbars will fade when this view is not scrolling
- *
+ *
* @return true if scrollbar fading is enabled
*/
public boolean isScrollbarFadingEnabled() {
- return mScrollCache != null && mScrollCache.fadeScrollBars;
+ return mScrollCache != null && mScrollCache.fadeScrollBars;
}
-
+
/**
* <p>Specify the style of the scrollbars. The scrollbars can be overlaid or
* inset. When inset, they add to the padding of the view. And the scrollbars
@@ -7483,30 +7486,30 @@
* scrollbars are painted only if they have been awakened first.</p>
*
* @param canvas the canvas on which to draw the scrollbars
- *
+ *
* @see #awakenScrollBars(int)
*/
protected final void onDrawScrollBars(Canvas canvas) {
// scrollbars are drawn only when the animation is running
final ScrollabilityCache cache = mScrollCache;
if (cache != null) {
-
+
int state = cache.state;
-
+
if (state == ScrollabilityCache.OFF) {
return;
}
-
+
boolean invalidate = false;
-
+
if (state == ScrollabilityCache.FADING) {
// We're fading -- get our fade interpolation
if (cache.interpolatorValues == null) {
cache.interpolatorValues = new float[1];
}
-
+
float[] values = cache.interpolatorValues;
-
+
// Stops the animation if we're done
if (cache.scrollBarInterpolator.timeToValues(values) ==
Interpolator.Result.FREEZE_END) {
@@ -7514,8 +7517,8 @@
} else {
cache.scrollBar.setAlpha(Math.round(values[0]));
}
-
- // This will make the scroll bars inval themselves after
+
+ // This will make the scroll bars inval themselves after
// drawing. We only want this when we're fading so that
// we prevent excessive redraws
invalidate = true;
@@ -7525,7 +7528,7 @@
cache.scrollBar.setAlpha(255);
}
-
+
final int viewFlags = mViewFlags;
final boolean drawHorizontalScrollBar =
@@ -7549,14 +7552,14 @@
final int inside = (viewFlags & SCROLLBARS_OUTSIDE_MASK) == 0 ? ~0 : 0;
int left, top, right, bottom;
-
+
if (drawHorizontalScrollBar) {
scrollBar.setParameters(computeHorizontalScrollRange(),
computeHorizontalScrollOffset(),
computeHorizontalScrollExtent(), false);
final int verticalScrollBarGap = drawVerticalScrollBar ?
getVerticalScrollbarWidth() : 0;
- top = scrollY + height - size - (mUserPaddingBottom & inside);
+ top = scrollY + height - size - (mUserPaddingBottom & inside);
left = scrollX + (mPaddingLeft & inside);
right = scrollX + width - (mUserPaddingRight & inside) - verticalScrollBarGap;
bottom = top + size;
@@ -7935,8 +7938,8 @@
if (state != BaseSavedState.EMPTY_STATE && state != null) {
throw new IllegalArgumentException("Wrong state class, expecting View State but "
+ "received " + state.getClass().toString() + " instead. This usually happens "
- + "when two views of different type have the same id in the same hierarchy. "
- + "This view's id is " + ViewDebug.resolveId(mContext, getId()) + ". Make sure "
+ + "when two views of different type have the same id in the same hierarchy. "
+ + "This view's id is " + ViewDebug.resolveId(mContext, getId()) + ". Make sure "
+ "other views do not use the same id.");
}
}
@@ -7961,7 +7964,7 @@
*
* <p>Note: if this view's parent addStateFromChildren property is enabled and this
* property is enabled, an exception will be thrown.</p>
- *
+ *
* <p>Note: if the child view uses and updates additionnal states which are unknown to the
* parent, these states should not be affected by this method.</p>
*
@@ -7992,7 +7995,7 @@
* <p>Specifies the type of layer backing this view. The layer can be
* {@link #LAYER_TYPE_NONE disabled}, {@link #LAYER_TYPE_SOFTWARE software} or
* {@link #LAYER_TYPE_HARDWARE hardware}.</p>
- *
+ *
* <p>A layer is associated with an optional {@link android.graphics.Paint}
* instance that controls how the layer is composed on screen. The following
* properties of the paint are taken into account when composing the layer:</p>
@@ -8001,35 +8004,35 @@
* <li>{@link android.graphics.Paint#getXfermode() Blending mode}</li>
* <li>{@link android.graphics.Paint#getColorFilter() Color filter}</li>
* </ul>
- *
+ *
* <p>If this view has an alpha value set to < 1.0 by calling
* {@link #setAlpha(float)}, the alpha value of the layer's paint is replaced by
* this view's alpha value. Calling {@link #setAlpha(float)} is therefore
* equivalent to setting a hardware layer on this view and providing a paint with
* the desired alpha value.<p>
- *
+ *
* <p>Refer to the documentation of {@link #LAYER_TYPE_NONE disabled},
* {@link #LAYER_TYPE_SOFTWARE software} and {@link #LAYER_TYPE_HARDWARE hardware}
* for more information on when and how to use layers.</p>
- *
+ *
* @param layerType The ype of layer to use with this view, must be one of
* {@link #LAYER_TYPE_NONE}, {@link #LAYER_TYPE_SOFTWARE} or
* {@link #LAYER_TYPE_HARDWARE}
* @param paint The paint used to compose the layer. This argument is optional
* and can be null. It is ignored when the layer type is
* {@link #LAYER_TYPE_NONE}
- *
- * @see #getLayerType()
+ *
+ * @see #getLayerType()
* @see #LAYER_TYPE_NONE
* @see #LAYER_TYPE_SOFTWARE
* @see #LAYER_TYPE_HARDWARE
- * @see #setAlpha(float)
- *
+ * @see #setAlpha(float)
+ *
* @attr ref android.R.styleable#View_layerType
*/
public void setLayerType(int layerType, Paint paint) {
if (layerType < LAYER_TYPE_NONE || layerType > LAYER_TYPE_HARDWARE) {
- throw new IllegalArgumentException("Layer type can only be one of: LAYER_TYPE_NONE, "
+ throw new IllegalArgumentException("Layer type can only be one of: LAYER_TYPE_NONE, "
+ "LAYER_TYPE_SOFTWARE or LAYER_TYPE_HARDWARE");
}
@@ -8049,7 +8052,7 @@
mDrawingCache.recycle();
mDrawingCache = null;
}
-
+
if (mUnscaledDrawingCache != null) {
mUnscaledDrawingCache.recycle();
mUnscaledDrawingCache = null;
@@ -8077,11 +8080,11 @@
* a view does not have a layer, and the layer type is {@link #LAYER_TYPE_NONE}.
* Refer to the documentation of {@link #setLayerType(int, android.graphics.Paint)}
* for more information on the different types of layers.
- *
+ *
* @return {@link #LAYER_TYPE_NONE}, {@link #LAYER_TYPE_SOFTWARE} or
* {@link #LAYER_TYPE_HARDWARE}
- *
- * @see #setLayerType(int, android.graphics.Paint)
+ *
+ * @see #setLayerType(int, android.graphics.Paint)
* @see #LAYER_TYPE_NONE
* @see #LAYER_TYPE_SOFTWARE
* @see #LAYER_TYPE_HARDWARE
@@ -8089,7 +8092,7 @@
public int getLayerType() {
return mLayerType;
}
-
+
/**
* <p>Returns a hardware layer that can be used to draw this view again
* without executing its draw method.</p>
@@ -8103,7 +8106,7 @@
final int width = mRight - mLeft;
final int height = mBottom - mTop;
-
+
if (width == 0 || height == 0) {
return null;
}
@@ -8130,7 +8133,7 @@
canvas.translate(-mScrollX, -mScrollY);
mPrivateFlags |= DRAWN | DRAWING_CACHE_VALID;
-
+
// Fast path for layouts with no backgrounds
if ((mPrivateFlags & SKIP_DRAW) == SKIP_DRAW) {
mPrivateFlags &= ~DIRTY_MASK;
@@ -8138,7 +8141,7 @@
} else {
draw(canvas);
}
-
+
canvas.restoreToCount(restoreCount);
} finally {
canvas.onPostDraw();
@@ -8157,7 +8160,7 @@
* the cache is enabled. To benefit from the cache, you must request the drawing cache by
* calling {@link #getDrawingCache()} and draw it on screen if the returned bitmap is not
* null.</p>
- *
+ *
* <p>Enabling the drawing cache is similar to
* {@link #setLayerType(int, android.graphics.Paint) setting a layer} when hardware
* acceleration is turned off. When hardware acceleration is turned on, enabling the
@@ -8175,7 +8178,7 @@
* @see #isDrawingCacheEnabled()
* @see #getDrawingCache()
* @see #buildDrawingCache()
- * @see #setLayerType(int, android.graphics.Paint)
+ * @see #setLayerType(int, android.graphics.Paint)
*/
public void setDrawingCacheEnabled(boolean enabled) {
setFlags(enabled ? DRAWING_CACHE_ENABLED : 0, DRAWING_CACHE_ENABLED);
@@ -8197,7 +8200,7 @@
/**
* Debugging utility which recursively outputs the dirty state of a view and its
* descendants.
- *
+ *
* @hide
*/
public void outputDirtyFlags(String indent, boolean clear, int clearMask) {
@@ -8242,11 +8245,11 @@
}
return true;
}
-
+
/**
* <p>Returns a display list that can be used to draw this view again
* without executing its draw method.</p>
- *
+ *
* @return A DisplayList ready to replay, or null if caching is not enabled.
*
* @hide
@@ -8295,7 +8298,7 @@
computeScroll();
canvas.translate(-mScrollX, -mScrollY);
mPrivateFlags |= DRAWN | DRAWING_CACHE_VALID;
-
+
// Fast path for layouts with no backgrounds
if ((mPrivateFlags & SKIP_DRAW) == SKIP_DRAW) {
mPrivateFlags &= ~DIRTY_MASK;
@@ -8303,7 +8306,7 @@
} else {
draw(canvas);
}
-
+
canvas.restoreToCount(restoreCount);
} finally {
canvas.onPostDraw();
@@ -8320,9 +8323,9 @@
/**
* <p>Calling this method is equivalent to calling <code>getDrawingCache(false)</code>.</p>
- *
+ *
* @return A non-scaled bitmap representing this view or null if cache is disabled.
- *
+ *
* @see #getDrawingCache(boolean)
*/
public Bitmap getDrawingCache() {
@@ -8336,7 +8339,7 @@
* draw from the cache when the cache is enabled. To benefit from the cache, you must
* request the drawing cache by calling this method and draw it on screen if the
* returned bitmap is not null.</p>
- *
+ *
* <p>Note about auto scaling in compatibility mode: When auto scaling is not enabled,
* this method will create a bitmap of the same size as this view. Because this bitmap
* will be drawn scaled by the parent ViewGroup, the result on screen might show
@@ -8344,13 +8347,13 @@
* the auto scaling to true. Doing so, however, will generate a bitmap of a different
* size than the view. This implies that your application must be able to handle this
* size.</p>
- *
+ *
* @param autoScale Indicates whether the generated bitmap should be scaled based on
* the current density of the screen when the application is in compatibility
* mode.
*
* @return A bitmap representing this view or null if cache is disabled.
- *
+ *
* @see #setDrawingCacheEnabled(boolean)
* @see #isDrawingCacheEnabled()
* @see #buildDrawingCache(boolean)
@@ -8416,7 +8419,7 @@
/**
* <p>Calling this method is equivalent to calling <code>buildDrawingCache(false)</code>.</p>
- *
+ *
* @see #buildDrawingCache(boolean)
*/
public void buildDrawingCache() {
@@ -8429,7 +8432,7 @@
* <p>If you call {@link #buildDrawingCache()} manually without calling
* {@link #setDrawingCacheEnabled(boolean) setDrawingCacheEnabled(true)}, you
* should cleanup the cache by calling {@link #destroyDrawingCache()} afterwards.</p>
- *
+ *
* <p>Note about auto scaling in compatibility mode: When auto scaling is not enabled,
* this method will create a bitmap of the same size as this view. Because this bitmap
* will be drawn scaled by the parent ViewGroup, the result on screen might show
@@ -8437,10 +8440,10 @@
* the auto scaling to true. Doing so, however, will generate a bitmap of a different
* size than the view. This implies that your application must be able to handle this
* size.</p>
- *
+ *
* <p>You should avoid calling this method when hardware acceleration is enabled. If
* you do not need the drawing cache bitmap, calling this method will increase memory
- * usage and cause the view to be rendered in software once, thus negatively impacting
+ * usage and cause the view to be rendered in software once, thus negatively impacting
* performance.</p>
*
* @see #getDrawingCache()
@@ -8553,12 +8556,12 @@
computeScroll();
final int restoreCount = canvas.save();
-
+
if (autoScale && scalingRequired) {
final float scale = attachInfo.mApplicationScale;
canvas.scale(scale, scale);
}
-
+
canvas.translate(-mScrollX, -mScrollY);
mPrivateFlags |= DRAWN;
@@ -8599,14 +8602,14 @@
final float scale = attachInfo != null ? attachInfo.mApplicationScale : 1.0f;
width = (int) ((width * scale) + 0.5f);
height = (int) ((height * scale) + 0.5f);
-
+
Bitmap bitmap = Bitmap.createBitmap(width > 0 ? width : 1, height > 0 ? height : 1, quality);
if (bitmap == null) {
throw new OutOfMemoryError();
}
bitmap.setDensity(getResources().getDisplayMetrics().densityDpi);
-
+
Canvas canvas;
if (attachInfo != null) {
canvas = attachInfo.mCanvas;
@@ -8756,7 +8759,7 @@
/**
* <p>Indicates whether this view is attached to an hardware accelerated
* window or not.</p>
- *
+ *
* <p>Even if this method returns true, it does not mean that every call
* to {@link #draw(android.graphics.Canvas)} will be made with an hardware
* accelerated {@link android.graphics.Canvas}. For instance, if this view
@@ -8764,14 +8767,14 @@
* window is hardware accelerated,
* {@link android.graphics.Canvas#isHardwareAccelerated()} will likely
* return false, and this method will return true.</p>
- *
+ *
* @return True if the view is attached to a window and the window is
* hardware accelerated; false in any other case.
*/
public boolean isHardwareAccelerated() {
return mAttachInfo != null && mAttachInfo.mHardwareAccelerated;
}
-
+
/**
* Manually render this view (and all of its children) to the given Canvas.
* The view must have already done a full layout before this function is
@@ -10838,21 +10841,35 @@
}
/**
- * !!! TODO: real docs
- *
- * The base class implementation makes the shadow the same size and appearance
- * as the view itself, and positions it with its center at the touch point.
+ * Creates an image that the system displays during the drag and drop
+ * operation. This is called a "drag shadow". The default implementation
+ * for a DragShadowBuilder based on a View returns an image that has exactly the same
+ * appearance as the given View. The default also positions the center of the drag shadow
+ * directly under the touch point. If no View is provided (the constructor with no parameters
+ * is used), and {@link #onProvideShadowMetrics(Point,Point) onProvideShadowMetrics()} and
+ * {@link #onDrawShadow(Canvas) onDrawShadow()} are not overriden, then the
+ * default is an invisible drag shadow.
+ * <p>
+ * You are not required to use the View you provide to the constructor as the basis of the
+ * drag shadow. The {@link #onDrawShadow(Canvas) onDrawShadow()} method allows you to draw
+ * anything you want as the drag shadow.
+ * </p>
+ * <p>
+ * You pass a DragShadowBuilder object to the system when you start the drag. The system
+ * calls {@link #onProvideShadowMetrics(Point,Point) onProvideShadowMetrics()} to get the
+ * size and position of the drag shadow. It uses this data to construct a
+ * {@link android.graphics.Canvas} object, then it calls {@link #onDrawShadow(Canvas) onDrawShadow()}
+ * so that your application can draw the shadow image in the Canvas.
+ * </p>
*/
public static class DragShadowBuilder {
private final WeakReference<View> mView;
/**
- * Construct a shadow builder object for use with the given View object. The
- * default implementation will construct a drag shadow the same size and
- * appearance as the supplied View.
- *
- * @param view A view within the application's layout whose appearance
- * should be replicated as the drag shadow.
+ * Constructs a shadow image builder based on a View. By default, the resulting drag
+ * shadow will have the same appearance and dimensions as the View, with the touch point
+ * over the center of the View.
+ * @param view A View. Any View in scope can be used.
*/
public DragShadowBuilder(View view) {
mView = new WeakReference<View>(view);
@@ -10863,7 +10880,8 @@
* constructor variant is only useful when the {@link #onProvideShadowMetrics(Point, Point)}
* and {@link #onDrawShadow(Canvas)} methods are also overridden in order
* to supply the drag shadow's dimensions and appearance without
- * reference to any View object.
+ * reference to any View object. If they are not overridden, then the result is an
+ * invisible drag shadow.
*/
public DragShadowBuilder() {
mView = new WeakReference<View>(null);
@@ -10884,22 +10902,24 @@
}
/**
- * Provide the draggable-shadow metrics for the operation: the dimensions of
- * the shadow image itself, and the point within that shadow that should
+ * Provides the metrics for the shadow image. These include the dimensions of
+ * the shadow image, and the point within that shadow that should
* be centered under the touch location while dragging.
* <p>
* The default implementation sets the dimensions of the shadow to be the
- * same as the dimensions of the View object that had been supplied to the
- * {@link #View.DragShadowBuilder(View)} constructor
- * when the builder object was instantiated, and centers the shadow under the touch
- * point.
+ * same as the dimensions of the View itself and centers the shadow under
+ * the touch point.
+ * </p>
*
- * @param shadowSize The application should set the {@code x} member of this
- * parameter to the desired shadow width, and the {@code y} member to
- * the desired height.
- * @param shadowTouchPoint The application should set this point to be the
- * location within the shadow that should track directly underneath
- * the touch point on the screen during a drag.
+ * @param shadowSize A {@link android.graphics.Point} containing the width and height
+ * of the shadow image. Your application must set {@link android.graphics.Point#x} to the
+ * desired width and must set {@link android.graphics.Point#y} to the desired height of the
+ * image.
+ *
+ * @param shadowTouchPoint A {@link android.graphics.Point} for the position within the
+ * shadow image that should be underneath the touch point during the drag and drop
+ * operation. Your application must set {@link android.graphics.Point#x} to the
+ * X coordinate and {@link android.graphics.Point#y} to the Y coordinate of this position.
*/
public void onProvideShadowMetrics(Point shadowSize, Point shadowTouchPoint) {
final View view = mView.get();
@@ -10912,16 +10932,11 @@
}
/**
- * Draw the shadow image for the upcoming drag. The shadow canvas was
- * created with the dimensions supplied by the
+ * Draws the shadow image. The system creates the {@link android.graphics.Canvas} object
+ * based on the dimensions it received from the
* {@link #onProvideShadowMetrics(Point, Point)} callback.
- * <p>
- * The default implementation replicates the appearance of the View object
- * that had been supplied to the
- * {@link #View.DragShadowBuilder(View)}
- * constructor when the builder object was instantiated.
*
- * @param canvas
+ * @param canvas A {@link android.graphics.Canvas} object in which to draw the shadow image.
*/
public void onDrawShadow(Canvas canvas) {
final View view = mView.get();
@@ -10934,24 +10949,43 @@
}
/**
- * Drag and drop. App calls startDrag(), then callbacks to the shadow builder's
- * {@link DragShadowBuilder#onProvideShadowMetrics(Point, Point)} and
- * {@link DragShadowBuilder#onDrawShadow(Canvas)} methods happen, then the drag
- * operation is handed over to the OS.
- * !!! TODO: real docs
- *
- * @param data !!! TODO
- * @param shadowBuilder !!! TODO
- * @param myLocalState An arbitrary object that will be passed as part of every DragEvent
- * delivered to the calling application during the course of the current drag operation.
- * This object is private to the application that called startDrag(), and is not
- * visible to other applications. It provides a lightweight way for the application to
- * propagate information from the initiator to the recipient of a drag within its own
- * application; for example, to help disambiguate between 'copy' and 'move' semantics.
- * @param flags Flags affecting the drag operation. At present no flags are defined;
- * pass 0 for this parameter.
- * @return {@code true} if the drag operation was initiated successfully; {@code false} if
- * an error prevented the drag from taking place.
+ * Starts a drag and drop operation. When your application calls this method, it passes a
+ * {@link android.view.View.DragShadowBuilder} object to the system. The
+ * system calls this object's {@link DragShadowBuilder#onProvideShadowMetrics(Point, Point)}
+ * to get metrics for the drag shadow, and then calls the object's
+ * {@link DragShadowBuilder#onDrawShadow(Canvas)} to draw the drag shadow itself.
+ * <p>
+ * Once the system has the drag shadow, it begins the drag and drop operation by sending
+ * drag events to all the View objects in your application that are currently visible. It does
+ * this either by calling the View object's drag listener (an implementation of
+ * {@link android.view.View.OnDragListener#onDrag(View,DragEvent) onDrag()} or by calling the
+ * View object's {@link android.view.View#onDragEvent(DragEvent) onDragEvent()} method.
+ * Both are passed a {@link android.view.DragEvent} object that has a
+ * {@link android.view.DragEvent#getAction()} value of
+ * {@link android.view.DragEvent#ACTION_DRAG_STARTED}.
+ * </p>
+ * <p>
+ * Your application can invoke startDrag() on any attached View object. The View object does not
+ * need to be the one used in {@link android.view.View.DragShadowBuilder}, nor does it need to
+ * be related to the View the user selected for dragging.
+ * </p>
+ * @param data A {@link android.content.ClipData} object pointing to the data to be
+ * transferred by the drag and drop operation.
+ * @param shadowBuilder A {@link android.view.View.DragShadowBuilder} object for building the
+ * drag shadow.
+ * @param myLocalState An {@link java.lang.Object} containing local data about the drag and
+ * drop operation. This Object is put into every DragEvent object sent by the system during the
+ * current drag.
+ * <p>
+ * myLocalState is a lightweight mechanism for the sending information from the dragged View
+ * to the target Views. For example, it can contain flags that differentiate between a
+ * a copy operation and a move operation.
+ * </p>
+ * @param flags Flags that control the drag and drop operation. No flags are currently defined,
+ * so the parameter should be set to 0.
+ * @return {@code true} if the method completes successfully, or
+ * {@code false} if it fails anywhere. Returning {@code false} means the system was unable to
+ * do a drag, and so no drag operation is in progress.
*/
public final boolean startDrag(ClipData data, DragShadowBuilder shadowBuilder,
Object myLocalState, int flags) {
@@ -11010,42 +11044,48 @@
}
/**
- * Drag-and-drop event dispatch. The event.getAction() verb is one of the DragEvent
- * constants DRAG_STARTED_EVENT, DRAG_EVENT, DROP_EVENT, and DRAG_ENDED_EVENT.
- *
- * For DRAG_STARTED_EVENT, event.getClipDescription() describes the content
- * being dragged. onDragEvent() should return 'true' if the view can handle
- * a drop of that content. A view that returns 'false' here will receive no
- * further calls to onDragEvent() about the drag/drop operation.
- *
- * For DRAG_ENTERED, event.getClipDescription() describes the content being
- * dragged. This will be the same content description passed in the
- * DRAG_STARTED_EVENT invocation.
- *
- * For DRAG_EXITED, event.getClipDescription() describes the content being
- * dragged. This will be the same content description passed in the
- * DRAG_STARTED_EVENT invocation. The view should return to its approriate
- * drag-acceptance visual state.
- *
- * For DRAG_LOCATION_EVENT, event.getX() and event.getY() give the location in View
- * coordinates of the current drag point. The view must return 'true' if it
- * can accept a drop of the current drag content, false otherwise.
- *
- * For DROP_EVENT, event.getX() and event.getY() give the location of the drop
- * within the view; also, event.getClipData() returns the full data payload
- * being dropped. The view should return 'true' if it consumed the dropped
- * content, 'false' if it did not.
- *
- * For DRAG_ENDED_EVENT, the 'event' argument may be null. The view should return
- * to its normal visual state.
+ * Handles drag events sent by the system following a call to
+ * {@link android.view.View#startDrag(ClipData,DragShadowBuilder,Object,int) startDrag()}.
+ *<p>
+ * When the system calls this method, it passes a
+ * {@link android.view.DragEvent} object. A call to
+ * {@link android.view.DragEvent#getAction()} returns one of the action type constants defined
+ * in DragEvent. The method uses these to determine what is happening in the drag and drop
+ * operation.
+ * @param event The {@link android.view.DragEvent} sent by the system.
+ * The {@link android.view.DragEvent#getAction()} method returns an action type constant defined
+ * in DragEvent, indicating the type of drag event represented by this object.
+ * @return {@code true} if the method was successful, otherwise {@code false}.
+ * <p>
+ * The method should return {@code true} in response to an action type of
+ * {@link android.view.DragEvent#ACTION_DRAG_STARTED} to receive drag events for the current
+ * operation.
+ * </p>
+ * <p>
+ * The method should also return {@code true} in response to an action type of
+ * {@link android.view.DragEvent#ACTION_DROP} if it consumed the drop, or
+ * {@code false} if it didn't.
+ * </p>
*/
public boolean onDragEvent(DragEvent event) {
return false;
}
/**
- * Views typically don't need to override dispatchDragEvent(); it just calls
- * onDragEvent(event) and passes the result up appropriately.
+ * Detects if this View is enabled and has a drag event listener.
+ * If both are true, then it calls the drag event listener with the
+ * {@link android.view.DragEvent} it received. If the drag event listener returns
+ * {@code true}, then dispatchDragEvent() returns {@code true}.
+ * <p>
+ * For all other cases, the method calls the
+ * {@link android.view.View#onDragEvent(DragEvent) onDragEvent()} drag event handler
+ * method and returns its result.
+ * </p>
+ * <p>
+ * This ensures that a drag event is always consumed, even if the View does not have a drag
+ * event listener. However, if the View has a listener and the listener returns true, then
+ * onDragEvent() is not called.
+ * </p>
*/
public boolean dispatchDragEvent(DragEvent event) {
if (mOnDragListener != null && (mViewFlags & ENABLED_MASK) == ENABLED
@@ -11062,7 +11102,7 @@
*/
public void onCloseSystemDialogs(String reason) {
}
-
+
/**
* Given a Drawable whose bounds have been set to draw into this view,
* update a Region being computed for {@link #gatherTransparentRegion} so
@@ -11394,7 +11434,7 @@
mOriginalWindowAttachCount = mWindowAttachCount;
}
}
-
+
private final class CheckForTap implements Runnable {
public void run() {
mPrivateFlags &= ~PREPRESSED;
@@ -11416,7 +11456,7 @@
public void hackTurnOffWindowResizeAnim(boolean off) {
mAttachInfo.mTurnOffWindowResizeAnim = off;
}
-
+
/**
* Interface definition for a callback to be invoked when a key event is
* dispatched to this view. The callback will be invoked before the key
@@ -11479,11 +11519,11 @@
* Called when a drag event is dispatched to a view. This allows listeners
* to get a chance to override base View behavior.
*
- * @param v The view the drag has been dispatched to.
- * @param event The DragEvent object containing full information
- * about the event.
- * @return true if the listener consumed the DragEvent, false in order to fall
- * back to the view's default handling.
+ * @param v The View that received the drag event.
+ * @param event The {@link android.view.DragEvent} object for the drag event.
+ * @return {@code true} if the drag event was handled successfully, or {@code false}
+ * if the drag event was not handled. Note that {@code false} will trigger the View
+ * to call its {@link #onDragEvent(DragEvent) onDragEvent()} handler.
*/
boolean onDrag(View v, DragEvent event);
}
@@ -11671,7 +11711,7 @@
boolean mHardwareAccelerated;
boolean mHardwareAccelerationRequested;
HardwareRenderer mHardwareRenderer;
-
+
/**
* Scale factor used by the compatibility mode
*/
@@ -11686,7 +11726,7 @@
* If set, ViewRoot doesn't use its lame animation for when the window resizes.
*/
boolean mTurnOffWindowResizeAnim;
-
+
/**
* Left position of this view's window
*/
@@ -11879,7 +11919,7 @@
* instances of View.</p>
*/
private static class ScrollabilityCache implements Runnable {
-
+
/**
* Scrollbars are not visible
*/
@@ -11896,7 +11936,7 @@
public static final int FADING = 2;
public boolean fadeScrollBars;
-
+
public int fadingEdgeLength;
public int scrollBarDefaultDelayBeforeFade;
public int scrollBarFadeDuration;
@@ -11914,7 +11954,7 @@
private static final float[] OPAQUE = { 255 };
private static final float[] TRANSPARENT = { 0.0f };
-
+
/**
* When fading should start. This time moves into the future every time
* a new scroll happens. Measured based on SystemClock.uptimeMillis()
@@ -11959,7 +11999,7 @@
paint.setXfermode(null);
}
}
-
+
public void run() {
long now = AnimationUtils.currentAnimationTimeMillis();
if (now >= fadeStartTime) {