Improve javadoc for some vibration functions. (03a52de3) · Commits · e / os / android_frameworks_base

core/java/android/os/VibrationAttributes.java

+14 −17

Original line number	Original line	Diff line number	Diff line
	@@ -105,20 +105,28 @@ public final class VibrationAttributes implements Parcelable {
	public static final int USAGE_NOTIFICATION = 0x30 \| USAGE_CLASS_ALARM;		public static final int USAGE_NOTIFICATION = 0x30 \| USAGE_CLASS_ALARM;
	/**		/**
	* Usage value to use for vibrations which mean a request to enter/end a		* 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;		public static final int USAGE_COMMUNICATION_REQUEST = 0x40 \| USAGE_CLASS_ALARM;
	/**		/**
	* Usage value to use for touch vibrations.		* 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;		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;		public static final int USAGE_PHYSICAL_EMULATION = 0x20 \| USAGE_CLASS_FEEDBACK;
	/**		/**
	* Usage value to use for vibrations which provide a feedback for hardware interaction,		* Usage value to use for vibrations which provide a feedback for hardware
	* such as a fingerprint sensor.		* component interaction, such as a fingerprint sensor.
	*/		*/
	public static final int USAGE_HARDWARE_FEEDBACK = 0x30 \| USAGE_CLASS_FEEDBACK;		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 the vibration usage class.
	* @return USAGE_CLASS_ALARM, USAGE_CLASS_FEEDBACK or USAGE_CLASS_UNKNOWN
	*/		*/
	@UsageClass		@UsageClass
	public int getUsageClass() {		public int getUsageClass() {
	@@ -191,7 +198,6 @@ public final class VibrationAttributes implements Parcelable {

	/**		/**
	* Return the vibration usage.		* Return the vibration usage.
	* @return one of the values that can be set in {@link Builder#setUsage(int)}
	*/		*/
	@Usage		@Usage
	public int getUsage() {		public int getUsage() {
	@@ -428,16 +434,8 @@ public final class VibrationAttributes implements Parcelable {
	}		}

	/**		/**
	* Sets the attribute describing the type of corresponding vibration.		* Sets the attribute describing the type of the corresponding vibration.
	* @param usage one of {@link VibrationAttributes#USAGE_ALARM},		* @param usage The type of usage for the vibration
	* {@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}.
	* @return the same Builder instance.		* @return the same Builder instance.
	*/		*/
	public @NonNull Builder setUsage(@Usage int usage) {		public @NonNull Builder setUsage(@Usage int usage) {
	@@ -459,4 +457,3 @@ public final class VibrationAttributes implements Parcelable {
	}		}
	}		}
	}		}

core/java/android/os/VibrationEffect.java

+20 −21

Original line number	Original line	Diff line number	Diff line
	@@ -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		* <p>In effect, the timings array represents the number of milliseconds <em>before</em> turning
	* each pair, the value in the amplitude array determines the strength of the vibration and the		* the vibrator on, followed by the number of milliseconds to keep the vibrator on, then
	* value in the timing array determines how long it vibrates for. An amplitude of 0 implies no		* the number of milliseconds turned off, and so on. Consequently, the first timing value will
	* vibration (i.e. off), and any pairs with a timing value of 0 will be ignored.		* 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		* <p>This method is equivalent to calling {@link #createWaveform(long[], int[], int)} with
	* timing array with alternating values of 0 (i.e. off) and {@link #DEFAULT_AMPLITUDE},		* corresponding amplitude values alternating between 0 and {@link #DEFAULT_AMPLITUDE},
	* starting with 0. Therefore the first timing value will be the period to wait before turning		* beginning with 0.
	* the vibrator on, the second value will be how long to vibrate at {@link #DEFAULT_AMPLITUDE}
	* strength, etc.
	*		*
	* <p>To cause the pattern to repeat, pass the index into the timings array at which to start		* <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		* the repetition, or -1 to disable repeating. Repeating effects will be played indefinitely
	* and should be cancelled via {@link Vibrator#cancel()}.		* and should be cancelled via {@link Vibrator#cancel()}.
	*		*
	* @param timings The pattern of alternating on-off timings, starting with off. Timing values		* @param timings The pattern of alternating on-off timings, starting with an 'off' timing, and
	* of 0 will cause the timing / amplitude pair to be ignored.		* representing the length of time to sustain the individual item (not
	* @param repeat The index into the timings array at which to repeat, or -1 if you you don't		* cumulative).
	* 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.		* @return The desired effect.
	*/		*/
	@@ -229,11 +229,10 @@ public abstract class VibrationEffect implements Parcelable {
	/**		/**
	* Create a waveform vibration.		* Create a waveform vibration.
	*		*
	* <p>Waveform vibrations are a potentially repeating series of timing and amplitude pairs. For		* <p>Waveform vibrations are a potentially repeating series of timing and amplitude pairs,
	* each pair, the value in the amplitude array determines the strength of the vibration and the		* provided in separate arrays. For each pair, the value in the amplitude array determines
	* value in the timing array determines how long it vibrates for, in milliseconds. Amplitude		* the strength of the vibration and the value in the timing array determines how long it
	* values must be between 0 and 255, and an amplitude of 0 implies no vibration (i.e. off). Any		* vibrates for, in milliseconds.
	* pairs with a timing value of 0 will be ignored.
	*		*
	* <p>To cause the pattern to repeat, pass the index into the timings array at which to start		* <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		* 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		* @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		* must be between 0 and 255, or equal to {@link #DEFAULT_AMPLITUDE}. An
	* amplitude value of 0 implies the motor is off.		* 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		* @param repeat The index into the timings array at which to repeat, or -1 if you don't
	* want to repeat.		* want to repeat indefinitely.
	*		*
	* @return The desired effect.		* @return The desired effect.
	*/		*/

core/java/android/os/Vibrator.java

+40 −19

Original line number	Original line	Diff line number	Diff line
	@@ -98,7 +98,8 @@ public abstract class Vibrator {
	/**		/**
	* Vibration effect support: unsupported		* 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;		public static final int VIBRATION_EFFECT_SUPPORT_NO = 2;

	@@ -485,20 +486,25 @@ public abstract class Vibrator {
	String reason, @NonNull VibrationAttributes attributes);		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		* <p>If an effect is not supported, the system may still automatically fall back to playing
	* whether an effect is supported or not.		* 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		* <p>The returned array will be the same length as the query array and the value at a given
	* will contain {@link #VIBRATION_EFFECT_SUPPORT_YES} if the effect at that same index in the		* index will contain {@link #VIBRATION_EFFECT_SUPPORT_YES} if the effect at that same index
	* querying array is supported, {@link #VIBRATION_EFFECT_SUPPORT_NO} if it isn't supported, or		* in the querying array is supported, {@link #VIBRATION_EFFECT_SUPPORT_NO} if it isn't
	* {@link #VIBRATION_EFFECT_SUPPORT_UNKNOWN} if the system can't determine whether it's		* supported, or {@link #VIBRATION_EFFECT_SUPPORT_UNKNOWN} if the system can't determine whether
	* supported or not.		* 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.		* @param effectIds Which effects to query for.
	* @return An array containing the systems current knowledge about whether the given effects		* @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		@NonNull
	@VibrationEffectSupport		@VibrationEffectSupport
	@@ -515,23 +521,27 @@ public abstract class Vibrator {
	/**		/**
	* Query whether the vibrator supports all of the given effects.		* Query whether the vibrator supports all of the given effects.
	*		*
	* Not all hardware reports its effect capabilities, so the system may not necessarily know		* <p>If an effect is not supported, the system may still automatically fall back to a simpler
	* whether an effect is supported or not.		* 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.		* supported by the hardware.
	*		*
	* If the result is {@link #VIBRATION_EFFECT_SUPPORT_NO}, at least one of the effects in the		* <p>If the result is {@link #VIBRATION_EFFECT_SUPPORT_NO}, at least one of the effects in the
	* query is not supported.		* 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		* <p>If the result is {@link #VIBRATION_EFFECT_SUPPORT_UNKNOWN}, the system doesn't know
	* all of the effects are supported. It may support any or all of the queried effects,		* 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		* 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		* cause a vibration. It's guaranteed, however, that none of the queried effects are
	* definitively unsupported by the hardware.		* definitively unsupported by the hardware.
	*		*
			* <p>Use {@link #areEffectsSupported(int...)} to get individual results for each effect.
			*
	* @param effectIds Which effects to query for.		* @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		@VibrationEffectSupport
	public final int areAllEffectsSupported(		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		* will contain whether the effect at that same index in the querying array is supported or
	* not.		* 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.		* @param primitiveIds Which primitives to query for.
	* @return Whether the primitives are supported.		* @return Whether the primitives are supported.
	*/		*/
	@@ -572,8 +588,13 @@ public abstract class Vibrator {
	/**		/**
	* Query whether the vibrator supports all of the given primitives.		* 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.		* @param primitiveIds Which primitives to query for.
	* @return Whether primitives effects are supported.		* @return Whether all specified primitives are supported.
	*/		*/
	public final boolean areAllPrimitivesSupported(		public final boolean areAllPrimitivesSupported(
	@NonNull @VibrationEffect.Composition.PrimitiveType int... primitiveIds) {		@NonNull @VibrationEffect.Composition.PrimitiveType int... primitiveIds) {