Improve docs for GradientDrawable's useLevel and centerX/Y properties am: daec5506c4

am: cc914b6b0b

Change-Id: I52f3e1d28cca58babce095852fea9f2c3da94422

2 files changed, 66 insertions, 26 deletions

diff --git a/core/res/res/values/attrs.xml b/core/res/res/values/attrs.xml
index f273d272e41b..cdcb15c96259 100644
--- a/core/res/res/values/attrs.xml
+++ b/core/res/res/values/attrs.xml
@@ -5356,7 +5356,10 @@ i
         <attr name="innerRadius" format="dimension" />
         <!-- Thickness of the ring. When defined, thicknessRatio is ignored. -->
         <attr name="thickness" format="dimension" />
-        <!-- Indicates whether the drawable's level affects the way the gradient is drawn. -->
+        <!-- Whether the drawable level value (see
+             {@link android.graphics.drawable.Drawable#getLevel()}) is used to scale the shape.
+             Scaling behavior depends on the shape type. For "ring", the angle is scaled from 0 to
+             360. For all other types, there is no effect. The default value is true. -->
         <attr name="useLevel" />
         <!-- If set, specifies the color to apply to the drawable as a tint. By default,
              no tint is applied. May be a color state list. -->
@@ -5390,28 +5393,37 @@ i
     <declare-styleable name="GradientDrawableGradient">
         <!-- Start color of the gradient. -->
         <attr name="startColor" format="color" />
-        <!-- Optional center color. For linear gradients, use centerX or centerY
-             to place the center color. -->
+        <!-- Optional center color. For linear gradients, use centerX or centerY to place the center
+             color. -->
         <attr name="centerColor" format="color" />
         <!-- End color of the gradient. -->
         <attr name="endColor" format="color" />
+        <!-- Whether the drawable level value (see
+             {@link android.graphics.drawable.Drawable#getLevel()}) is used to scale the gradient.
+             Scaling behavior varies based on gradient type. For "linear", adjusts the ending
+             position along the gradient's axis of orientation. For "radial", adjusts the outer
+             radius. For "sweep", adjusts the ending angle. The default value is false. -->
         <attr name="useLevel" format="boolean" />
-        <!-- Angle of the gradient. -->
+        <!-- Angle of the gradient, used only with linear gradient. Must be a multiple of 45 in the
+             range [0, 315]. -->
         <attr name="angle" format="float" />
         <!-- Type of gradient. The default type is linear. -->
         <attr name="type">
-            <!-- Linear gradient. -->
+            <!-- Linear gradient extending across the center point. -->
             <enum name="linear" value="0" />
-            <!-- Radial, or circular, gradient. -->
+            <!-- Radial gradient extending from the center point outward. -->
             <enum name="radial" value="1" />
-            <!-- Sweep, or angled or diamond, gradient. -->
+            <!-- Sweep (or angular) gradient sweeping counter-clockwise around the center point. -->
             <enum name="sweep"  value="2" />
         </attr>
-        <!-- X coordinate of the origin of the gradient within the shape. -->
+        <!-- X-position of the center point of the gradient within the shape as a fraction of the
+             width. The default value is 0.5. -->
         <attr name="centerX" format="float|fraction" />
-        <!-- Y coordinate of the origin of the gradient within the shape. -->
+        <!-- Y-position of the center point of the gradient within the shape as a fraction of the
+             height. The default value is 0.5. -->
         <attr name="centerY" format="float|fraction" />
-        <!-- Radius of the gradient, used only with radial gradient. -->
+        <!-- Radius of the gradient, used only with radial gradient. May be an explicit dimension
+             or a fractional value relative to the shape's minimum dimension. -->
         <attr name="gradientRadius" format="float|fraction|dimension" />
     </declare-styleable>
 
diff --git a/graphics/java/android/graphics/drawable/GradientDrawable.java b/graphics/java/android/graphics/drawable/GradientDrawable.java
index 3dbd2a96b00a..8c633b0da93a 100644
--- a/graphics/java/android/graphics/drawable/GradientDrawable.java
+++ b/graphics/java/android/graphics/drawable/GradientDrawable.java
@@ -475,16 +475,17 @@ public class GradientDrawable extends Drawable {
     }
 
     /**
-     * Sets the center location in pixels of the gradient. The radius is
-     * honored only when the gradient type is set to {@link #RADIAL_GRADIENT}
-     * or {@link #SWEEP_GRADIENT}.
+     * Sets the position of the center of the gradient as a fraction of the
+     * width and height.
+     * <p>
+     * The default value is (0.5, 0.5).
      * <p>
      * <strong>Note</strong>: changing this property will affect all instances
      * of a drawable loaded from a resource. It is recommended to invoke
      * {@link #mutate()} before changing this property.
      *
-     * @param x the x coordinate of the gradient's center in pixels
-     * @param y the y coordinate of the gradient's center in pixels
+     * @param x the X-position of the center of the gradient
+     * @param y the Y-position of the center of the gradient
      *
      * @see #mutate()
      * @see #setGradientType(int)
@@ -498,9 +499,10 @@ public class GradientDrawable extends Drawable {
     }
 
     /**
-     * Returns the center X location of this gradient in pixels.
+     * Returns the X-position of the center of the gradient as a fraction of
+     * the width.
      *
-     * @return the center X location of this gradient in pixels
+     * @return the X-position of the center of the gradient
      * @see #setGradientCenter(float, float)
      */
     public float getGradientCenterX() {
@@ -508,9 +510,10 @@ public class GradientDrawable extends Drawable {
     }
 
     /**
-     * Returns the center Y location of this gradient in pixels.
+     * Returns the Y-position of the center of this gradient as a fraction of
+     * the height.
      *
-     * @return the center Y location of this gradient in pixels
+     * @return the Y-position of the center of the gradient
      * @see #setGradientCenter(float, float)
      */
     public float getGradientCenterY() {
@@ -554,19 +557,43 @@ public class GradientDrawable extends Drawable {
     }
 
     /**
-     * Sets whether or not this drawable will honor its {@code level} property.
+     * Sets whether this drawable's {@code level} property will be used to
+     * scale the gradient. If a gradient is not used, this property has no
+     * effect.
      * <p>
-     * <strong>Note</strong>: changing this property will affect all instances
+     * Scaling behavior varies based on gradient type:
+     * <ul>
+     *     <li>{@link #LINEAR_GRADIENT} adjusts the ending position along the
+     *         gradient's axis of orientation (see {@link #getOrientation()})
+     *     <li>{@link #RADIAL_GRADIENT} adjusts the outer radius
+     *     <li>{@link #SWEEP_GRADIENT} adjusts the ending angle
+     * <ul>
+     * <p>
+     * The default value for this property is {@code false}.
+     * <p>
+     * <strong>Note</strong>: This property corresponds to the
+     * {@code android:useLevel} attribute on the inner {@code &lt;gradient&gt;}
+     * tag, NOT the {@code android:useLevel} attribute on the outer
+     * {@code &lt;shape&gt;} tag. For example,
+     * <pre>{@code
+     * <shape ...>
+     *     <gradient
+     *         ...
+     *         android:useLevel="true" />
+     * </shape>
+     * }</pre><p>
+     * <strong>Note</strong>: Changing this property will affect all instances
      * of a drawable loaded from a resource. It is recommended to invoke
      * {@link #mutate()} before changing this property.
      *
-     * @param useLevel {@code true} if this drawable should honor its level,
-     *                 {@code false} otherwise
+     * @param useLevel {@code true} if the gradient should be scaled based on
+     *                 level, {@code false} otherwise
      *
      * @see #mutate()
      * @see #setLevel(int)
      * @see #getLevel()
      * @see #getUseLevel()
+     * @attr ref android.R.styleable#GradientDrawableGradient_useLevel
      */
     public void setUseLevel(boolean useLevel) {
         mGradientState.mUseLevel = useLevel;
@@ -575,12 +602,13 @@ public class GradientDrawable extends Drawable {
     }
 
     /**
-     * Returns whether or not this drawable will honor its {@code level}
-     * property.
+     * Returns whether this drawable's {@code level} property will be used to
+     * scale the gradient.
      *
-     * @return {@code true} if this drawable should honor its level,
+     * @return {@code true} if the gradient should be scaled based on level,
      *         {@code false} otherwise
      * @see #setUseLevel(boolean)
+     * @attr ref android.R.styleable#GradientDrawableGradient_useLevel
      */
     public boolean getUseLevel() {
         return mGradientState.mUseLevel;