| java.lang.Object | |
| ↳ | android.os.PowerManager |
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.
Do not acquire PowerManager.WakeLocks unless you really need them, use the minimum levels
possible, and be sure to release them as soon as possible.
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 the wake lock 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 wake lock levels are defined, with varying effects on system power. These levels 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 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.
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. |
Any application using a WakeLock must request the android.permission.WAKE_LOCK
permission in an <uses-permission> element of the application's manifest.
| Nested Classes | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| PowerManager.WakeLock | A wake lock is a mechanism to indicate that your application needs to have the device stay on. | ||||||||||
| Constants | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| int | ACQUIRE_CAUSES_WAKEUP | Wake lock flag: Turn the screen on when the wake lock is acquired. | |||||||||
| int | FULL_WAKE_LOCK |
This constant was deprecated
in API level 17.
Most applications should use
FLAG_KEEP_SCREEN_ON instead
of this type of wake lock, as it will be correctly managed by the platform
as the user moves between applications and doesn't require a special permission.
|
|||||||||
| int | ON_AFTER_RELEASE | Wake lock flag: 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 level: Ensures that the CPU is running; the screen and keyboard backlight will be allowed to go off. | |||||||||
| int | SCREEN_BRIGHT_WAKE_LOCK |
This constant was deprecated
in API level 13.
Most applications should use
FLAG_KEEP_SCREEN_ON instead
of this type of wake lock, as it will be correctly managed by the platform
as the user moves between applications and doesn't require a special permission.
|
|||||||||
| int | SCREEN_DIM_WAKE_LOCK |
This constant was deprecated
in API level 17.
Most applications should use
FLAG_KEEP_SCREEN_ON instead
of this type of wake lock, as it will be correctly managed by the platform
as the user moves between applications and doesn't require a special permission.
|
|||||||||
| Public Methods | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
Forces the device to go to sleep.
| |||||||||||
Returns whether the screen is currently on.
| |||||||||||
Creates a new wake lock with the specified level and flags.
| |||||||||||
Reboot the device.
| |||||||||||
Notifies the power manager that user activity happened.
| |||||||||||
Forces the device to wake up from sleep.
| |||||||||||
|
[Expand]
Inherited Methods | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
From class
java.lang.Object
| |||||||||||
Wake lock flag: Turn the screen on when the wake lock is acquired.
Normally wake locks don't actually wake the device, they just cause the screen to remain on once it's already on. Think of the video player application 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.
Cannot be used with PARTIAL_WAKE_LOCK.
This constant was deprecated
in API level 17.
Most applications should use
FLAG_KEEP_SCREEN_ON instead
of this type of wake lock, as it will be correctly managed by the platform
as the user moves between applications and doesn't require a special permission.
Wake lock level: Ensures that the screen and keyboard backlight are on at full brightness.
If the user presses the power button, then the FULL_WAKE_LOCK will be
implicitly released by the system, causing both the screen and the CPU to be turned off.
Contrast with PARTIAL_WAKE_LOCK.
Wake lock flag: 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.
Cannot be used with PARTIAL_WAKE_LOCK.
Wake lock level: Ensures that the CPU is running; the screen and keyboard backlight will be allowed to go off.
If the user presses the power button, then the screen will be turned off but the CPU will be kept on until all partial wake locks have been released.
This constant was deprecated
in API level 13.
Most applications should use
FLAG_KEEP_SCREEN_ON instead
of this type of wake lock, as it will be correctly managed by the platform
as the user moves between applications and doesn't require a special permission.
Wake lock level: Ensures that the screen is on at full brightness; the keyboard backlight will be allowed to go off.
If the user presses the power button, then the SCREEN_BRIGHT_WAKE_LOCK will be
implicitly released by the system, causing both the screen and the CPU to be turned off.
Contrast with PARTIAL_WAKE_LOCK.
This constant was deprecated
in API level 17.
Most applications should use
FLAG_KEEP_SCREEN_ON instead
of this type of wake lock, as it will be correctly managed by the platform
as the user moves between applications and doesn't require a special permission.
Wake lock level: Ensures that the screen is on (but may be dimmed); the keyboard backlight will be allowed to go off.
If the user presses the power button, then the SCREEN_DIM_WAKE_LOCK will be
implicitly released by the system, causing both the screen and the CPU to be turned off.
Contrast with PARTIAL_WAKE_LOCK.
Forces the device to go to sleep.
Overrides all the wake locks that are held. This is what happens when the power key is pressed to turn off the screen.
Requires the DEVICE_POWER permission.
| time | The time when the request to go to sleep was issued, in the
uptimeMillis() time base. This timestamp is used to correctly
order the go to sleep request with other power management functions. It should be set
to the timestamp of the input event that caused the request to go to sleep. |
|---|
Returns whether the screen is currently on.
Only indicates whether the screen is on. The screen could be either bright or dim.
PowerManager pm = (PowerManager) getSystemService(Context.POWER_SERVICE); boolean isScreenOn = pm.isScreenOn();
Creates a new wake lock with the specified level and flags.
The levelAndFlags parameter specifies a wake lock level and optional flags
combined using the logical OR operator.
The wake lock levels are: PARTIAL_WAKE_LOCK,
FULL_WAKE_LOCK, SCREEN_DIM_WAKE_LOCK
and SCREEN_BRIGHT_WAKE_LOCK. Exactly one wake lock level must be
specified as part of the levelAndFlags parameter.
The wake lock flags are: ACQUIRE_CAUSES_WAKEUP
and ON_AFTER_RELEASE. Multiple flags can be combined as part of the
levelAndFlags parameters.
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();
// ... do work...
wl.release();
Although a wake lock can be created without special permissions,
the WAKE_LOCK permission is
required to actually acquire or release the wake lock that is returned.
If using this to keep the screen on, you should strongly consider using
FLAG_KEEP_SCREEN_ON instead.
This window flag will be correctly managed by the platform
as the user moves between applications and doesn't require a special permission.
| levelAndFlags | Combination of wake lock level and flag values defining the requested behavior of the WakeLock. |
|---|---|
| tag | Your class name (or other tag) for debugging purposes. |
Reboot the device. Will not return if the reboot is successful.
Requires the REBOOT permission.
| reason | code to pass to the kernel (e.g., "recovery") to request special boot modes, or null. |
|---|
Notifies the power manager that user activity happened.
Resets the auto-off timer and brightens the screen if the device is not asleep. This is what happens normally when a key or the touch screen is pressed or when some other user activity occurs. This method does not wake up the device if it has been put to sleep.
Requires the DEVICE_POWER permission.
| when | The time of the user activity, in the uptimeMillis()
time base. This timestamp is used to correctly order the user activity request with
other power management functions. It should be set
to the timestamp of the input event that caused the user activity. |
|---|---|
| noChangeLights | If true, does not cause the keyboard backlight to turn on because of this event. This is set when the power key is pressed. We want the device to stay on while the button is down, but we're about to turn off the screen so we don't want the keyboard backlight to turn on again. Otherwise the lights flash on and then off and it looks weird. |
Forces the device to wake up from sleep.
If the device is currently asleep, wakes it up, otherwise does nothing. This is what happens when the power key is pressed to turn on the screen.
Requires the DEVICE_POWER permission.
| time | The time when the request to wake up was issued, in the
uptimeMillis() time base. This timestamp is used to correctly
order the wake up request with other power management functions. It should be set
to the timestamp of the input event that caused the request to wake up. |
|---|