Improve docs for drawable tint and color filters

bug:19564477
Change-Id: I7e11baae2d4dd245965904c85b8855de71f6b6ac

10 files changed, 94 insertions, 47 deletions

diff --git a/graphics/java/android/graphics/PorterDuffColorFilter.java b/graphics/java/android/graphics/PorterDuffColorFilter.java
index fe4f8b8..bddd224 100644
--- a/graphics/java/android/graphics/PorterDuffColorFilter.java
+++ b/graphics/java/android/graphics/PorterDuffColorFilter.java
@@ -16,6 +16,8 @@
 
 package android.graphics;
 
+import android.annotation.NonNull;
+
 /**
  * A color filter that can be used to tint the source pixels using a single
  * color and a specific {@link PorterDuff Porter-Duff composite mode}.
@@ -34,7 +36,7 @@ public class PorterDuffColorFilter extends ColorFilter {
      * @see #setColor(int)
      * @see #setMode(android.graphics.PorterDuff.Mode)
      */
-    public PorterDuffColorFilter(int color, PorterDuff.Mode mode) {
+    public PorterDuffColorFilter(int color, @NonNull PorterDuff.Mode mode) {
         mColor = color;
         mMode = mode;
         update();
@@ -93,7 +95,7 @@ public class PorterDuffColorFilter extends ColorFilter {
      *
      * @hide
      */
-    public void setMode(PorterDuff.Mode mode) {
+    public void setMode(@NonNull PorterDuff.Mode mode) {
         mMode = mode;
         update();
     }
diff --git a/graphics/java/android/graphics/drawable/BitmapDrawable.java b/graphics/java/android/graphics/drawable/BitmapDrawable.java
index 945ae2e..68ffed6 100644
--- a/graphics/java/android/graphics/drawable/BitmapDrawable.java
+++ b/graphics/java/android/graphics/drawable/BitmapDrawable.java
@@ -628,8 +628,8 @@ public class BitmapDrawable extends Drawable {
     }
 
     @Override
-    public void setColorFilter(ColorFilter cf) {
-        mBitmapState.mPaint.setColorFilter(cf);
+    public void setColorFilter(ColorFilter colorFilter) {
+        mBitmapState.mPaint.setColorFilter(colorFilter);
         invalidateSelf();
     }
 
diff --git a/graphics/java/android/graphics/drawable/Drawable.java b/graphics/java/android/graphics/drawable/Drawable.java
index 247f94a..2cc192c 100644
--- a/graphics/java/android/graphics/drawable/Drawable.java
+++ b/graphics/java/android/graphics/drawable/Drawable.java
@@ -17,6 +17,7 @@
 package android.graphics.drawable;
 
 import android.annotation.NonNull;
+import android.annotation.Nullable;
 import android.content.res.ColorStateList;
 import android.content.res.Resources;
 import android.content.res.Resources.Theme;
@@ -477,67 +478,111 @@ public abstract class Drawable {
     }
 
     /**
-     * @hide Consider for future API inclusion
+     * @hide
+     *
+     * Internal-only method for setting xfermode on certain supported drawables.
+     *
+     * Should not be made public since the layers and drawing area with which
+     * Drawables draw is private implementation detail, and not something apps
+     * should rely upon.
      */
     public void setXfermode(Xfermode mode) {
         // Base implementation drops it on the floor for compatibility. Whee!
-        // TODO: For this to be included in the API proper, all framework drawables need impls.
-        // For right now only BitmapDrawable has it.
     }
 
     /**
-     * Specify an optional color filter for the drawable. Pass {@code null} to
-     * remove any existing color filter.
+     * Specify an optional color filter for the drawable.
+     * <p>
+     * If a Drawable has a ColorFilter, each output pixel of the Drawable's
+     * drawing contents will be modified by the color filter before it is
+     * blended onto the render target of a Canvas.
+     * </p>
+     * <p>
+     * Pass {@code null} to remove any existing color filter.
+     * </p>
+     * <p class="note"><strong>Note:</strong> Setting a non-{@code null} color
+     * filter disables {@link #setTintList(ColorStateList) tint}.
+     * </p>
      *
-     * @param cf the color filter to apply, or {@code null} to remove the
+     * @param colorFilter The color filter to apply, or {@code null} to remove the
      *            existing color filter
      */
-    public abstract void setColorFilter(ColorFilter cf);
+    public abstract void setColorFilter(@Nullable ColorFilter colorFilter);
 
     /**
      * Specify a color and Porter-Duff mode to be the color filter for this
      * drawable.
+     * <p>
+     * Convenience for {@link #setColorFilter(ColorFilter)} which constructs a
+     * {@link PorterDuffColorFilter}.
+     * </p>
+     * <p class="note"><strong>Note:</strong> Setting a color filter disables
+     * {@link #setTintList(ColorStateList) tint}.
+     * </p>
      */
-    public void setColorFilter(int color, PorterDuff.Mode mode) {
+    public void setColorFilter(int color, @NonNull PorterDuff.Mode mode) {
         setColorFilter(new PorterDuffColorFilter(color, mode));
     }
 
     /**
-     * Specifies a tint for this drawable.
+     * Specifies tint color for this drawable.
+     * <p>
+     * A Drawable's drawing content will be blended together with its tint
+     * before it is drawn to the screen. This functions similarly to
+     * {@link #setColorFilter(int, PorterDuff.Mode)}.
+     * </p>
      * <p>
-     * Setting a color filter via {@link #setColorFilter(ColorFilter)} overrides
-     * tint.
+     * To clear the tint, pass {@code null} to
+     * {@link #setTintList(ColorStateList)}.
+     * </p>
+     * <p class="note"><strong>Note:</strong> Setting a color filter via
+     * {@link #setColorFilter(ColorFilter)} or
+     * {@link #setColorFilter(int, PorterDuff.Mode)} overrides tint.
+     * </p>
      *
-     * @param tint Color to use for tinting this drawable
+     * @param tintColor Color to use for tinting this drawable
+     * @see #setTintList(ColorStateList)
      * @see #setTintMode(PorterDuff.Mode)
      */
-    public void setTint(int tint) {
-        setTintList(ColorStateList.valueOf(tint));
+    public void setTint(int tintColor) {
+        setTintList(ColorStateList.valueOf(tintColor));
     }
 
     /**
-     * Specifies a tint for this drawable as a color state list.
+     * Specifies tint color for this drawable as a color state list.
      * <p>
-     * Setting a color filter via {@link #setColorFilter(ColorFilter)} overrides
-     * tint.
+     * A Drawable's drawing content will be blended together with its tint
+     * before it is drawn to the screen. This functions similarly to
+     * {@link #setColorFilter(int, PorterDuff.Mode)}.
+     * </p>
+     * <p class="note"><strong>Note:</strong> Setting a color filter via
+     * {@link #setColorFilter(ColorFilter)} or
+     * {@link #setColorFilter(int, PorterDuff.Mode)} overrides tint.
+     * </p>
      *
-     * @param tint Color state list to use for tinting this drawable, or null to
-     *            clear the tint
+     * @param tint Color state list to use for tinting this drawable, or
+     *            {@code null} to clear the tint
+     * @see #setTint(int)
      * @see #setTintMode(PorterDuff.Mode)
      */
-    public void setTintList(ColorStateList tint) {}
+    public void setTintList(@Nullable ColorStateList tint) {}
 
     /**
      * Specifies a tint blending mode for this drawable.
      * <p>
-     * Setting a color filter via {@link #setColorFilter(ColorFilter)} overrides
-     * tint.
+     * Defines how this drawable's tint color should be blended into the drawable
+     * before it is drawn to screen. Default tint mode is {@link PorterDuff.Mode#MULTIPLY}.
+     * </p>
+     * <p class="note"><strong>Note:</strong> Setting a color filter via
+     * {@link #setColorFilter(ColorFilter)} or
+     * {@link #setColorFilter(int, PorterDuff.Mode)} overrides tint.
+     * </p>
      *
-     * @param tintMode Color state list to use for tinting this drawable, or null to
-     *            clear the tint
      * @param tintMode A Porter-Duff blending mode
+     * @see #setTint(int)
+     * @see #setTintList(ColorStateList)
      */
-    public void setTintMode(PorterDuff.Mode tintMode) {}
+    public void setTintMode(@NonNull PorterDuff.Mode tintMode) {}
 
     /**
      * Returns the current color filter, or {@code null} if none set.
diff --git a/graphics/java/android/graphics/drawable/DrawableContainer.java b/graphics/java/android/graphics/drawable/DrawableContainer.java
index 434134a..ddcb48b 100644
--- a/graphics/java/android/graphics/drawable/DrawableContainer.java
+++ b/graphics/java/android/graphics/drawable/DrawableContainer.java
@@ -172,14 +172,14 @@ public class DrawableContainer extends Drawable implements Drawable.Callback {
     }
 
     @Override
-    public void setColorFilter(ColorFilter cf) {
+    public void setColorFilter(ColorFilter colorFilter) {
         mDrawableContainerState.mHasColorFilter = true;
 
-        if (mDrawableContainerState.mColorFilter != cf) {
-            mDrawableContainerState.mColorFilter = cf;
+        if (mDrawableContainerState.mColorFilter != colorFilter) {
+            mDrawableContainerState.mColorFilter = colorFilter;
 
             if (mCurrDrawable != null) {
-                mCurrDrawable.mutate().setColorFilter(cf);
+                mCurrDrawable.mutate().setColorFilter(colorFilter);
             }
         }
     }
diff --git a/graphics/java/android/graphics/drawable/DrawableWrapper.java b/graphics/java/android/graphics/drawable/DrawableWrapper.java
index b17bab0..a213af8 100644
--- a/graphics/java/android/graphics/drawable/DrawableWrapper.java
+++ b/graphics/java/android/graphics/drawable/DrawableWrapper.java
@@ -238,9 +238,9 @@ public abstract class DrawableWrapper extends Drawable implements Drawable.Callb
     }
 
     @Override
-    public void setColorFilter(@Nullable ColorFilter cf) {
+    public void setColorFilter(@Nullable ColorFilter colorFilter) {
         if (mDrawable != null) {
-            mDrawable.setColorFilter(cf);
+            mDrawable.setColorFilter(colorFilter);
         }
     }
 
diff --git a/graphics/java/android/graphics/drawable/GradientDrawable.java b/graphics/java/android/graphics/drawable/GradientDrawable.java
index cc2de22..6ea23d4 100644
--- a/graphics/java/android/graphics/drawable/GradientDrawable.java
+++ b/graphics/java/android/graphics/drawable/GradientDrawable.java
@@ -832,9 +832,9 @@ public class GradientDrawable extends Drawable {
     }
 
     @Override
-    public void setColorFilter(ColorFilter cf) {
-        if (cf != mColorFilter) {
-            mColorFilter = cf;
+    public void setColorFilter(ColorFilter colorFilter) {
+        if (colorFilter != mColorFilter) {
+            mColorFilter = colorFilter;
             invalidateSelf();
         }
     }
diff --git a/graphics/java/android/graphics/drawable/LayerDrawable.java b/graphics/java/android/graphics/drawable/LayerDrawable.java
index f5353d4..74f62be 100644
--- a/graphics/java/android/graphics/drawable/LayerDrawable.java
+++ b/graphics/java/android/graphics/drawable/LayerDrawable.java
@@ -1035,11 +1035,11 @@ public class LayerDrawable extends Drawable implements Drawable.Callback {
     }
 
     @Override
-    public void setColorFilter(ColorFilter cf) {
+    public void setColorFilter(ColorFilter colorFilter) {
         final ChildDrawable[] array = mLayerState.mChildren;
         final int N = mLayerState.mNum;
         for (int i = 0; i < N; i++) {
-            array[i].mDrawable.setColorFilter(cf);
+            array[i].mDrawable.setColorFilter(colorFilter);
         }
     }
 
diff --git a/graphics/java/android/graphics/drawable/NinePatchDrawable.java b/graphics/java/android/graphics/drawable/NinePatchDrawable.java
index 617bf7c..487162e 100644
--- a/graphics/java/android/graphics/drawable/NinePatchDrawable.java
+++ b/graphics/java/android/graphics/drawable/NinePatchDrawable.java
@@ -338,12 +338,12 @@ public class NinePatchDrawable extends Drawable {
     }
 
     @Override
-    public void setColorFilter(ColorFilter cf) {
-        if (mPaint == null && cf == null) {
+    public void setColorFilter(ColorFilter colorFilter) {
+        if (mPaint == null && colorFilter == null) {
             // Fast common case -- leave at no color filter.
             return;
         }
-        getPaint().setColorFilter(cf);
+        getPaint().setColorFilter(colorFilter);
         invalidateSelf();
     }
 
diff --git a/graphics/java/android/graphics/drawable/RippleDrawable.java b/graphics/java/android/graphics/drawable/RippleDrawable.java
index c6ea91d..b028eeb 100644
--- a/graphics/java/android/graphics/drawable/RippleDrawable.java
+++ b/graphics/java/android/graphics/drawable/RippleDrawable.java
@@ -241,8 +241,8 @@ public class RippleDrawable extends LayerDrawable {
     }
 
     @Override
-    public void setColorFilter(ColorFilter cf) {
-        super.setColorFilter(cf);
+    public void setColorFilter(ColorFilter colorFilter) {
+        super.setColorFilter(colorFilter);
 
         // TODO: Should we support this?
     }
diff --git a/graphics/java/android/graphics/drawable/ShapeDrawable.java b/graphics/java/android/graphics/drawable/ShapeDrawable.java
index c208c03..fc88c15 100644
--- a/graphics/java/android/graphics/drawable/ShapeDrawable.java
+++ b/graphics/java/android/graphics/drawable/ShapeDrawable.java
@@ -299,8 +299,8 @@ public class ShapeDrawable extends Drawable {
     }
 
     @Override
-    public void setColorFilter(ColorFilter cf) {
-        mShapeState.mPaint.setColorFilter(cf);
+    public void setColorFilter(ColorFilter colorFilter) {
+        mShapeState.mPaint.setColorFilter(colorFilter);
         invalidateSelf();
     }