mozilla
Your Search Results

    Navigator.requestWakeLock()

    Non-standard
    This feature is not on a current W3C standards track, but it is supported on the Firefox OS platform. Although implementations may change in the future and it is not supported widely across browsers, it is suitable for use in code dedicated to Firefox OS apps.

    Summary

    This method is used to request a wake lock on any resource of the device. This means that you can prevent that resource from becoming unavailable as long as your app holds a lock for that resource. For example, a voice recording app can obtain a lock to keep the screen on during recording so that it can give prover visual feedback to the user that recording is progressing.

    Returns a MozWakeLock object you can use to keep track of or release the lock.

    Syntax

    var lock = window.navigator.requestWakeLock(resourceName);
    
    resourceName
    A string representing the name of the resource to lock. Gaia uses three basic resource names: screen, cpu, and wifi, but any certified application can expose new resources.

    Value

    navigator.requestWakeLock returns a MozWakeLock object you must use to release the lock.

    Note: When the window that requested one or more wake locks is closed or destroyed, any wake locks it acquired are implicitly released; no manual release is necessary.

    MozWakeLock

    interface MozWakeLock
    {
      readonly attribute DOMString topic
    
      void unlock();
    }
    topic
    The string name of the resource with a lock.
    unlock
    A function which has to be called to release the lock. If several locks have been asked for, each of them must be released individually.

    Note: Calling the unlock method on a wake lock already released will throw an error of type NS_ERROR_DOM_INVALID_STATE_ERR.

    Example - keeping the screen on

    Any app can choose to keep the screen on while they are running. To achieve this, the app needs to obtain a lock for the screen resource when it is initialized.

    var lock = window.navigator.requestWakeLock('screen');
    

    App developers need to be responsible and think carefully about whether they need to keep the screen on. The risk of claiming the lock is that users may forget to close the app when they are done using it, which can result in significant increase in battery use. If you are not certain that obtaining the screen lock makes sense in all scenarios, then providing the option to enable or disable prevent screen lock option in the app settings, would be a smart move.

    If you do not release the screen wake lock at all, it will be obtained again from your app when it goes to the background or when the app terminates. However there are some scenarios when you do need to release the screen lock yourself, for example when user disables the option in settings, or when the app is not performing the task that required the screen to remain on. In those scenarios you just need to call the unlock() method to release the lock.

    lock.unlock();

    Screen wake lock is currently available to both hosted and packaged apps running on the Firefox OS platform.

    Specification

    Not part of any specification

    See also

    Document Tags and Contributors

    Contributors to this page: Sheppy, Jeremie, teoli, markg, arasbm, kscarfone, autonome
    Last updated by: autonome,
    Hide Sidebar