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

@@ -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"

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.
+         * Construct a shadow builder object for use with the given View object.  The
-         * @param view
+         * 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
+         * same as the dimensions of the View object that had been supplied to the
-         * the touch point.
+         * {@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
          */