Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit b15909f4 authored by Lais Andrade's avatar Lais Andrade
Browse files

Add documentation to Vibrator on foreground/background app behavior 

Add information to javadocs explaining that apps in background can only vibrate the device if the given AudioAttributes usage is one of notification, ringtone or alarm usages.

Fix: 146313440
Test: N/A
Change-Id: Iff24612ac76be6a77fbfa700ec59a2ca32b2b1b5
parent 33517174

core/java/android/os/Vibrator.java

+29 −0
Original line number Diff line number Diff line
@@ -228,6 +228,8 @@ public abstract class Vibrator { 
    /**

     * Vibrate constantly for the specified period of time.

     *

     * <p>The app should be in foreground for the vibration to happen.</p>

     *

     * @param milliseconds The number of milliseconds to vibrate.

     * @deprecated Use {@link #vibrate(VibrationEffect)} instead.

     */
@@ -240,6 +242,9 @@ public abstract class Vibrator { 
    /**

     * Vibrate constantly for the specified period of time.

     *

     * <p>The app should be in foreground for the vibration to happen. Background apps should

     * specify a ringtone, notification or alarm usage in order to vibrate.</p>

     *

     * @param milliseconds The number of milliseconds to vibrate.

     * @param attributes   {@link AudioAttributes} corresponding to the vibration. For example,

     *                     specify {@link AudioAttributes#USAGE_ALARM} for alarm vibrations or
@@ -274,6 +279,8 @@ public abstract class Vibrator { 
     * to start the repeat, or -1 to disable repeating.

     * </p>

     *

     * <p>The app should be in foreground for the vibration to happen.</p>

     *

     * @param pattern an array of longs of times for which to turn the vibrator on or off.

     * @param repeat  the index into pattern at which to repeat, or -1 if

     *                you don't want to repeat.
@@ -299,6 +306,9 @@ public abstract class Vibrator { 
     * to start the repeat, or -1 to disable repeating.

     * </p>

     *

     * <p>The app should be in foreground for the vibration to happen. Background apps should

     * specify a ringtone, notification or alarm usage in order to vibrate.</p>

     *

     * @param pattern    an array of longs of times for which to turn the vibrator on or off.

     * @param repeat     the index into pattern at which to repeat, or -1 if

     *                   you don't want to repeat.
@@ -326,11 +336,30 @@ public abstract class Vibrator { 
        }

    }



    /**

     * Vibrate with a given effect.

     *

     * <p>The app should be in foreground for the vibration to happen.</p>

     *

     * @param vibe {@link VibrationEffect} describing the vibration to be performed.

     */

    @RequiresPermission(android.Manifest.permission.VIBRATE)

    public void vibrate(VibrationEffect vibe) {

        vibrate(vibe, null);

    }



    /**

     * Vibrate with a given effect.

     *

     * <p>The app should be in foreground for the vibration to happen. Background apps should

     * specify a ringtone, notification or alarm usage in order to vibrate.</p>

     *

     * @param vibe       {@link VibrationEffect} describing the vibration to be performed.

     * @param attributes {@link AudioAttributes} corresponding to the vibration. For example,

     *                   specify {@link AudioAttributes#USAGE_ALARM} for alarm vibrations or

     *                   {@link AudioAttributes#USAGE_NOTIFICATION_RINGTONE} for

     *                   vibrations associated with incoming calls.

     */

    @RequiresPermission(android.Manifest.permission.VIBRATE)

    public void vibrate(VibrationEffect vibe, AudioAttributes attributes) {

        vibrate(Process.myUid(), mPackageName, vibe, null, attributes);