mozilla
Your Search Results

    window.navigator.requestWakeLock Redirect 1

    Non-standard
    This feature is non-standard and is not on a standards track. Do not use it on production sites facing the Web: it will not work for every user. There may also be large incompatibilities between implementations and the behavior may change in the future.

    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 significat increase in battery use. If you are not certain that obtaining 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 scenatios 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 a the task that required the screen to remain on. In those senarios you just need to call the unlock() methos 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
    Last updated by: Sheppy,