From 17ed60c3d2e480ab9788b445958a22b9ae7b6e96 Mon Sep 17 00:00:00 2001
From: Christopher Tate <ctate@google.com>
Date: Tue, 18 Jan 2011 12:50:26 -0800
Subject: [PATCH] API CHANGE: add a no-View ctor for DragShadowBuilder

Cf conversation with the API council.  Also expand the javadoc
a bit.

Change-Id: I9d4edb1042e00492b3db5c6bb7c7d9648581efad
---
 api/current.xml                  |  8 +++++++
 core/java/android/view/View.java | 40 ++++++++++++++++++++++++++++----
 2 files changed, 44 insertions(+), 4 deletions(-)

diff --git a/api/current.xml b/api/current.xml
index a8b6c80c3775c..a8ab943410e47 100644
--- a/api/current.xml
+++ b/api/current.xml
@@ -219458,6 +219458,14 @@
 <parameter name="view" type="android.view.View">
 </parameter>
 </constructor>
+<constructor name="View.DragShadowBuilder"
+ type="android.view.View.DragShadowBuilder"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+</constructor>
 <method name="getView"
  return="android.view.View"
  abstract="false"
diff --git a/core/java/android/view/View.java b/core/java/android/view/View.java
index 53fc0c0ff1122..270ea7689e1a1 100644
--- a/core/java/android/view/View.java
+++ b/core/java/android/view/View.java
@@ -10606,13 +10606,38 @@ public class View implements Drawable.Callback, KeyEvent.Callback, Accessibility
         private final WeakReference<View> mView;
 
         /**
-         * Construct a shadow builder object for use with the given view.
-         * @param view
+         * 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.
          */
         public DragShadowBuilder(View view) {
             mView = new WeakReference<View>(view);
         }
 
+        /**
+         * Construct a shadow builder object with no associated View.  This
+         * 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.
+         */
+        public DragShadowBuilder() {
+            mView = new WeakReference<View>(null);
+        }
+
+        /**
+         * Returns the View object that had been passed to the
+         * {@link #View.DragShadowBuilder(View)}
+         * constructor.  If that View parameter was {@code null} or if the
+         * {@link #View.DragShadowBuilder()}
+         * constructor was used to instantiate the builder object, this method will return
+         * null.
+         *
+         * @return The View object associate with this builder object.
+         */
         final public View getView() {
             return mView.get();
         }
@@ -10623,8 +10648,10 @@ public class View implements Drawable.Callback, KeyEvent.Callback, Accessibility
          * 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 itself and centers the shadow under
-         * the touch point.
+         * 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.
          *
          * @param shadowSize The application should set the {@code x} member of this
          *        parameter to the desired shadow width, and the {@code y} member to
@@ -10647,6 +10674,11 @@ public class View implements Drawable.Callback, KeyEvent.Callback, Accessibility
          * Draw the shadow image for the upcoming drag.  The shadow canvas was
          * created with the dimensions supplied by 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
          */