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

Commit 3fea8d10 authored by Andrew Solovay's avatar Andrew Solovay
Browse files

docs: Removing most of the intro to PowerManager API 

The intro text says PowerManager is discouraged, and almost
all the available wakelock options have long been deprecated.
Given that, I think it makes sense to remove most of that
intro and just point devs to FLAG_KEEP_SCREEN_ON instead.

Staged to:
go/dac-stage/reference/android/os/PowerManager

Test: make ds-docs
Bug: 145699347
Change-Id: I517366903f3d9743166d7edaddc08471af0803d9
parent 899f8301

core/java/android/os/PowerManager.java

+5 −64
Original line number Diff line number Diff line
@@ -44,70 +44,10 @@ import java.util.concurrent.Executor; 
 * <p>

 * <b>Device battery life will be significantly affected by the use of this API.</b>

 * Do not acquire {@link WakeLock}s unless you really need them, use the minimum levels

 * possible, and be sure to release them as soon as possible.

 * </p><p>

 * The primary API you'll use is {@link #newWakeLock(int, String) newWakeLock()}.

 * This will create a {@link PowerManager.WakeLock} object.  You can then use methods

 * on the wake lock object to control the power state of the device.

 * </p><p>

 * In practice it's quite simple:

 * {@samplecode

 * PowerManager pm = (PowerManager) getSystemService(Context.POWER_SERVICE);

 * PowerManager.WakeLock wl = pm.newWakeLock(PowerManager.SCREEN_DIM_WAKE_LOCK, "My Tag");

 * wl.acquire();

 *   ..screen will stay on during this section..

 * wl.release();

 * }

 * </p><p>

 * The following wake lock levels are defined, with varying effects on system power.

 * <i>These levels are mutually exclusive - you may only specify one of them.</i>

 *

 * <table>

 *     <tr><th>Flag Value</th>

 *     <th>CPU</th> <th>Screen</th> <th>Keyboard</th></tr>

 *

 *     <tr><td>{@link #PARTIAL_WAKE_LOCK}</td>

 *         <td>On*</td> <td>Off</td> <td>Off</td>

 *     </tr>

 *

 *     <tr><td>{@link #SCREEN_DIM_WAKE_LOCK}</td>

 *         <td>On</td> <td>Dim</td> <td>Off</td>

 *     </tr>

 *

 *     <tr><td>{@link #SCREEN_BRIGHT_WAKE_LOCK}</td>

 *         <td>On</td> <td>Bright</td> <td>Off</td>

 *     </tr>

 * possible, and be sure to release them as soon as possible. In most cases,

 * you'll want to use

 * {@link android.view.WindowManager.LayoutParams#FLAG_KEEP_SCREEN_ON} instead.

 *

 *     <tr><td>{@link #FULL_WAKE_LOCK}</td>

 *         <td>On</td> <td>Bright</td> <td>Bright</td>

 *     </tr>

 * </table>

 * </p><p>

 * *<i>If you hold a partial wake lock, the CPU will continue to run, regardless of any

 * display timeouts or the state of the screen and even after the user presses the power button.

 * In all other wake locks, the CPU will run, but the user can still put the device to sleep

 * using the power button.</i>

 * </p><p>

 * In addition, you can add two more flags, which affect behavior of the screen only.

 * <i>These flags have no effect when combined with a {@link #PARTIAL_WAKE_LOCK}.</i></p>

 *

 * <table>

 *     <tr><th>Flag Value</th> <th>Description</th></tr>

 *

 *     <tr><td>{@link #ACQUIRE_CAUSES_WAKEUP}</td>

 *         <td>Normal wake locks don't actually turn on the illumination.  Instead, they cause

 *         the illumination to remain on once it turns on (e.g. from user activity).  This flag

 *         will force the screen and/or keyboard to turn on immediately, when the WakeLock is

 *         acquired.  A typical use would be for notifications which are important for the user to

 *         see immediately.</td>

 *     </tr>

 *

 *     <tr><td>{@link #ON_AFTER_RELEASE}</td>

 *         <td>If this flag is set, the user activity timer will be reset when the WakeLock is

 *         released, causing the illumination to remain on a bit longer.  This can be used to

 *         reduce flicker if you are cycling between wake lock conditions.</td>

 *     </tr>

 * </table>

 * <p>

 * Any application using a WakeLock must request the {@code android.permission.WAKE_LOCK}

 * permission in an {@code <uses-permission>} element of the application's manifest.
@@ -914,7 +854,8 @@ public final class PowerManager { 
     * {@link #FULL_WAKE_LOCK}, {@link #SCREEN_DIM_WAKE_LOCK}

     * and {@link #SCREEN_BRIGHT_WAKE_LOCK}.  Exactly one wake lock level must be

     * specified as part of the {@code levelAndFlags} parameter.

     * </p><p>

     * </p>

     * <p>

     * The wake lock flags are: {@link #ACQUIRE_CAUSES_WAKEUP}

     * and {@link #ON_AFTER_RELEASE}.  Multiple flags can be combined as part of the

     * {@code levelAndFlags} parameters.