diff options
| -rw-r--r-- | core/java/android/os/VibrationAttributes.java | 31 | ||||
| -rw-r--r-- | core/java/android/os/VibrationEffect.java | 41 | ||||
| -rw-r--r-- | core/java/android/os/Vibrator.java | 59 |
3 files changed, 74 insertions, 57 deletions
diff --git a/core/java/android/os/VibrationAttributes.java b/core/java/android/os/VibrationAttributes.java index 8bc219b7dc57..5f079da0c590 100644 --- a/core/java/android/os/VibrationAttributes.java +++ b/core/java/android/os/VibrationAttributes.java @@ -105,20 +105,28 @@ public final class VibrationAttributes implements Parcelable { public static final int USAGE_NOTIFICATION = 0x30 | USAGE_CLASS_ALARM; /** * Usage value to use for vibrations which mean a request to enter/end a - * communication, such as a VoIP communication or video-conference. + * communication with the user, such as a voice prompt. */ public static final int USAGE_COMMUNICATION_REQUEST = 0x40 | USAGE_CLASS_ALARM; /** * Usage value to use for touch vibrations. + * + * <p>Most typical haptic feedback should be classed as <em>touch</em> feedback. Examples + * include vibrations for tap, long press, drag and scroll. */ public static final int USAGE_TOUCH = 0x10 | USAGE_CLASS_FEEDBACK; /** - * Usage value to use for vibrations which emulate physical effects, such as edge squeeze. + * Usage value to use for vibrations which emulate physical hardware reactions, + * such as edge squeeze. + * + * <p>Note that normal screen-touch feedback "click" effects would typically be + * classed as {@link #USAGE_TOUCH}, and that on-screen "physical" animations + * like bouncing would be {@link #USAGE_MEDIA}. */ public static final int USAGE_PHYSICAL_EMULATION = 0x20 | USAGE_CLASS_FEEDBACK; /** - * Usage value to use for vibrations which provide a feedback for hardware interaction, - * such as a fingerprint sensor. + * Usage value to use for vibrations which provide a feedback for hardware + * component interaction, such as a fingerprint sensor. */ public static final int USAGE_HARDWARE_FEEDBACK = 0x30 | USAGE_CLASS_FEEDBACK; /** @@ -182,7 +190,6 @@ public final class VibrationAttributes implements Parcelable { /** * Return the vibration usage class. - * @return USAGE_CLASS_ALARM, USAGE_CLASS_FEEDBACK or USAGE_CLASS_UNKNOWN */ @UsageClass public int getUsageClass() { @@ -191,7 +198,6 @@ public final class VibrationAttributes implements Parcelable { /** * Return the vibration usage. - * @return one of the values that can be set in {@link Builder#setUsage(int)} */ @Usage public int getUsage() { @@ -428,16 +434,8 @@ public final class VibrationAttributes implements Parcelable { } /** - * Sets the attribute describing the type of corresponding vibration. - * @param usage one of {@link VibrationAttributes#USAGE_ALARM}, - * {@link VibrationAttributes#USAGE_RINGTONE}, - * {@link VibrationAttributes#USAGE_NOTIFICATION}, - * {@link VibrationAttributes#USAGE_COMMUNICATION_REQUEST}, - * {@link VibrationAttributes#USAGE_TOUCH}, - * {@link VibrationAttributes#USAGE_PHYSICAL_EMULATION}, - * {@link VibrationAttributes#USAGE_HARDWARE_FEEDBACK}. - * {@link VibrationAttributes#USAGE_ACCESSIBILITY}. - * {@link VibrationAttributes#USAGE_MEDIA}. + * Sets the attribute describing the type of the corresponding vibration. + * @param usage The type of usage for the vibration * @return the same Builder instance. */ public @NonNull Builder setUsage(@Usage int usage) { @@ -459,4 +457,3 @@ public final class VibrationAttributes implements Parcelable { } } } - diff --git a/core/java/android/os/VibrationEffect.java b/core/java/android/os/VibrationEffect.java index f490587ae1e1..9598410d8f33 100644 --- a/core/java/android/os/VibrationEffect.java +++ b/core/java/android/os/VibrationEffect.java @@ -194,27 +194,27 @@ public abstract class VibrationEffect implements Parcelable { } /** - * Create a waveform vibration. + * Create a waveform vibration, using only off/on transitions at the provided time intervals, + * and potentially repeating. * - * <p>Waveform vibrations are a potentially repeating series of timing and amplitude pairs. For - * each pair, the value in the amplitude array determines the strength of the vibration and the - * value in the timing array determines how long it vibrates for. An amplitude of 0 implies no - * vibration (i.e. off), and any pairs with a timing value of 0 will be ignored. + * <p>In effect, the timings array represents the number of milliseconds <em>before</em> turning + * the vibrator on, followed by the number of milliseconds to keep the vibrator on, then + * the number of milliseconds turned off, and so on. Consequently, the first timing value will + * often be 0, so that the effect will start vibrating immediately. * - * <p>The amplitude array of the generated waveform will be the same size as the given - * timing array with alternating values of 0 (i.e. off) and {@link #DEFAULT_AMPLITUDE}, - * starting with 0. Therefore the first timing value will be the period to wait before turning - * the vibrator on, the second value will be how long to vibrate at {@link #DEFAULT_AMPLITUDE} - * strength, etc. + * <p>This method is equivalent to calling {@link #createWaveform(long[], int[], int)} with + * corresponding amplitude values alternating between 0 and {@link #DEFAULT_AMPLITUDE}, + * beginning with 0. * * <p>To cause the pattern to repeat, pass the index into the timings array at which to start * the repetition, or -1 to disable repeating. Repeating effects will be played indefinitely * and should be cancelled via {@link Vibrator#cancel()}. * - * @param timings The pattern of alternating on-off timings, starting with off. Timing values - * of 0 will cause the timing / amplitude pair to be ignored. - * @param repeat The index into the timings array at which to repeat, or -1 if you you don't - * want to repeat. + * @param timings The pattern of alternating on-off timings, starting with an 'off' timing, and + * representing the length of time to sustain the individual item (not + * cumulative). + * @param repeat The index into the timings array at which to repeat, or -1 if you don't + * want to repeat indefinitely. * * @return The desired effect. */ @@ -229,11 +229,10 @@ public abstract class VibrationEffect implements Parcelable { /** * Create a waveform vibration. * - * <p>Waveform vibrations are a potentially repeating series of timing and amplitude pairs. For - * each pair, the value in the amplitude array determines the strength of the vibration and the - * value in the timing array determines how long it vibrates for, in milliseconds. Amplitude - * values must be between 0 and 255, and an amplitude of 0 implies no vibration (i.e. off). Any - * pairs with a timing value of 0 will be ignored. + * <p>Waveform vibrations are a potentially repeating series of timing and amplitude pairs, + * provided in separate arrays. For each pair, the value in the amplitude array determines + * the strength of the vibration and the value in the timing array determines how long it + * vibrates for, in milliseconds. * * <p>To cause the pattern to repeat, pass the index into the timings array at which to start * the repetition, or -1 to disable repeating. Repeating effects will be played indefinitely @@ -244,8 +243,8 @@ public abstract class VibrationEffect implements Parcelable { * @param amplitudes The amplitude values of the timing / amplitude pairs. Amplitude values * must be between 0 and 255, or equal to {@link #DEFAULT_AMPLITUDE}. An * amplitude value of 0 implies the motor is off. - * @param repeat The index into the timings array at which to repeat, or -1 if you you don't - * want to repeat. + * @param repeat The index into the timings array at which to repeat, or -1 if you don't + * want to repeat indefinitely. * * @return The desired effect. */ diff --git a/core/java/android/os/Vibrator.java b/core/java/android/os/Vibrator.java index 23baa5d70c66..8f5086021530 100644 --- a/core/java/android/os/Vibrator.java +++ b/core/java/android/os/Vibrator.java @@ -98,7 +98,8 @@ public abstract class Vibrator { /** * Vibration effect support: unsupported * - * This effect is <b>not</b> supported by the underlying hardware. + * This effect is <b>not</b> natively supported by the underlying hardware, although + * the system may still play a fallback vibration. */ public static final int VIBRATION_EFFECT_SUPPORT_NO = 2; @@ -485,20 +486,25 @@ public abstract class Vibrator { String reason, @NonNull VibrationAttributes attributes); /** - * Query whether the vibrator supports the given effects. + * Query whether the vibrator natively supports the given effects. * - * Not all hardware reports its effect capabilities, so the system may not necessarily know - * whether an effect is supported or not. + * <p>If an effect is not supported, the system may still automatically fall back to playing + * a simpler vibration instead, which is not optimised for the specific device. This includes + * the unknown case, which can't be determined in advance, that will dynamically attempt to + * fall back if the optimised effect fails to play. * - * The returned array will be the same length as the query array and the value at a given index - * will contain {@link #VIBRATION_EFFECT_SUPPORT_YES} if the effect at that same index in the - * querying array is supported, {@link #VIBRATION_EFFECT_SUPPORT_NO} if it isn't supported, or - * {@link #VIBRATION_EFFECT_SUPPORT_UNKNOWN} if the system can't determine whether it's - * supported or not. + * <p>The returned array will be the same length as the query array and the value at a given + * index will contain {@link #VIBRATION_EFFECT_SUPPORT_YES} if the effect at that same index + * in the querying array is supported, {@link #VIBRATION_EFFECT_SUPPORT_NO} if it isn't + * supported, or {@link #VIBRATION_EFFECT_SUPPORT_UNKNOWN} if the system can't determine whether + * it's supported or not, as some hardware doesn't report its effect capabilities. + * + * <p>Use {@link #areAllEffectsSupported(int...)} to get a single combined result, + * or for convenience when querying exactly one effect. * * @param effectIds Which effects to query for. * @return An array containing the systems current knowledge about whether the given effects - * are supported or not. + * are natively supported by the device, or not. */ @NonNull @VibrationEffectSupport @@ -515,23 +521,27 @@ public abstract class Vibrator { /** * Query whether the vibrator supports all of the given effects. * - * Not all hardware reports its effect capabilities, so the system may not necessarily know - * whether an effect is supported or not. + * <p>If an effect is not supported, the system may still automatically fall back to a simpler + * vibration instead, which is not optimised for the specific device, however vibration isn't + * guaranteed in this case. * - * If the result is {@link #VIBRATION_EFFECT_SUPPORT_YES}, all effects in the query are + * <p>If the result is {@link #VIBRATION_EFFECT_SUPPORT_YES}, all effects in the query are * supported by the hardware. * - * If the result is {@link #VIBRATION_EFFECT_SUPPORT_NO}, at least one of the effects in the - * query is not supported. + * <p>If the result is {@link #VIBRATION_EFFECT_SUPPORT_NO}, at least one of the effects in the + * query is not supported, and using them may fall back to an un-optimized vibration or no + * vibration. * - * If the result is {@link #VIBRATION_EFFECT_SUPPORT_UNKNOWN}, the system doesn't know whether - * all of the effects are supported. It may support any or all of the queried effects, + * <p>If the result is {@link #VIBRATION_EFFECT_SUPPORT_UNKNOWN}, the system doesn't know + * whether all of the effects are supported. It may support any or all of the queried effects, * but there's no way to programmatically know whether a {@link #vibrate} call will successfully * cause a vibration. It's guaranteed, however, that none of the queried effects are * definitively unsupported by the hardware. * + * <p>Use {@link #areEffectsSupported(int...)} to get individual results for each effect. + * * @param effectIds Which effects to query for. - * @return Whether all of the effects are supported. + * @return Whether all of the effects are natively supported by the device. */ @VibrationEffectSupport public final int areAllEffectsSupported( @@ -555,6 +565,12 @@ public abstract class Vibrator { * will contain whether the effect at that same index in the querying array is supported or * not. * + * <p>If a primitive is not supported by the device, then <em>no vibration</em> will occur if + * it is played. + * + * <p>Use {@link #areAllPrimitivesSupported(int...)} to get a single combined result, + * or for convenience when querying exactly one primitive. + * * @param primitiveIds Which primitives to query for. * @return Whether the primitives are supported. */ @@ -572,8 +588,13 @@ public abstract class Vibrator { /** * Query whether the vibrator supports all of the given primitives. * + * <p>If a primitive is not supported by the device, then <em>no vibration</em> will occur if + * it is played. + * + * <p>Use {@link #arePrimitivesSupported(int...)} to get individual results for each primitive. + * * @param primitiveIds Which primitives to query for. - * @return Whether primitives effects are supported. + * @return Whether all specified primitives are supported. */ public final boolean areAllPrimitivesSupported( @NonNull @VibrationEffect.Composition.PrimitiveType int... primitiveIds) { |