PowerManager
extends Objectjava.lang.Object | |
↳ | android.os.PowerManager |
Class Overview
This class gives you control of the power state of the device.
这个类会让你拥有此设备的电源状态控制权
Device battery life will be significantly affected by the use of this API.
用户使用这个API会对设备电源的周期会受到很显著的影响
Do not acquire WakeLocks(唤醒锁) unless you really need them, use the minimum levels possible, and be sure to release it as soon as you can.
You can obtain an instance of this class by calling Context.getSystemService()
.
The primary API you'll use is newWakeLock()
. This will create a PowerManager.WakeLock
object. You can then use methods on this object to control the power state of the device. In practice it's quite simple:
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();
The following flags are defined, with varying effects on system power. These flags are mutually exclusive - you may only specify one of them.
Flag Value | CPU | Screen | Keyboard |
---|---|---|---|
PARTIAL_WAKE_LOCK | On* | Off | Off |
SCREEN_DIM_WAKE_LOCK | On | Dim | Off |
SCREEN_BRIGHT_WAKE_LOCK | On | Bright | Off |
FULL_WAKE_LOCK | On | Bright | Bright |
*If you hold a partial wakelock, the CPU will continue to run, irrespective of any timers and even after the user presses the power button. In all other wakelocks, the CPU will run, but the user can still put the device to sleep using the power button.
In addition, you can add two more flags, which affect behavior of the screen only. These flags have no effect when combined with a PARTIAL_WAKE_LOCK
.
Flag Value | Description |
---|---|
ACQUIRE_CAUSES_WAKEUP | 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. |
ON_AFTER_RELEASE | 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. |
Summary
Nested Classes | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
class | PowerManager.WakeLock | Class lets you say that you need to have the device on. |
Constants | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
int | ACQUIRE_CAUSES_WAKEUP | Normally wake locks don't actually wake the device, they just cause it to remain on once it's already on. | |||||||||
int | FULL_WAKE_LOCK | Wake lock that ensures that the screen and keyboard are on at full brightness. | |||||||||
int | ON_AFTER_RELEASE | When this wake lock is released, poke the user activity timer so the screen stays on for a little longer. | |||||||||
int | PARTIAL_WAKE_LOCK | Wake lock that ensures that the CPU is running. | |||||||||
int | SCREEN_BRIGHT_WAKE_LOCK | Wake lock that ensures that the screen is on at full brightness; the keyboard backlight will be allowed to go off. | |||||||||
int | SCREEN_DIM_WAKE_LOCK | Wake lock that ensures that the screen is on (but may be dimmed); the keyboard backlight will be allowed to go off. |
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
void | goToSleep(long time)
Force the device to go to sleep.
| ||||||||||
boolean | isScreenOn()
Returns whether the screen is currently on.
| ||||||||||
PowerManager.WakeLock | newWakeLock(int flags, String tag)
Get a wake lock at the level of the flags parameter.
| ||||||||||
void | reboot(String reason)
Reboot the device.
| ||||||||||
void | userActivity(long when, boolean noChangeLights)
User activity happened.
|
[Expand]
Inherited Methods
| |||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
From class java.lang.Object
|
Constants
public static final int ACQUIRE_CAUSES_WAKEUP
Normally wake locks don't actually wake the device, they just cause it to remain on once it's already on. Think of the video player app as the normal behavior. Notifications that pop up and want the device to be on are the exception; use this flag to be like them.
Does not work with PARTIAL_WAKE_LOCKs.
public static final int FULL_WAKE_LOCK
Wake lock that ensures that the screen and keyboard are on at full brightness.
public static final int ON_AFTER_RELEASE
When this wake lock is released, poke the user activity timer so the screen stays on for a little longer.
Will not turn the screen on if it is not already on. See ACQUIRE_CAUSES_WAKEUP
if you want that.
Does not work with PARTIAL_WAKE_LOCKs.
public static final int PARTIAL_WAKE_LOCK
Wake lock that ensures that the CPU is running. The screen might not be on.
public static final int SCREEN_BRIGHT_WAKE_LOCK
Wake lock that ensures that the screen is on at full brightness; the keyboard backlight will be allowed to go off.
public static final int SCREEN_DIM_WAKE_LOCK
Wake lock that ensures that the screen is on (but may be dimmed); the keyboard backlight will be allowed to go off.
Public Methods
public void goToSleep (long time)
Force the device to go to sleep. Overrides all the wake locks that are held.
Parameters
time | is used to order this correctly with the wake lock calls. The time should be in theSystemClock.uptimeMillis() time base. |
---|
public boolean isScreenOn ()
Returns whether the screen is currently on. The screen could be bright or dim.
PowerManager pm = (PowerManager) getSystemService(Context.POWER_SERVICE); boolean isScreenOn = pm.isScreenOn();
Returns
- whether the screen is on (bright or dim).
public PowerManager.WakeLock newWakeLock (int flags, String tag)
Get a wake lock at the level of the flags parameter. Call acquire()
on the object to acquire the wake lock, and release()
when you are done.
PowerManager pm = (PowerManager)mContext.getSystemService( Context.POWER_SERVICE); PowerManager.WakeLock wl = pm.newWakeLock( PowerManager.SCREEN_DIM_WAKE_LOCK | PowerManager.ON_AFTER_RELEASE, TAG); wl.acquire(); // ... wl.release();
Parameters
flags | Combination of flag values defining the requested behavior of the WakeLock. |
---|---|
tag | Your class name (or other tag) for debugging purposes. |
public void reboot (String reason)
Reboot the device. Will not return if the reboot is successful. Requires the REBOOT
permission.
Parameters
reason | code to pass to the kernel (e.g., "recovery") to request special boot modes, or null. |
---|
public void userActivity (long when, boolean noChangeLights)
User activity happened.
Turns the device from whatever state it's in to full on, and resets the auto-off timer.
Parameters
when | is used to order this correctly with the wake lock calls. This time should be in theSystemClock.uptimeMillis() time base. |
---|---|
noChangeLights | should be true if you don't want the lights to turn on because of this event. This is set when the power key goes down. We want the device to stay on while the button is down, but we're about to turn off. Otherwise the lights flash on and then off and it looks weird. |