VibrationEffect.Composition


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();

When choosing to play a composed effect, you should check that individual components are supported by the device by using Vibrator#arePrimitivesSupported.

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

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.

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.

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.

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.