Clean up Outline API, method on drawable

bug:15025466
bug:15089680
Change-Id: I8d3b64a0d9dbdbaf679042c8b384d2050323a8e6

2 files changed, 28 insertions, 15 deletions

diff --git a/graphics/java/android/graphics/Outline.java b/graphics/java/android/graphics/Outline.java
index c6ba75c..d87c3cb 100644
--- a/graphics/java/android/graphics/Outline.java
+++ b/graphics/java/android/graphics/Outline.java
@@ -23,9 +23,9 @@ import android.view.View;
 
 /**
  * Defines a simple shape, used for bounding graphical regions.
- *
+ * <p>
  * Can be used with a View, or computed by a Drawable, to drive the shape of shadows cast by a
- * View.
+ * View, or to clip the contents of the View.
  *
  * @see View#setOutline(Outline)
  * @see Drawable#getOutline(Outline)
@@ -41,7 +41,7 @@ public final class Outline {
     public Path mPath;
 
     /**
-     * Constructs an invalid Outline. Call one of the setter methods to make
+     * Constructs an empty Outline. Call one of the setter methods to make
      * the outline valid for use with a View.
      */
     public Outline() {}
@@ -49,23 +49,31 @@ public final class Outline {
     /**
      * Constructs an Outline with a copy of the data in src.
      */
-    public Outline(@Nullable Outline src) {
+    public Outline(@NonNull Outline src) {
         set(src);
     }
 
-    public void reset() {
+    /**
+     * Sets the outline to be empty.
+     *
+     * @see #isEmpty()
+     */
+    public void setEmpty() {
         mRadius = 0;
         mRect = null;
         mPath = null;
     }
 
     /**
-     * Returns whether the Outline is valid for use with a View.
+     * Returns whether the Outline is empty.
      * <p>
-     * Outlines are invalid when constructed until a setter method is called.
+     * Outlines are empty when constructed, or if {@link #setEmpty()} is called,
+     * until a setter method is called
+     *
+     * @see #setEmpty()
      */
-    public boolean isValid() {
-        return mRect != null || mPath != null;
+    public boolean isEmpty() {
+        return mRect == null && mPath == null;
     }
 
     /**
diff --git a/graphics/java/android/graphics/drawable/Drawable.java b/graphics/java/android/graphics/drawable/Drawable.java
index c78096a..951add9 100644
--- a/graphics/java/android/graphics/drawable/Drawable.java
+++ b/graphics/java/android/graphics/drawable/Drawable.java
@@ -16,6 +16,7 @@
 
 package android.graphics.drawable;
 
+import android.annotation.NonNull;
 import android.graphics.Insets;
 import android.graphics.Xfermode;
 import android.os.Trace;
@@ -817,11 +818,12 @@ public abstract class Drawable {
     /**
      * Return in padding the insets suggested by this Drawable for placing
      * content inside the drawable's bounds. Positive values move toward the
-     * center of the Drawable (set Rect.inset). Returns true if this drawable
-     * actually has a padding, else false. When false is returned, the padding
-     * is always set to 0.
+     * center of the Drawable (set Rect.inset).
+     *
+     * @return true if this drawable actually has a padding, else false. When false is returned,
+     * the padding is always set to 0.
      */
-    public boolean getPadding(Rect padding) {
+    public boolean getPadding(@NonNull Rect padding) {
         padding.set(0, 0, 0, 0);
         return false;
     }
@@ -842,13 +844,16 @@ public abstract class Drawable {
      * This method will be called by a View on its background Drawable after bounds change, or its
      * Drawable is invalidated, if the View's Outline isn't set explicitly. This allows the
      * background Drawable to define the shape of the shadow cast by the View.
-     *
+     * <p>
      * The default behavior defines the outline to be the bounding rectangle. Subclasses that wish
      * to convey a different shape must override this method.
      *
+     * @return true if this drawable actually has an outline, else false. The outline must be
+     *         populated by the drawable if true is returned.
+     *
      * @see View#setOutline(android.graphics.Outline)
      */
-    public boolean getOutline(Outline outline) {
+    public boolean getOutline(@NonNull Outline outline) {
         outline.setRect(getBounds());
         return true;
     }