From 8620ee6f76e0277e24d143388f4721272da8b59b Mon Sep 17 00:00:00 2001 From: Lais Andrade Date: Wed, 14 Dec 2022 21:24:18 +0000 Subject: [PATCH] Remove public APIs related to VibrationEffect.WaveformBuilder The frequency control will not be supported in Android U, so remove the newly introduced public APIs. Also remove related Vibrator and VibratorFrequencyProfile APIs. Fixes: 261879365 Test: N/A Change-Id: Iaa3644f8e1552d38a5bb9a0679f7d7cc8aae33ec --- core/api/current.txt | 34 ---------- core/api/test-current.txt | 33 +++++++++ core/java/android/os/VibrationEffect.java | 68 +++++++++---------- core/java/android/os/Vibrator.java | 4 ++ .../os/vibrator/VibratorFrequencyProfile.java | 11 +++ 5 files changed, 82 insertions(+), 68 deletions(-) diff --git a/core/api/current.txt b/core/api/current.txt index 3ca7dadfcddc1..8f71a2f15713a 100644 --- a/core/api/current.txt +++ b/core/api/current.txt @@ -32774,9 +32774,6 @@ package android.os { method public static android.os.VibrationEffect createWaveform(long[], int[], int); method public int describeContents(); method @NonNull public static android.os.VibrationEffect.Composition startComposition(); - method @NonNull public static android.os.VibrationEffect.WaveformBuilder startWaveform(); - method @NonNull public static android.os.VibrationEffect.WaveformBuilder startWaveform(@NonNull android.os.VibrationEffect.VibrationParameter); - method @NonNull public static android.os.VibrationEffect.WaveformBuilder startWaveform(@NonNull android.os.VibrationEffect.VibrationParameter, @NonNull android.os.VibrationEffect.VibrationParameter); field @NonNull public static final android.os.Parcelable.Creator CREATOR; field public static final int DEFAULT_AMPLITUDE = -1; // 0xffffffff field public static final int EFFECT_CLICK = 0; // 0x0 @@ -32786,13 +32783,10 @@ package android.os { } public static final class VibrationEffect.Composition { - method @NonNull public android.os.VibrationEffect.Composition addEffect(@NonNull android.os.VibrationEffect); - method @NonNull public android.os.VibrationEffect.Composition addOffDuration(@NonNull java.time.Duration); method @NonNull public android.os.VibrationEffect.Composition addPrimitive(int); method @NonNull public android.os.VibrationEffect.Composition addPrimitive(int, @FloatRange(from=0.0f, to=1.0f) float); method @NonNull public android.os.VibrationEffect.Composition addPrimitive(int, @FloatRange(from=0.0f, to=1.0f) float, @IntRange(from=0) int); method @NonNull public android.os.VibrationEffect compose(); - method @NonNull public android.os.VibrationEffect.Composition repeatEffectIndefinitely(@NonNull android.os.VibrationEffect); field public static final int PRIMITIVE_CLICK = 1; // 0x1 field public static final int PRIMITIVE_LOW_TICK = 8; // 0x8 field public static final int PRIMITIVE_QUICK_FALL = 6; // 0x6 @@ -32803,34 +32797,17 @@ package android.os { field public static final int PRIMITIVE_TICK = 7; // 0x7 } - public static final class VibrationEffect.Composition.UnreachableAfterRepeatingIndefinitelyException extends java.lang.IllegalStateException { - } - - public static class VibrationEffect.VibrationParameter { - method @NonNull public static android.os.VibrationEffect.VibrationParameter targetAmplitude(@FloatRange(from=0, to=1) float); - method @NonNull public static android.os.VibrationEffect.VibrationParameter targetFrequency(@FloatRange(from=1) float); - } - - public static final class VibrationEffect.WaveformBuilder { - method @NonNull public android.os.VibrationEffect.WaveformBuilder addSustain(@NonNull java.time.Duration); - method @NonNull public android.os.VibrationEffect.WaveformBuilder addTransition(@NonNull java.time.Duration, @NonNull android.os.VibrationEffect.VibrationParameter); - method @NonNull public android.os.VibrationEffect.WaveformBuilder addTransition(@NonNull java.time.Duration, @NonNull android.os.VibrationEffect.VibrationParameter, @NonNull android.os.VibrationEffect.VibrationParameter); - method @NonNull public android.os.VibrationEffect build(); - } - public abstract class Vibrator { method public final int areAllEffectsSupported(@NonNull int...); method public final boolean areAllPrimitivesSupported(@NonNull int...); method @NonNull public int[] areEffectsSupported(@NonNull int...); method @NonNull public boolean[] arePrimitivesSupported(@NonNull int...); method @RequiresPermission(android.Manifest.permission.VIBRATE) public abstract void cancel(); - method @Nullable public android.os.vibrator.VibratorFrequencyProfile getFrequencyProfile(); method public int getId(); method @NonNull public int[] getPrimitiveDurations(@NonNull int...); method public float getQFactor(); method public float getResonantFrequency(); method public abstract boolean hasAmplitudeControl(); - method public boolean hasFrequencyControl(); method public abstract boolean hasVibrator(); method @Deprecated @RequiresPermission(android.Manifest.permission.VIBRATE) public void vibrate(long); method @Deprecated @RequiresPermission(android.Manifest.permission.VIBRATE) public void vibrate(long, android.media.AudioAttributes); @@ -33161,17 +33138,6 @@ package android.os.strictmode { } -package android.os.vibrator { - - public final class VibratorFrequencyProfile { - method public float getMaxAmplitudeMeasurementInterval(); - method @FloatRange(from=0, to=1) @NonNull public float[] getMaxAmplitudeMeasurements(); - method public float getMaxFrequency(); - method public float getMinFrequency(); - } - -} - package android.preference { @Deprecated public class CheckBoxPreference extends android.preference.TwoStatePreference { diff --git a/core/api/test-current.txt b/core/api/test-current.txt index 85d73ec7d65af..8efdf82b225d2 100644 --- a/core/api/test-current.txt +++ b/core/api/test-current.txt @@ -1909,6 +1909,9 @@ package android.os { method public static android.os.VibrationEffect get(int, boolean); method @Nullable public static android.os.VibrationEffect get(android.net.Uri, android.content.Context); method public abstract long getDuration(); + method @NonNull public static android.os.VibrationEffect.WaveformBuilder startWaveform(); + method @NonNull public static android.os.VibrationEffect.WaveformBuilder startWaveform(@NonNull android.os.VibrationEffect.VibrationParameter); + method @NonNull public static android.os.VibrationEffect.WaveformBuilder startWaveform(@NonNull android.os.VibrationEffect.VibrationParameter, @NonNull android.os.VibrationEffect.VibrationParameter); field public static final int EFFECT_POP = 4; // 0x4 field public static final int EFFECT_STRENGTH_LIGHT = 0; // 0x0 field public static final int EFFECT_STRENGTH_MEDIUM = 1; // 0x1 @@ -1926,8 +1929,31 @@ package android.os { field @NonNull public static final android.os.Parcelable.Creator CREATOR; } + public static final class VibrationEffect.Composition { + method @NonNull public android.os.VibrationEffect.Composition addEffect(@NonNull android.os.VibrationEffect); + method @NonNull public android.os.VibrationEffect.Composition addOffDuration(@NonNull java.time.Duration); + method @NonNull public android.os.VibrationEffect.Composition repeatEffectIndefinitely(@NonNull android.os.VibrationEffect); + } + + public static final class VibrationEffect.Composition.UnreachableAfterRepeatingIndefinitelyException extends java.lang.IllegalStateException { + } + + public static class VibrationEffect.VibrationParameter { + method @NonNull public static android.os.VibrationEffect.VibrationParameter targetAmplitude(@FloatRange(from=0, to=1) float); + method @NonNull public static android.os.VibrationEffect.VibrationParameter targetFrequency(@FloatRange(from=1) float); + } + + public static final class VibrationEffect.WaveformBuilder { + method @NonNull public android.os.VibrationEffect.WaveformBuilder addSustain(@NonNull java.time.Duration); + method @NonNull public android.os.VibrationEffect.WaveformBuilder addTransition(@NonNull java.time.Duration, @NonNull android.os.VibrationEffect.VibrationParameter); + method @NonNull public android.os.VibrationEffect.WaveformBuilder addTransition(@NonNull java.time.Duration, @NonNull android.os.VibrationEffect.VibrationParameter, @NonNull android.os.VibrationEffect.VibrationParameter); + method @NonNull public android.os.VibrationEffect build(); + } + public abstract class Vibrator { method public int getDefaultVibrationIntensity(int); + method @Nullable public android.os.vibrator.VibratorFrequencyProfile getFrequencyProfile(); + method public boolean hasFrequencyControl(); field public static final int VIBRATION_INTENSITY_HIGH = 3; // 0x3 field public static final int VIBRATION_INTENSITY_LOW = 1; // 0x1 field public static final int VIBRATION_INTENSITY_MEDIUM = 2; // 0x2 @@ -2105,6 +2131,13 @@ package android.os.vibrator { field @NonNull public static final android.os.Parcelable.Creator CREATOR; } + public final class VibratorFrequencyProfile { + method public float getMaxAmplitudeMeasurementInterval(); + method @FloatRange(from=0, to=1) @NonNull public float[] getMaxAmplitudeMeasurements(); + method public float getMaxFrequency(); + method public float getMinFrequency(); + } + } package android.permission { diff --git a/core/java/android/os/VibrationEffect.java b/core/java/android/os/VibrationEffect.java index 71bc4b36f4e02..0723a628c03d3 100644 --- a/core/java/android/os/VibrationEffect.java +++ b/core/java/android/os/VibrationEffect.java @@ -413,7 +413,9 @@ public abstract class VibrationEffect implements Parcelable { * {@link #startWaveform(VibrationEffect.VibrationParameter)}. * * @see VibrationEffect.WaveformBuilder + * @hide */ + @TestApi @NonNull public static WaveformBuilder startWaveform() { return new WaveformBuilder(); @@ -431,7 +433,9 @@ public abstract class VibrationEffect implements Parcelable { * @return The {@link VibrationEffect.WaveformBuilder} started with the initial parameters. * * @see VibrationEffect.WaveformBuilder + * @hide */ + @TestApi @NonNull public static WaveformBuilder startWaveform(@NonNull VibrationParameter initialParameter) { WaveformBuilder builder = startWaveform(); @@ -454,7 +458,9 @@ public abstract class VibrationEffect implements Parcelable { * @return The {@link VibrationEffect.WaveformBuilder} started with the initial parameters. * * @see VibrationEffect.WaveformBuilder + * @hide */ + @TestApi @NonNull public static WaveformBuilder startWaveform(@NonNull VibrationParameter initialParameter1, @NonNull VibrationParameter initialParameter2) { @@ -824,29 +830,8 @@ public abstract class VibrationEffect implements Parcelable { * .addPrimitive(VibrationEffect.Composition.PRIMITIVE_TICK, 1.0f, 100) * .compose();} * - *

Composition elements can also be {@link VibrationEffect} instances, including other - * compositions, and off durations, which are periods of time when the vibrator will be - * turned off. Here is an example of a composition that "warms up" with a light tap, - * a stronger double tap, then repeats a vibration pattern indefinitely: - * - * 

-     * {@code VibrationEffect repeatingEffect = VibrationEffect.startComposition()
-     *     .addPrimitive(VibrationEffect.Composition.PRIMITIVE_LOW_TICK)
-     *     .addOffDuration(Duration.ofMillis(10))
-     *     .addEffect(VibrationEffect.createPredefined(VibrationEffect.EFFECT_DOUBLE_CLICK))
-     *     .addOffDuration(Duration.ofMillis(50))
-     *     .addEffect(VibrationEffect.createWaveform(pattern, repeatIndex))
-     *     .compose();}
- * *

When choosing to play a composed effect, you should check that individual components are - * supported by the device by using the appropriate vibrator method: - * - *

    - *
  • Primitive support can be checked using {@link Vibrator#arePrimitivesSupported}. - *
  • Effect support can be checked using {@link Vibrator#areEffectsSupported}. - *
  • Amplitude control for one-shot and waveforms with amplitude values can be checked - * using {@link Vibrator#hasAmplitudeControl}. - *
+ * supported by the device by using {@link Vibrator#arePrimitivesSupported}. * * @see VibrationEffect#startComposition() */ @@ -869,7 +854,9 @@ public abstract class VibrationEffect implements Parcelable { /** * Exception thrown when adding an element to a {@link Composition} that already ends in an * indefinitely repeating effect. + * @hide */ + @TestApi public static final class UnreachableAfterRepeatingIndefinitelyException extends IllegalStateException { UnreachableAfterRepeatingIndefinitelyException() { @@ -938,7 +925,9 @@ public abstract class VibrationEffect implements Parcelable { * * @throws UnreachableAfterRepeatingIndefinitelyException if the composition is currently * ending with a repeating effect. + * @hide */ + @TestApi @NonNull public Composition addOffDuration(@NonNull Duration duration) { int durationMs = (int) duration.toMillis(); @@ -965,7 +954,9 @@ public abstract class VibrationEffect implements Parcelable { * * @throws UnreachableAfterRepeatingIndefinitelyException if the composition is currently * ending with a repeating effect. + * @hide */ + @TestApi @NonNull public Composition addEffect(@NonNull VibrationEffect effect) { return addSegments(effect); @@ -987,7 +978,9 @@ public abstract class VibrationEffect implements Parcelable { * @throws IllegalArgumentException if the given effect is already repeating indefinitely. * @throws UnreachableAfterRepeatingIndefinitelyException if the composition is currently * ending with a repeating effect. + * @hide */ + @TestApi @NonNull public Composition repeatEffectIndefinitely(@NonNull VibrationEffect effect) { Preconditions.checkArgument(effect.getDuration() < Long.MAX_VALUE, @@ -1007,9 +1000,6 @@ public abstract class VibrationEffect implements Parcelable { * * @param primitiveId The primitive to add * @return This {@link Composition} object to enable adding multiple elements in one chain. - * - * @throws UnreachableAfterRepeatingIndefinitelyException if the composition is currently - * ending with a repeating effect. */ @NonNull public Composition addPrimitive(@PrimitiveType int primitiveId) { @@ -1024,9 +1014,6 @@ public abstract class VibrationEffect implements Parcelable { * @param primitiveId The primitive to add * @param scale The scale to apply to the intensity of the primitive. * @return This {@link Composition} object to enable adding multiple elements in one chain. - * - * @throws UnreachableAfterRepeatingIndefinitelyException if the composition is currently - * ending with a repeating effect. */ @NonNull public Composition addPrimitive(@PrimitiveType int primitiveId, @@ -1042,9 +1029,6 @@ public abstract class VibrationEffect implements Parcelable { * @param delay The amount of time in milliseconds to wait before playing this primitive, * starting at the time the previous element in this composition is finished. * @return This {@link Composition} object to enable adding multiple elements in one chain. - * - * @throws UnreachableAfterRepeatingIndefinitelyException if the composition is currently - * ending with a repeating effect. */ @NonNull public Composition addPrimitive(@PrimitiveType int primitiveId, @@ -1077,13 +1061,13 @@ public abstract class VibrationEffect implements Parcelable { } /** - * Compose all of the added elements together into a single {@link VibrationEffect}. + * Compose all of the added primitives together into a single {@link VibrationEffect}. * *

The {@link Composition} object is still valid after this call, so you can continue - * adding more elements to it and generating more {@link VibrationEffect}s by calling this + * adding more primitives to it and generating more {@link VibrationEffect}s by calling this * method again. * - * @return The {@link VibrationEffect} resulting from the composition of the elements. + * @return The {@link VibrationEffect} resulting from the composition of the primitives. */ @NonNull public VibrationEffect compose() { @@ -1202,7 +1186,9 @@ public abstract class VibrationEffect implements Parcelable { * .build();} * * @see VibrationEffect#startWaveform + * @hide */ + @TestApi public static final class WaveformBuilder { // Epsilon used for float comparison of amplitude and frequency values on transitions. private static final float EPSILON = 1e-5f; @@ -1229,7 +1215,9 @@ public abstract class VibrationEffect implements Parcelable { * after the given duration. * @return This {@link WaveformBuilder} object to enable adding multiple transitions in * chain. + * @hide */ + @TestApi @SuppressWarnings("MissingGetterMatchingBuilder") // No getters to segments once created. @NonNull public WaveformBuilder addTransition(@NonNull Duration duration, @@ -1261,7 +1249,9 @@ public abstract class VibrationEffect implements Parcelable { * than the one specified by the first argument. * @return This {@link WaveformBuilder} object to enable adding multiple transitions in * chain. + * @hide */ + @TestApi @SuppressWarnings("MissingGetterMatchingBuilder") // No getters to segments once created. @NonNull public WaveformBuilder addTransition(@NonNull Duration duration, @@ -1289,7 +1279,9 @@ public abstract class VibrationEffect implements Parcelable { * Value must be >= 1ms. * @return This {@link WaveformBuilder} object to enable adding multiple transitions in * chain. + * @hide */ + @TestApi @SuppressWarnings("MissingGetterMatchingBuilder") // No getters to segments once created. @NonNull public WaveformBuilder addSustain(@NonNull Duration duration) { @@ -1307,7 +1299,9 @@ public abstract class VibrationEffect implements Parcelable { * calling this method again. * * @return The {@link VibrationEffect} resulting from the list of transitions. + * @hide */ + @TestApi @NonNull public VibrationEffect build() { if (mSegments.isEmpty()) { @@ -1383,7 +1377,9 @@ public abstract class VibrationEffect implements Parcelable { *

Examples of concrete parameters are the vibration amplitude or frequency. * * @see VibrationEffect.WaveformBuilder + * @hide */ + @TestApi @SuppressWarnings("UserHandleName") // This is not a regular set of parameters, no *Params. public static class VibrationParameter { VibrationParameter() { @@ -1396,7 +1392,9 @@ public abstract class VibrationEffect implements Parcelable { * vibrator turned off and 1 represents the maximum amplitude the vibrator * can reach across all supported frequencies. * @return The {@link VibrationParameter} instance that represents given amplitude. + * @hide */ + @TestApi @NonNull public static VibrationParameter targetAmplitude( @FloatRange(from = 0, to = 1) float amplitude) { @@ -1408,7 +1406,9 @@ public abstract class VibrationEffect implements Parcelable { * * @param frequencyHz The frequency value, in hertz. * @return The {@link VibrationParameter} instance that represents given frequency. + * @hide */ + @TestApi @NonNull public static VibrationParameter targetFrequency(@FloatRange(from = 1) float frequencyHz) { return new FrequencyVibrationParameter(frequencyHz); diff --git a/core/java/android/os/Vibrator.java b/core/java/android/os/Vibrator.java index fb3230093f24d..7edcdd754f063 100644 --- a/core/java/android/os/Vibrator.java +++ b/core/java/android/os/Vibrator.java @@ -212,7 +212,9 @@ public abstract class Vibrator { * * @return True if the hardware can control the frequency of the vibrations independently of * the vibration amplitude, false otherwise. + * @hide */ + @TestApi public boolean hasFrequencyControl() { // We currently can only control frequency of the vibration using the compose PWLE method. return getInfo().hasCapability( @@ -262,7 +264,9 @@ public abstract class Vibrator { * frequency control. If this vibrator is a composite of multiple physical devices then this * will return a profile supported in all devices, or null if the intersection is empty or not * available. + * @hide */ + @TestApi @Nullable public VibratorFrequencyProfile getFrequencyProfile() { VibratorInfo.FrequencyProfile frequencyProfile = getInfo().getFrequencyProfile(); diff --git a/core/java/android/os/vibrator/VibratorFrequencyProfile.java b/core/java/android/os/vibrator/VibratorFrequencyProfile.java index 0f2aa157d94c1..8392940010e31 100644 --- a/core/java/android/os/vibrator/VibratorFrequencyProfile.java +++ b/core/java/android/os/vibrator/VibratorFrequencyProfile.java @@ -18,6 +18,7 @@ package android.os.vibrator; import android.annotation.FloatRange; import android.annotation.NonNull; +import android.annotation.TestApi; import android.os.VibratorInfo; import com.android.internal.util.Preconditions; @@ -38,7 +39,9 @@ import com.android.internal.util.Preconditions; * frequency increment between each pair of amplitude values. * *

Vibrators without independent frequency control do not have a frequency profile. + * @hide */ +@TestApi public final class VibratorFrequencyProfile { private final VibratorInfo.FrequencyProfile mFrequencyProfile; @@ -62,7 +65,9 @@ public final class VibratorFrequencyProfile { * {@link #getMinFrequency()} to {@link #getMaxFrequency()}, inclusive. * * @return Array of maximum relative amplitude measurements. + * @hide */ + @TestApi @NonNull @FloatRange(from = 0, to = 1) public float[] getMaxAmplitudeMeasurements() { @@ -74,7 +79,9 @@ public final class VibratorFrequencyProfile { * Gets the frequency interval used to measure the maximum relative amplitudes. * * @return the frequency interval used for the measurement, in hertz. + * @hide */ + @TestApi public float getMaxAmplitudeMeasurementInterval() { return mFrequencyProfile.getFrequencyResolutionHz(); } @@ -83,7 +90,9 @@ public final class VibratorFrequencyProfile { * Gets the minimum frequency supported by the vibrator. * * @return the minimum frequency supported by the vibrator, in hertz. + * @hide */ + @TestApi public float getMinFrequency() { return mFrequencyProfile.getFrequencyRangeHz().getLower(); } @@ -92,7 +101,9 @@ public final class VibratorFrequencyProfile { * Gets the maximum frequency supported by the vibrator. * * @return the maximum frequency supported by the vibrator, in hertz. + * @hide */ + @TestApi public float getMaxFrequency() { return mFrequencyProfile.getFrequencyRangeHz().getUpper(); }