Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge "Improve javadoc for some vibration functions."

Browse Source
This commit is contained in:
TreeHugger Robot
2022-01-31 11:25:18 +00:00
committed by Android (Google) Code Review
parent a38e938b6f 03a52de384
commit d42a4f09c6
3 changed files with 74 additions and 56 deletions
Download Patch File Download Diff File Expand all files Collapse all files

30
core/java/android/os/VibrationAttributes.java
View File

@@ -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;
/**
@@ -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() {
@@ -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() {
@@ -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) {

41
core/java/android/os/VibrationEffect.java
View File

@@ -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.
*/

59
core/java/android/os/Vibrator.java
View File

@@ -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) {