VibrationEffect
public
abstract
class
VibrationEffect
extends Object
implements
Parcelable
java.lang.Object | |
↳ | android.os.VibrationEffect |
A VibrationEffect describes a haptic effect to be performed by a Vibrator
.
These effects may be any number of things, from single shot vibrations to complex waveforms.
Summary
Nested classes | |
---|---|
class |
VibrationEffect.BasicEnvelopeBuilder
A builder for waveform effects defined by their envelope, designed to provide a consistent haptic perception across devices with varying capabilities. |
class |
VibrationEffect.Composition
A composition of haptic elements that are combined to be playable as a single
|
class |
VibrationEffect.WaveformEnvelopeBuilder
A builder for waveform effects described by its envelope. |
Constants | |
---|---|
int |
DEFAULT_AMPLITUDE
The default vibration strength of the device. |
int |
EFFECT_CLICK
A click effect. |
int |
EFFECT_DOUBLE_CLICK
A double click effect. |
int |
EFFECT_HEAVY_CLICK
A heavy click effect. |
int |
EFFECT_TICK
A tick effect. |
Inherited constants |
---|
Fields | |
---|---|
public
static
final
Creator<VibrationEffect> |
CREATOR
|
Public methods | |
---|---|
static
VibrationEffect
|
createOneShot(long milliseconds, int amplitude)
Create a one shot vibration. |
static
VibrationEffect
|
createPredefined(int effectId)
Create a predefined vibration effect. |
static
VibrationEffect
|
createRepeatingEffect(VibrationEffect preamble, VibrationEffect repeatingEffect)
Creates a new |
static
VibrationEffect
|
createRepeatingEffect(VibrationEffect effect)
Creates a new |
static
VibrationEffect
|
createWaveform(long[] timings, int[] amplitudes, int repeat)
Create a waveform vibration. |
static
VibrationEffect
|
createWaveform(long[] timings, int repeat)
Create a waveform vibration, using only off/on transitions at the provided time intervals, and potentially repeating. |
int
|
describeContents()
Describe the kinds of special objects contained in this Parcelable instance's marshaled representation. |
static
VibrationEffect.Composition
|
startComposition()
Start composing a haptic effect. |
Inherited methods | |
---|---|
Constants
DEFAULT_AMPLITUDE
public static final int DEFAULT_AMPLITUDE
The default vibration strength of the device.
Constant Value: -1 (0xffffffff)
EFFECT_CLICK
public static final int EFFECT_CLICK
A click effect. Use this effect as a baseline, as it's the most common type of click effect.
Constant Value: 0 (0x00000000)
EFFECT_DOUBLE_CLICK
public static final int EFFECT_DOUBLE_CLICK
A double click effect.
Constant Value: 1 (0x00000001)
EFFECT_HEAVY_CLICK
public static final int EFFECT_HEAVY_CLICK
A heavy click effect. This effect is stronger than EFFECT_CLICK
.
Constant Value: 5 (0x00000005)
EFFECT_TICK
public static final int EFFECT_TICK
A tick effect. This effect is less strong compared to EFFECT_CLICK
.
Constant Value: 2 (0x00000002)
Fields
Public methods
createOneShot
public static VibrationEffect createOneShot (long milliseconds, int amplitude)
Create a one shot vibration.
One shot vibrations will vibrate constantly for the specified period of time at the specified amplitude, and then stop.
Parameters | |
---|---|
milliseconds |
long : The number of milliseconds to vibrate. This must be a positive number. |
amplitude |
int : The strength of the vibration. This must be a value between 1 and 255, or
DEFAULT_AMPLITUDE . |
Returns | |
---|---|
VibrationEffect |
The desired effect. |
createPredefined
public static VibrationEffect createPredefined (int effectId)
Create a predefined vibration effect.
Predefined effects are a set of common vibration effects that should be identical, regardless of the app they come from, in order to provide a cohesive experience for users across the entire device. They also may be custom tailored to the device hardware in order to provide a better experience than you could otherwise build using the generic building blocks.
This will fallback to a generic pattern if one exists and there does not exist a hardware-specific implementation of the effect.
Parameters | |
---|---|
effectId |
int : The ID of the effect to perform:
EFFECT_CLICK , EFFECT_DOUBLE_CLICK , EFFECT_TICK
Value is EFFECT_TICK , EFFECT_CLICK , EFFECT_HEAVY_CLICK , or EFFECT_DOUBLE_CLICK |
Returns | |
---|---|
VibrationEffect |
The desired effect.
This value cannot be null . |
createRepeatingEffect
public static VibrationEffect createRepeatingEffect (VibrationEffect preamble, VibrationEffect repeatingEffect)
Creates a new VibrationEffect
by merging the preamble and repeating vibration effect.
Neither input vibration may already be repeating. An IllegalArgumentException
will
be thrown if either input vibration is set to repeat indefinitely.
Parameters | |
---|---|
preamble |
VibrationEffect : The starting vibration effect, which must be finite.
This value cannot be null . |
repeatingEffect |
VibrationEffect : The vibration effect to be repeated indefinitely after the preamble.
This value cannot be null . |
Returns | |
---|---|
VibrationEffect |
A VibrationEffect that plays the preamble once followed by the
`repeatingEffect` indefinitely.
This value cannot be null . |
Throws | |
---|---|
IllegalArgumentException |
if either preamble or repeatingEffect is already a repeating vibration. |
createRepeatingEffect
public static VibrationEffect createRepeatingEffect (VibrationEffect effect)
Creates a new VibrationEffect
that repeats the given effect indefinitely.
The input vibration must not be a repeating vibration. If it is, an
IllegalArgumentException
will be thrown.
Parameters | |
---|---|
effect |
VibrationEffect : The VibrationEffect that will be repeated.
This value cannot be null . |
Returns | |
---|---|
VibrationEffect |
A VibrationEffect that repeats the effect indefinitely.
This value cannot be null . |
Throws | |
---|---|
IllegalArgumentException |
if the effect is already a repeating vibration. |
createWaveform
public static VibrationEffect createWaveform (long[] timings, int[] amplitudes, int repeat)
Create a waveform vibration.
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.
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 Vibrator.cancel()
.
Parameters | |
---|---|
timings |
long : The timing values, in milliseconds, of the timing / amplitude pairs. Timing
values of 0 will cause the pair to be ignored. |
amplitudes |
int : The amplitude values of the timing / amplitude pairs. Amplitude values
must be between 0 and 255, or equal to DEFAULT_AMPLITUDE . An
amplitude value of 0 implies the motor is off. |
repeat |
int : The index into the timings array at which to repeat, or -1 if you don't
want to repeat indefinitely. |
Returns | |
---|---|
VibrationEffect |
The desired effect. |
createWaveform
public static VibrationEffect createWaveform (long[] timings, int repeat)
Create a waveform vibration, using only off/on transitions at the provided time intervals, and potentially repeating.
In effect, the timings array represents the number of milliseconds before 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.
This method is equivalent to calling createWaveform(long[], int[], int)
with
corresponding amplitude values alternating between 0 and DEFAULT_AMPLITUDE
,
beginning with 0.
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 Vibrator.cancel()
.
Parameters | |
---|---|
timings |
long : 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). |
repeat |
int : The index into the timings array at which to repeat, or -1 if you don't
want to repeat indefinitely. |
Returns | |
---|---|
VibrationEffect |
The desired effect. |
describeContents
public int describeContents ()
Describe the kinds of special objects contained in this Parcelable
instance's marshaled representation. For example, if the object will
include a file descriptor in the output of writeToParcel(android.os.Parcel, int)
,
the return value of this method must include the
CONTENTS_FILE_DESCRIPTOR
bit.
Returns | |
---|---|
int |
a bitmask indicating the set of special object types marshaled
by this Parcelable object instance.
Value is either 0 or CONTENTS_FILE_DESCRIPTOR |
startComposition
public static VibrationEffect.Composition startComposition ()
Start composing a haptic effect.
Returns | |
---|---|
VibrationEffect.Composition |
This value cannot be null . |
See also: