Vibrator
abstract class Vibrator
| kotlin.Any | |
| ↳ | android.os.Vibrator |
Class that operates the vibrator on the device.
If your process exits, any vibration you started will stop.
Summary
| Constants | |
|---|---|
| static Int |
Vibration effect support: unsupported |
| static Int |
Vibration effect support: unknown |
| static Int |
Vibration effect support: supported |
| Public methods | |
|---|---|
| Int |
areAllEffectsSupported(vararg effectIds: Int)Query whether the vibrator supports all the given effects. |
| Boolean |
areAllPrimitivesSupported(vararg primitiveIds: Int)Query whether the vibrator supports all of the given primitives. |
| open IntArray |
areEffectsSupported(vararg effectIds: Int)Query whether the vibrator natively supports the given effects. |
| open Boolean |
Checks whether the vibrator supports the creation of envelope effects. |
| open BooleanArray |
arePrimitivesSupported(vararg primitiveIds: Int)Query whether the vibrator supports the given primitives. |
| abstract Unit |
cancel()Turn the vibrator off. |
| open VibratorEnvelopeEffectInfo |
Retrieves the vibrator's capabilities and limitations for envelope effects. |
| open VibratorFrequencyProfile? |
Gets the profile that describes the vibrator output across the supported frequency range. |
| open Int |
getId()Return the ID of this vibrator. |
| open IntArray |
getPrimitiveDurations(vararg primitiveIds: Int)Query the estimated durations of the given primitives. |
| open Float |
Gets the Q factor of the vibrator. |
| open Float |
Gets the resonant frequency of the vibrator, if applicable. |
| abstract Boolean |
Check whether the vibrator has amplitude control. |
| abstract Boolean |
Check whether the hardware has a vibrator. |
| open Unit |
vibrate(vibe: VibrationEffect!)Vibrate with a given effect. |
| open Unit |
vibrate(vibe: VibrationEffect!, attributes: AudioAttributes!)Vibrate with a given effect. |
| open Unit |
vibrate(vibe: VibrationEffect, attributes: VibrationAttributes)Vibrate with a given effect. |
| open Unit |
Vibrate constantly for the specified period of time. |
| open Unit |
vibrate(milliseconds: Long, attributes: AudioAttributes!)Vibrate constantly for the specified period of time. |
| open Unit |
Vibrate with a given pattern. |
| open Unit |
vibrate(pattern: LongArray!, repeat: Int, attributes: AudioAttributes!)Vibrate with a given pattern. |
Constants
VIBRATION_EFFECT_SUPPORT_NO
static val VIBRATION_EFFECT_SUPPORT_NO: Int
Vibration effect support: unsupported
This effect is not natively supported by the underlying hardware, although the system may still play a fallback vibration.
Value: 2VIBRATION_EFFECT_SUPPORT_UNKNOWN
static val VIBRATION_EFFECT_SUPPORT_UNKNOWN: Int
Vibration effect support: unknown
The hardware doesn't report its supported effects, so we can't determine whether the effect is supported or not.
Value: 0VIBRATION_EFFECT_SUPPORT_YES
static val VIBRATION_EFFECT_SUPPORT_YES: Int
Vibration effect support: supported
This effect is supported by the underlying hardware.
Value: 1Public methods
areAllEffectsSupported
fun areAllEffectsSupported(vararg effectIds: Int): Int
Query whether the vibrator supports all the given effects. If no argument is provided this method will always return VIBRATION_EFFECT_SUPPORT_YES.
If an effect is not supported, the system may still automatically fall back to a simpler vibration instead, which is not optimised for the specific device, however vibration isn't guaranteed in this case.
If the result is VIBRATION_EFFECT_SUPPORT_YES, all effects in the query are supported by the hardware.
If the result is VIBRATION_EFFECT_SUPPORT_NO, at least one of the effects in the query is not supported, and using them may fall back to an un-optimized vibration or no vibration.
If the result is VIBRATION_EFFECT_SUPPORT_UNKNOWN, the system doesn't know whether all the effects are supported. It may support any or all of the queried effects, but there's no way to programmatically know whether a #vibrate call will successfully cause a vibration. It's guaranteed, however, that none of the queried effects are definitively unsupported by the hardware.
Use areEffectsSupported(int...) to get individual results for each effect.
| Parameters | |
|---|---|
effectIds |
Int: Which effects to query for. This value cannot be null. Value is android.os.VibrationEffect#EFFECT_TICK, android.os.VibrationEffect#EFFECT_CLICK, android.os.VibrationEffect#EFFECT_HEAVY_CLICK, or android.os.VibrationEffect#EFFECT_DOUBLE_CLICK |
| Return | |
|---|---|
Int |
Whether all specified effects are natively supported by the device. Empty query defaults to VIBRATION_EFFECT_SUPPORT_YES. Value is android.os.Vibrator#VIBRATION_EFFECT_SUPPORT_UNKNOWN, android.os.Vibrator#VIBRATION_EFFECT_SUPPORT_YES, or android.os.Vibrator#VIBRATION_EFFECT_SUPPORT_NO |
areAllPrimitivesSupported
fun areAllPrimitivesSupported(vararg primitiveIds: Int): Boolean
Query whether the vibrator supports all of the given primitives. If no argument is provided this method will always return true.
If a primitive is not supported by the device, then no vibration will occur if it is played.
Use arePrimitivesSupported(int...) to get individual results for each primitive.
| Return | |
|---|---|
Boolean |
Whether all specified primitives are supported. Empty query defaults to true. |
areEffectsSupported
open fun areEffectsSupported(vararg effectIds: Int): IntArray
Query whether the vibrator natively supports the given effects.
If an effect is not supported, the system may still automatically fall back to playing 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 will contain VIBRATION_EFFECT_SUPPORT_YES if the effect at that same index in the querying array is supported, VIBRATION_EFFECT_SUPPORT_NO if it isn't supported, or VIBRATION_EFFECT_SUPPORT_UNKNOWN if the system can't determine whether it's supported or not, as some hardware doesn't report its effect capabilities.
Use areAllEffectsSupported(int...) to get a single combined result, or for convenience when querying exactly one effect.
| Parameters | |
|---|---|
effectIds |
Int: Which effects to query for. This value cannot be null. Value is android.os.VibrationEffect#EFFECT_TICK, android.os.VibrationEffect#EFFECT_CLICK, android.os.VibrationEffect#EFFECT_HEAVY_CLICK, or android.os.VibrationEffect#EFFECT_DOUBLE_CLICK |
| Return | |
|---|---|
IntArray |
An array containing the systems current knowledge about whether the given effects are natively supported by the device, or not. This value cannot be null. Value is android.os.Vibrator#VIBRATION_EFFECT_SUPPORT_UNKNOWN, android.os.Vibrator#VIBRATION_EFFECT_SUPPORT_YES, or android.os.Vibrator#VIBRATION_EFFECT_SUPPORT_NO |
areEnvelopeEffectsSupported
open fun areEnvelopeEffectsSupported(): Boolean
Checks whether the vibrator supports the creation of envelope effects. Envelope effects are defined by a series of frequency-amplitude pairs with specified transition times, allowing the creation of more complex vibration patterns.
| Return | |
|---|---|
Boolean |
True if the hardware supports creating envelope effects, false otherwise. |
arePrimitivesSupported
open fun arePrimitivesSupported(vararg primitiveIds: Int): BooleanArray
Query whether the vibrator supports the given primitives. The returned array will be the same length as the query array and the value at a given index will contain whether the effect at that same index in the querying array is supported or not.
If a primitive is not supported by the device, then no vibration will occur if it is played.
Use areAllPrimitivesSupported(int...) to get a single combined result, or for convenience when querying exactly one primitive.
| Return | |
|---|---|
BooleanArray |
Whether the primitives are supported. This value cannot be null. |
cancel
abstract fun cancel(): Unit
Turn the vibrator off.
Requires android.Manifest.permission#VIBRATE
getEnvelopeEffectInfo
open fun getEnvelopeEffectInfo(): VibratorEnvelopeEffectInfo
Retrieves the vibrator's capabilities and limitations for envelope effects.
These parameters can be used with VibrationEffect.WaveformEnvelopeBuilder to create custom envelope effects.
| Return | |
|---|---|
VibratorEnvelopeEffectInfo |
The vibrator's envelope effect information, or null if not supported. If this vibrator is a composite of multiple physical devices then this will return a profile supported in all devices, or null if the intersection is empty or not available. |
getFrequencyProfile
open fun getFrequencyProfile(): VibratorFrequencyProfile?
Gets the profile that describes the vibrator output across the supported frequency range.
The profile describes the output acceleration that the device can reach when it vibrates at different frequencies.
| Return | |
|---|---|
VibratorFrequencyProfile? |
The frequency profile for this vibrator, or null if the vibrator does not have frequency control. If this vibrator is a composite of multiple physical devices then this will return a profile supported in all devices, or null if the intersection is empty or not available. |
getId
open fun getId(): Int
Return the ID of this vibrator.
| Return | |
|---|---|
Int |
A non-negative integer representing the id of the vibrator controlled by this service, or -1 this service is not attached to any physical vibrator. |
getPrimitiveDurations
open fun getPrimitiveDurations(vararg primitiveIds: Int): IntArray
Query the estimated durations of the given primitives.
The returned array will be the same length as the query array and the value at a given index will contain the duration in milliseconds of the effect at the same index in the querying array.
The duration will be positive for primitives that are supported and zero for the unsupported ones, in correspondence with arePrimitivesSupported(int...).
| Return | |
|---|---|
IntArray |
The duration of each primitive, with zeroes for primitives that are not supported. This value cannot be null. |
getQFactor
open fun getQFactor(): Float
Gets the Q factor of the vibrator.
| Return | |
|---|---|
Float |
the Q factor of the vibrator, or NaN if it's unknown, not applicable, or if this vibrator is a composite of multiple physical devices with different Q factors. |
getResonantFrequency
open fun getResonantFrequency(): Float
Gets the resonant frequency of the vibrator, if applicable.
| Return | |
|---|---|
Float |
the resonant frequency of the vibrator, or NaN if it's unknown, not applicable, or if this vibrator is a composite of multiple physical devices with different frequencies. |
hasAmplitudeControl
abstract fun hasAmplitudeControl(): Boolean
Check whether the vibrator has amplitude control.
| Return | |
|---|---|
Boolean |
True if the hardware can control the amplitude of the vibrations, otherwise false. |
hasVibrator
abstract fun hasVibrator(): Boolean
Check whether the hardware has a vibrator.
| Return | |
|---|---|
Boolean |
True if the hardware has a vibrator, else false. |
vibrate
open fun vibrate(vibe: VibrationEffect!): Unit
Vibrate with a given effect.
The app should be in the foreground for the vibration to happen.
Requires
android.Manifest.permission#VIBRATE
| Parameters | |
|---|---|
vibe |
VibrationEffect!: VibrationEffect describing the vibration to be performed. |
vibrate
open funvibrate(
vibe: VibrationEffect!,
attributes: AudioAttributes!
): Unit
Deprecated: Use vibrate(android.os.VibrationEffect,android.os.VibrationAttributes) instead.
Vibrate with a given effect.
The app should be in the foreground for the vibration to happen. Background apps should specify a ringtone, notification or alarm usage in order to vibrate.
Requires
android.Manifest.permission#VIBRATE
| Parameters | |
|---|---|
vibe |
VibrationEffect!: VibrationEffect describing the vibration to be performed. |
attributes |
AudioAttributes!: AudioAttributes corresponding to the vibration. For example, specify AudioAttributes.USAGE_ALARM for alarm vibrations or AudioAttributes.USAGE_NOTIFICATION_RINGTONE for vibrations associated with incoming calls. |
vibrate
open fun vibrate(
vibe: VibrationEffect,
attributes: VibrationAttributes
): Unit
Vibrate with a given effect.
The app should be in the foreground for the vibration to happen. Background apps should specify a ringtone, notification or alarm usage in order to vibrate.
Requires
android.Manifest.permission#VIBRATE
| Parameters | |
|---|---|
vibe |
VibrationEffect: VibrationEffect describing the vibration to be performed. This value cannot be null. |
attributes |
VibrationAttributes: VibrationAttributes corresponding to the vibration. For example, specify VibrationAttributes.USAGE_ALARM for alarm vibrations or VibrationAttributes.USAGE_RINGTONE for vibrations associated with incoming calls. This value cannot be null. |
vibrate
open funvibrate(milliseconds: Long): Unit
Deprecated: Use vibrate(android.os.VibrationEffect) instead.
Vibrate constantly for the specified period of time.
The app should be in the foreground for the vibration to happen.
Requires
android.Manifest.permission#VIBRATE
| Parameters | |
|---|---|
milliseconds |
Long: The number of milliseconds to vibrate. |
vibrate
open funvibrate(
milliseconds: Long,
attributes: AudioAttributes!
): Unit
Deprecated: Use vibrate(android.os.VibrationEffect,android.os.VibrationAttributes) instead.
Vibrate constantly for the specified period of time.
The app should be in the foreground for the vibration to happen. Background apps should specify a ringtone, notification or alarm usage in order to vibrate.
Requires
android.Manifest.permission#VIBRATE
| Parameters | |
|---|---|
milliseconds |
Long: The number of milliseconds to vibrate. |
attributes |
AudioAttributes!: AudioAttributes corresponding to the vibration. For example, specify AudioAttributes.USAGE_ALARM for alarm vibrations or AudioAttributes.USAGE_NOTIFICATION_RINGTONE for vibrations associated with incoming calls. |
vibrate
open funvibrate(
pattern: LongArray!,
repeat: Int
): Unit
Deprecated: Use vibrate(android.os.VibrationEffect) instead.
Vibrate with a given pattern.
Pass in an array of ints that are the durations for which to turn on or off the vibrator in milliseconds. The first value indicates the number of milliseconds to wait before turning the vibrator on. The next value indicates the number of milliseconds for which to keep the vibrator on before turning it off. Subsequent values alternate between durations in milliseconds to turn the vibrator off or to turn the vibrator on.
To cause the pattern to repeat, pass the index into the pattern array at which to start the repeat, or -1 to disable repeating.
The app should be in the foreground for the vibration to happen.
Requires
android.Manifest.permission#VIBRATE
| Parameters | |
|---|---|
pattern |
LongArray!: an array of longs of times for which to turn the vibrator on or off. |
repeat |
Int: the index into pattern at which to repeat, or -1 if you don't want to repeat. |
vibrate
open funvibrate(
pattern: LongArray!,
repeat: Int,
attributes: AudioAttributes!
): Unit
Deprecated: Use vibrate(android.os.VibrationEffect,android.os.VibrationAttributes) instead.
Vibrate with a given pattern.
Pass in an array of ints that are the durations for which to turn on or off the vibrator in milliseconds. The first value indicates the number of milliseconds to wait before turning the vibrator on. The next value indicates the number of milliseconds for which to keep the vibrator on before turning it off. Subsequent values alternate between durations in milliseconds to turn the vibrator off or to turn the vibrator on.
To cause the pattern to repeat, pass the index into the pattern array at which to start the repeat, or -1 to disable repeating.
The app should be in the foreground for the vibration to happen. Background apps should specify a ringtone, notification or alarm usage in order to vibrate.
Requires
android.Manifest.permission#VIBRATE
| Parameters | |
|---|---|
pattern |
LongArray!: an array of longs of times for which to turn the vibrator on or off. |
repeat |
Int: the index into pattern at which to repeat, or -1 if you don't want to repeat. |
attributes |
AudioAttributes!: AudioAttributes corresponding to the vibration. For example, specify AudioAttributes.USAGE_ALARM for alarm vibrations or AudioAttributes.USAGE_NOTIFICATION_RINGTONE for vibrations associated with incoming calls. |