Added in API level 30

Summary: Constants | Methods | Inherited Methods

VibrationEffect.Composition

Kotlin |Java

public static final class VibrationEffect.Composition
extends Object

java.lang.Object
↳	android.os.VibrationEffect.Composition

A composition of haptic elements that are combined to be playable as a single VibrationEffect.

The haptic primitives are available as Composition.PRIMITIVE_* constants and can be added to a composition to create a custom vibration effect. Here is an example of an effect that grows in intensity and then dies off, with a longer rising portion for emphasis and an extra tick 100ms after:

 VibrationEffect effect = VibrationEffect.startComposition()
     .addPrimitive(VibrationEffect.Composition.PRIMITIVE_SLOW_RISE, 0.5f)
     .addPrimitive(VibrationEffect.Composition.PRIMITIVE_QUICK_FALL, 0.5f)
     .addPrimitive(VibrationEffect.Composition.PRIMITIVE_TICK, 1.0f, 100)
     .compose();

Composition elements can also be 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:

 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 Vibrator#arePrimitivesSupported.
Effect support can be checked using Vibrator#areEffectsSupported.
Amplitude control for one-shot and waveforms with amplitude values can be checked using Vibrator#hasAmplitudeControl.

See also:

VibrationEffect.startComposition()

Summary

Constants
`int`	`PRIMITIVE_CLICK` This effect should produce a sharp, crisp click sensation.
`int`	`PRIMITIVE_LOW_TICK` This very short low frequency effect should produce a light crisp sensation intended to be used repetitively for dynamic feedback.
`int`	`PRIMITIVE_QUICK_FALL` A haptic effect that simulates quick downwards movement with gravity.
`int`	`PRIMITIVE_QUICK_RISE` A haptic effect that simulates quick upward movement against gravity.
`int`	`PRIMITIVE_SLOW_RISE` A haptic effect that simulates slow upward movement against gravity.
`int`	`PRIMITIVE_SPIN` A haptic effect that simulates spinning momentum.
`int`	`PRIMITIVE_THUD` A haptic effect that simulates downwards movement with gravity.
`int`	`PRIMITIVE_TICK` This very short effect should produce a light crisp sensation intended to be used repetitively for dynamic feedback.

Public methods
`VibrationEffect.Composition`	`addPrimitive(int primitiveId)` Add a haptic primitive to the end of the current composition.
`VibrationEffect.Composition`	`addPrimitive(int primitiveId, float scale, int delay)` Add a haptic primitive to the end of the current composition.
`VibrationEffect.Composition`	`addPrimitive(int primitiveId, float scale)` Add a haptic primitive to the end of the current composition.
`VibrationEffect`	`compose()` Compose all of the added primitives together into a single `VibrationEffect`.

Inherited methods

From class


        
          java.lang.Object

`Object`	`clone()` Creates and returns a copy of this object.
`boolean`	`equals(Object obj)` Indicates whether some other object is "equal to" this one.
`void`	`finalize()` Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.
`final Class<?>`	`getClass()` Returns the runtime class of this `Object`.
`int`	`hashCode()` Returns a hash code value for the object.
`final void`	`notify()` Wakes up a single thread that is waiting on this object's monitor.
`final void`	`notifyAll()` Wakes up all threads that are waiting on this object's monitor.
`String`	`toString()` Returns a string representation of the object.
`final void`	`wait(long timeout, int nanos)` Causes the current thread to wait until another thread invokes the `notify()` method or the `notifyAll()` method for this object, or some other thread interrupts the current thread, or a certain amount of real time has elapsed.
`final void`	`wait(long timeout)` Causes the current thread to wait until either another thread invokes the `notify()` method or the `notifyAll()` method for this object, or a specified amount of time has elapsed.
`final void`	`wait()` Causes the current thread to wait until another thread invokes the `notify()` method or the `notifyAll()` method for this object.

Constants

PRIMITIVE_CLICK

Added in API level 30

public static final int PRIMITIVE_CLICK

This effect should produce a sharp, crisp click sensation.

Constant Value: 1 (0x00000001)

PRIMITIVE_LOW_TICK

Added in API level 31

public static final int PRIMITIVE_LOW_TICK

This very short low frequency effect should produce a light crisp sensation intended to be used repetitively for dynamic feedback.

Constant Value: 8 (0x00000008)

PRIMITIVE_QUICK_FALL

Added in API level 30

public static final int PRIMITIVE_QUICK_FALL

A haptic effect that simulates quick downwards movement with gravity.

Constant Value: 6 (0x00000006)

PRIMITIVE_QUICK_RISE

Added in API level 30

public static final int PRIMITIVE_QUICK_RISE

A haptic effect that simulates quick upward movement against gravity.

Constant Value: 4 (0x00000004)

PRIMITIVE_SLOW_RISE

Added in API level 30

public static final int PRIMITIVE_SLOW_RISE

A haptic effect that simulates slow upward movement against gravity.

Constant Value: 5 (0x00000005)

PRIMITIVE_SPIN

Added in API level 31

public static final int PRIMITIVE_SPIN

A haptic effect that simulates spinning momentum.

Constant Value: 3 (0x00000003)

PRIMITIVE_THUD

Added in API level 31

public static final int PRIMITIVE_THUD

A haptic effect that simulates downwards movement with gravity. Often followed by extra energy of hitting and reverberation to augment physicality.

Constant Value: 2 (0x00000002)

PRIMITIVE_TICK

Added in API level 30

public static final int PRIMITIVE_TICK

This very short effect should produce a light crisp sensation intended to be used repetitively for dynamic feedback.

Constant Value: 7 (0x00000007)

Public methods

addPrimitive

Added in API level 30

public VibrationEffect.Composition addPrimitive (int primitiveId)

Add a haptic primitive to the end of the current composition.

Similar to addPrimitive(int, float, int), but with no delay and a default scale applied.

Parameters
`primitiveId`	`int`: The primitive to add Value is `PRIMITIVE_CLICK`, `PRIMITIVE_THUD`, `PRIMITIVE_SPIN`, `PRIMITIVE_QUICK_RISE`, `PRIMITIVE_SLOW_RISE`, `PRIMITIVE_QUICK_FALL`, `PRIMITIVE_TICK`, or `PRIMITIVE_LOW_TICK`

Returns
`VibrationEffect.Composition`	This `Composition` object to enable adding multiple elements in one chain. This value cannot be `null`.

Throws
`VibrationEffect.Composition.UnreachableAfterRepeatingIndefinitelyException`	if the composition is currently ending with a repeating effect.

addPrimitive

Added in API level 30

public VibrationEffect.Composition addPrimitive (int primitiveId, 
                float scale, 
                int delay)

Add a haptic primitive to the end of the current composition.

Parameters
`primitiveId`	`int`: The primitive to add Value is `PRIMITIVE_CLICK`, `PRIMITIVE_THUD`, `PRIMITIVE_SPIN`, `PRIMITIVE_QUICK_RISE`, `PRIMITIVE_SLOW_RISE`, `PRIMITIVE_QUICK_FALL`, `PRIMITIVE_TICK`, or `PRIMITIVE_LOW_TICK`
`scale`	`float`: The scale to apply to the intensity of the primitive. Value is between 0f and 1f inclusive
`delay`	`int`: The amount of time in milliseconds to wait before playing this primitive, starting at the time the previous element in this composition is finished. Value is 0 or greater

Returns
`VibrationEffect.Composition`	This `Composition` object to enable adding multiple elements in one chain. This value cannot be `null`.

Throws
`VibrationEffect.Composition.UnreachableAfterRepeatingIndefinitelyException`	if the composition is currently ending with a repeating effect.

addPrimitive

Added in API level 30

public VibrationEffect.Composition addPrimitive (int primitiveId, 
                float scale)

Add a haptic primitive to the end of the current composition.

Similar to addPrimitive(int, float, int), but with no delay.

Parameters
`primitiveId`	`int`: The primitive to add Value is `PRIMITIVE_CLICK`, `PRIMITIVE_THUD`, `PRIMITIVE_SPIN`, `PRIMITIVE_QUICK_RISE`, `PRIMITIVE_SLOW_RISE`, `PRIMITIVE_QUICK_FALL`, `PRIMITIVE_TICK`, or `PRIMITIVE_LOW_TICK`
`scale`	`float`: The scale to apply to the intensity of the primitive. Value is between 0f and 1f inclusive

Returns
`VibrationEffect.Composition`	This `Composition` object to enable adding multiple elements in one chain. This value cannot be `null`.

Throws
`VibrationEffect.Composition.UnreachableAfterRepeatingIndefinitelyException`	if the composition is currently ending with a repeating effect.

compose

Added in API level 30

public VibrationEffect compose ()

Compose all of the added primitives together into a single VibrationEffect.

The Composition object is still valid after this call, so you can continue adding more primitives to it and generating more VibrationEffects by calling this method again.

Returns
`VibrationEffect`	The `VibrationEffect` resulting from the composition of the primitives. This value cannot be `null`.