[ProgressIndicator] Added APIs for customizing wave amplitude ramping.

pekingme · dsn5ft · commit 24cddabbb819 · 2025-07-17T20:47:27.000Z
PiperOrigin-RevId: 784177043
diff --git a/docs/components/ProgressIndicator.md b/docs/components/ProgressIndicator.md
@@ -78,6 +78,8 @@ Element                                   | Attribute
 **Wave amplitude**                        | `app:waveAmplitude`                      | `setWaveAmplitude`<br>`getWaveAmplitude`                                           | 0
 **Wave speed**                            | `app:waveSpeed`                          | `setWaveSpeed`<br>`getWaveSpeed`                                                   | 0
 **Indeterminate animator duration scale** | `app:indeterminateAnimatorDurationScale` | `setIndeterminateAnimatorDurationScale`                                            | 1
+**Wave amplitude ramp up progress**       | `app:waveAmplitudeRampProgressMin`       | `setWaveAmplitudeRampProgressRange`                                                | 0.1
+**Wave amplitude ramp down progress**     | `app:waveAmplitudeRampProgressMax`       | `setWaveAmplitudeRampProgressRange`                                                | 0.9
 
 ### Linear type specific attributes
 
diff --git a/lib/java/com/google/android/material/progressindicator/BaseProgressIndicator.java b/lib/java/com/google/android/material/progressindicator/BaseProgressIndicator.java
@@ -449,9 +449,7 @@ public IndeterminateDrawable<S> getIndeterminateDrawable() {
    * attached to a window and whether it and its ancestors are visible.
    */
   boolean visibleToUser() {
-    return isAttachedToWindow()
-        && getWindowVisibility() == View.VISIBLE
-        && isEffectivelyVisible();
+    return isAttachedToWindow() && getWindowVisibility() == View.VISIBLE && isEffectivelyVisible();
   }
 
   /**
@@ -474,8 +472,8 @@ && getWindowVisibility() == View.VISIBLE
    * #isShown()} on parent changes that result from {@link
    * android.view.ViewGroup#attachViewToParent(View, int, ViewGroup.LayoutParams)}, which *can*
    * change our effective visibility. So this method errs on the side of assuming visibility unless
-   * we can conclusively prove otherwise (but may result in some false positives, if this view
-   * ends up being attached to a non-visible hierarchy after being detached in a visible state).
+   * we can conclusively prove otherwise (but may result in some false positives, if this view ends
+   * up being attached to a non-visible hierarchy after being detached in a visible state).
    */
   boolean isEffectivelyVisible() {
     View current = this;
@@ -821,6 +819,28 @@ public void setWaveSpeed(@Px int waveSpeed) {
     getProgressDrawable().setEnforcedDrawing(spec.waveSpeed != 0);
   }
 
+  /**
+   * Sets the progress for ramping up the full wave amplitude. If progress is outside the range,
+   * track is flat.
+   *
+   * @param progress The progress to ramp up wave amplitude.
+   */
+  public void setWaveAmplitudeRampProgressMin(float progress) {
+    getProgressDrawable().setWaveAmplitudeRampProgressMin(progress);
+    invalidate();
+  }
+
+  /**
+   * Sets the progress for ramping down the full wave amplitude. If progress is outside the range,
+   * track is flat.
+   *
+   * @param progress The progress to ramp down wave amplitude.
+   */
+  public void setWaveAmplitudeRampProgressMax(float progress) {
+    getProgressDrawable().setWaveAmplitudeRampProgressMax(progress);
+    invalidate();
+  }
+
   /**
    * Returns the show animation behavior used in this progress indicator.
    *
diff --git a/lib/java/com/google/android/material/progressindicator/BaseProgressIndicatorSpec.java b/lib/java/com/google/android/material/progressindicator/BaseProgressIndicatorSpec.java
@@ -18,6 +18,8 @@
 
 import com.google.android.material.R;
 
+import static com.google.android.material.progressindicator.DeterminateDrawable.FULL_AMPLITUDE_PROGRESS_MAX;
+import static com.google.android.material.progressindicator.DeterminateDrawable.FULL_AMPLITUDE_PROGRESS_MIN;
 import static com.google.android.material.resources.MaterialResources.getDimensionPixelSize;
 import static java.lang.Math.abs;
 import static java.lang.Math.min;
@@ -102,6 +104,14 @@ public abstract class BaseProgressIndicatorSpec {
   @FloatRange(from = 0.1f, to = 10f)
   public float indeterminateAnimatorDurationScale;
 
+  /** The normalized progress, at which the full wave amplitude will be ramped up. */
+  @FloatRange(from = 0f, to = 1f)
+  public float waveAmplitudeRampProgressMin;
+
+  /** The normalized progress, at which the full wave amplitude will be ramped down. */
+  @FloatRange(from = 0f, to = 1f)
+  public float waveAmplitudeRampProgressMax;
+
   /**
    * Instantiates BaseProgressIndicatorSpec.
    *
@@ -164,6 +174,14 @@ protected BaseProgressIndicatorSpec(
     waveSpeed = a.getDimensionPixelSize(R.styleable.BaseProgressIndicator_waveSpeed, 0);
     indeterminateAnimatorDurationScale =
         a.getFloat(R.styleable.BaseProgressIndicator_indeterminateAnimatorDurationScale, 1);
+    waveAmplitudeRampProgressMin =
+        a.getFloat(
+                R.styleable.BaseProgressIndicator_waveAmplitudeRampProgressMin,
+                FULL_AMPLITUDE_PROGRESS_MIN);
+    waveAmplitudeRampProgressMax =
+        a.getFloat(
+                R.styleable.BaseProgressIndicator_waveAmplitudeRampProgressMax,
+                FULL_AMPLITUDE_PROGRESS_MAX);
 
     loadIndicatorColors(context, a);
     loadTrackColor(context, a);
@@ -247,7 +265,7 @@ public boolean hasWavyEffect(boolean isDeterminate) {
         && ((!isDeterminate && wavelengthIndeterminate > 0)
             || (isDeterminate && wavelengthDeterminate > 0));
   }
-  
+
   /**
    * Returns the track corner radius in pixels.
    *
diff --git a/lib/java/com/google/android/material/progressindicator/DeterminateDrawable.java b/lib/java/com/google/android/material/progressindicator/DeterminateDrawable.java
@@ -40,8 +40,8 @@ public final class DeterminateDrawable<S extends BaseProgressIndicatorSpec>
   // Constants for drawing progress.
   private static final int MAX_DRAWABLE_LEVEL = 10000;
   // Constants for amplitude animation.
-  private static final float FULL_AMPLITUDE_FRACTION_MIN = 0.1f;
-  private static final float FULL_AMPLITUDE_FRACTION_MAX = 0.9f;
+  static final float FULL_AMPLITUDE_PROGRESS_MIN = 0.1f;
+  static final float FULL_AMPLITUDE_PROGRESS_MAX = 0.9f;
 
   // The constant for spring force stiffness.
   private static final float SPRING_FORCE_STIFFNESS = SpringForce.STIFFNESS_VERY_LOW;
@@ -288,8 +288,8 @@ void setLevelByFraction(float fraction) {
   }
 
   private float getAmplitudeFractionFromLevel(int level) {
-    return level >= FULL_AMPLITUDE_FRACTION_MIN * MAX_DRAWABLE_LEVEL
-            && level <= FULL_AMPLITUDE_FRACTION_MAX * MAX_DRAWABLE_LEVEL
+    return level >= baseSpec.waveAmplitudeRampProgressMin * MAX_DRAWABLE_LEVEL
+            && level <= baseSpec.waveAmplitudeRampProgressMax * MAX_DRAWABLE_LEVEL
         ? 1f
         : 0f;
   }
@@ -403,6 +403,16 @@ void setEnforcedDrawing(boolean enforced) {
     }
   }
 
+  void setWaveAmplitudeRampProgressMin(float progress) {
+    baseSpec.waveAmplitudeRampProgressMin = progress;
+    invalidateSelf();
+  }
+
+  void setWaveAmplitudeRampProgressMax(float progress) {
+    baseSpec.waveAmplitudeRampProgressMax = progress;
+    invalidateSelf();
+  }
+
   // ******************* Properties *******************
 
   private static final FloatPropertyCompat<DeterminateDrawable<?>> INDICATOR_LENGTH_IN_LEVEL =
diff --git a/lib/java/com/google/android/material/progressindicator/res-public/values/public.xml b/lib/java/com/google/android/material/progressindicator/res-public/values/public.xml
@@ -32,6 +32,8 @@
   <public name="waveAmplitude" type="attr"/>
   <public name="waveSpeed" type="attr"/>
   <public name="indeterminateAnimatorDurationScale" type="attr"/>
+  <public name="waveAmplitudeRampProgressMin" type="attr" />
+  <public name="waveAmplitudeRampProgressMax" type="attr" />
 
   <!-- LinearProgressIndicator attributes -->
   <public name="indeterminateAnimationType" type="attr"/>
diff --git a/lib/java/com/google/android/material/progressindicator/res/values/attrs.xml b/lib/java/com/google/android/material/progressindicator/res/values/attrs.xml
@@ -119,6 +119,16 @@
       This is independent from the animator scale in the System settings.
     -->
     <attr name="indeterminateAnimatorDurationScale" format="float" />
+    <!--
+      Defines the normalized progress [0, 1], at which the full wave amplitude will be ramped up.
+      When the progress is less than this, the track is shown as flat.
+    -->
+    <attr name="waveAmplitudeRampProgressMin" format="float" />
+    <!--
+      Defines the normalized progress [0, 1], at which the full wave amplitude will be ramped down.
+      When the progress is greater than this, the track is shown as flat.
+    -->
+    <attr name="waveAmplitudeRampProgressMax" format="float" />
   </declare-styleable>
 
   <declare-styleable name="LinearProgressIndicator">
