Improve docs for GradientDrawable's useLevel and centerX/Y properties (daec5506) · Commits · e / os / android_frameworks_base

core/res/res/values/attrs.xml

+22 −10

Original line number	Diff line number	Diff line
		@@ -5341,7 +5341,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. -->
		@@ -5375,28 +5378,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>

graphics/java/android/graphics/drawable/GradientDrawable.java

+44 −16

Original line number	Diff line number	Diff line
		@@ -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 <gradient>}
		* tag, NOT the {@code android:useLevel} attribute on the outer
		* {@code <shape>} 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;