Composition

Kotlin |Java

class Composition

kotlin.Any
↳	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:

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

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

Summary

Constants
static Int	`PRIMITIVE_CLICK` This effect should produce a sharp, crisp click sensation.
static Int	`PRIMITIVE_LOW_TICK` This very short low frequency effect should produce a light crisp sensation intended to be used repetitively for dynamic feedback.
static Int	`PRIMITIVE_QUICK_FALL` A haptic effect that simulates quick downwards movement with gravity.
static Int	`PRIMITIVE_QUICK_RISE` A haptic effect that simulates quick upward movement against gravity.
static Int	`PRIMITIVE_SLOW_RISE` A haptic effect that simulates slow upward movement against gravity.
static Int	`PRIMITIVE_SPIN` A haptic effect that simulates spinning momentum.
static Int	`PRIMITIVE_THUD` A haptic effect that simulates downwards movement with gravity.
static 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(primitiveId: Int)` Add a haptic primitive to the end of the current composition.
VibrationEffect.Composition	`addPrimitive(primitiveId: Int, scale: Float)` Add a haptic primitive to the end of the current composition.
VibrationEffect.Composition	`addPrimitive(primitiveId: Int, scale: Float, delay: Int)` Add a haptic primitive to the end of the current composition.
VibrationEffect	`compose()` Compose all of the added primitives together into a single `VibrationEffect`.

Constants

PRIMITIVE_CLICK

Added in API level 30

static val PRIMITIVE_CLICK: Int

This effect should produce a sharp, crisp click sensation.

Value: 1

PRIMITIVE_LOW_TICK

Added in API level 31

static val PRIMITIVE_LOW_TICK: Int

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

Value: 8

PRIMITIVE_QUICK_FALL

Added in API level 30

static val PRIMITIVE_QUICK_FALL: Int

A haptic effect that simulates quick downwards movement with gravity.

Value: 6

PRIMITIVE_QUICK_RISE

Added in API level 30

static val PRIMITIVE_QUICK_RISE: Int

A haptic effect that simulates quick upward movement against gravity.

Value: 4

PRIMITIVE_SLOW_RISE

Added in API level 30

static val PRIMITIVE_SLOW_RISE: Int

A haptic effect that simulates slow upward movement against gravity.

Value: 5

PRIMITIVE_SPIN

Added in API level 31

static val PRIMITIVE_SPIN: Int

A haptic effect that simulates spinning momentum.

Value: 3

PRIMITIVE_THUD

Added in API level 31

static val PRIMITIVE_THUD: Int

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

Value: 2

PRIMITIVE_TICK

Added in API level 30

static val PRIMITIVE_TICK: Int

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

Value: 7

Public methods

addPrimitive

Added in API level 30

fun addPrimitive(primitiveId: Int): VibrationEffect.Composition

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 android.os.VibrationEffect.Composition#PRIMITIVE_CLICK, android.os.VibrationEffect.Composition#PRIMITIVE_THUD, android.os.VibrationEffect.Composition#PRIMITIVE_SPIN, android.os.VibrationEffect.Composition#PRIMITIVE_QUICK_RISE, android.os.VibrationEffect.Composition#PRIMITIVE_SLOW_RISE, android.os.VibrationEffect.Composition#PRIMITIVE_QUICK_FALL, android.os.VibrationEffect.Composition#PRIMITIVE_TICK, or android.os.VibrationEffect.Composition#PRIMITIVE_LOW_TICK

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

addPrimitive

Added in API level 30

fun addPrimitive(
    primitiveId: Int, 
    scale: Float
): VibrationEffect.Composition

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

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

Parameters

scale Float: The scale to apply to the intensity of the primitive. Value is between 0f and 1f inclusive

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

addPrimitive

Added in API level 30

fun addPrimitive(
    primitiveId: Int, 
    scale: Float, 
    delay: Int
): VibrationEffect.Composition

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

Parameters
`primitiveId`	Int: The primitive to add Value is `android.os.VibrationEffect.Composition#PRIMITIVE_CLICK`, `android.os.VibrationEffect.Composition#PRIMITIVE_THUD`, `android.os.VibrationEffect.Composition#PRIMITIVE_SPIN`, `android.os.VibrationEffect.Composition#PRIMITIVE_QUICK_RISE`, `android.os.VibrationEffect.Composition#PRIMITIVE_SLOW_RISE`, `android.os.VibrationEffect.Composition#PRIMITIVE_QUICK_FALL`, `android.os.VibrationEffect.Composition#PRIMITIVE_TICK`, or `android.os.VibrationEffect.Composition#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

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

compose

Added in API level 30

fun compose(): VibrationEffect

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.

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