Loading core/java/android/os/VibrationAttributes.java +14 −16 Original line number Diff line number Diff line Loading @@ -106,20 +106,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; /** Loading Loading @@ -183,7 +191,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() { Loading @@ -192,7 +199,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() { Loading Loading @@ -429,16 +435,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) { Loading core/java/android/os/VibrationEffect.java +20 −21 Original line number Diff line number Diff line Loading @@ -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. */ Loading @@ -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 Loading @@ -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. */ Loading core/java/android/os/Vibrator.java +40 −19 Original line number Diff line number Diff line Loading @@ -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; Loading Loading @@ -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 Loading @@ -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( Loading @@ -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. */ Loading @@ -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) { Loading Loading
core/java/android/os/VibrationAttributes.java +14 −16 Original line number Diff line number Diff line Loading @@ -106,20 +106,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; /** Loading Loading @@ -183,7 +191,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() { Loading @@ -192,7 +199,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() { Loading Loading @@ -429,16 +435,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) { Loading
core/java/android/os/VibrationEffect.java +20 −21 Original line number Diff line number Diff line Loading @@ -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. */ Loading @@ -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 Loading @@ -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. */ Loading
core/java/android/os/Vibrator.java +40 −19 Original line number Diff line number Diff line Loading @@ -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; Loading Loading @@ -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 Loading @@ -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( Loading @@ -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. */ Loading @@ -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) { Loading
