Class ScreenWakeLock

java.lang.Object
org.vaadin.firitin.util.ScreenWakeLock
public class ScreenWakeLock extends Object
A Vaadin wrapper for the browser's Screen Wake Lock API.

The Screen Wake Lock API prevents devices from dimming or locking the screen when an application needs to keep running and remain visible to the user. This is particularly useful for applications like e-book readers, navigation apps, recipe viewers, presentation software, QR/barcode scanners, or any voice or gesture-controlled applications.

Notes:

  • Only active documents can acquire screen wake locks. Previously acquired locks are automatically released when the document becomes inactive (e.g., when the page is hidden or minimized).
  • Applications should listen for visibility changes and reacquire the wake lock when the page becomes visible again if continuous lock is required.
  • The API requires a secure context (HTTPS) and browser support may vary.
See Also:

  • Method Details

    • request

      public static CompletableFuture<ScreenWakeLock.State> request(com.vaadin.flow.component.UI ui, Runnable onReleased)
      Requests a screen wake lock for the specified UI instance.

      This method acquires a WakeLockSentinel by calling navigator.wakeLock.request("screen") in the browser, which prevents the device screen from dimming or locking while the lock is active.

      Important: If the document becomes inactive (e.g., when the user switches tabs or minimizes the browser), the wake lock is automatically released by the browser. Applications that require continuous wake lock should monitor page visibility changes and reacquire the lock when the page becomes visible again.

      Parameters:
      ui - the Vaadin UI instance for which to request the wake lock
      onReleased - an optional callback that will be invoked when the wake lock is released (either manually via release(UI) or automatically by the browser). Can be null if no callback is needed.
      Returns:
      a CompletableFuture that completes with the wake lock state. Returns ScreenWakeLock.State.ACTIVE if the lock was successfully acquired, or ScreenWakeLock.State.ERROR if an error occurred (e.g., browser doesn't support the API, permissions denied, or not in a secure context).
      See Also:

    • request

      public static CompletableFuture<ScreenWakeLock.State> request(Runnable onReleased)
      Requests a screen wake lock for the current UI instance with a release callback.

      This is a convenience method that calls request(UI, Runnable) with the current UI.

      Parameters:
      onReleased - a callback that will be invoked when the wake lock is released (either manually via release() or automatically by the browser). Can be null if no callback is needed.
      Returns:
      a CompletableFuture that completes with the wake lock state
      See Also:

    • request

      public static CompletableFuture<ScreenWakeLock.State> request()
      Requests a screen wake lock for the current UI instance without a release callback.

      This is a convenience method that calls request(UI, Runnable) with the current UI and no release callback.

      Returns:
      a CompletableFuture that completes with the wake lock state
      See Also:

    • release

      public static void release(com.vaadin.flow.component.UI ui)
      Releases the screen wake lock for the specified UI instance.

      This method manually releases the wake lock by calling release() on the WakeLockSentinel. Once released, if a new wake lock is needed, a new request must be made via request(UI, Runnable).

      If no wake lock is currently active, this method has no effect.

      Parameters:
      ui - the Vaadin UI instance for which to release the wake lock
      See Also:

    • release

      public static void release()
      Releases the screen wake lock for the current UI instance.

      This is a convenience method that calls release(UI) with the current UI.

      See Also:

    • checkState

      public static CompletableFuture<ScreenWakeLock.State> checkState(com.vaadin.flow.component.UI ui)
      Checks the current state of the screen wake lock for the specified UI instance.

      This method queries the WakeLockSentinel.released property to determine the current state of the wake lock. Note that this only checks the state of the wake lock that was requested through this wrapper class.

      Parameters:
      ui - the Vaadin UI instance for which to check the wake lock state
      Returns:
      a CompletableFuture that completes with one of the following states:
      See Also:

    • checkState

      public static CompletionStage<ScreenWakeLock.State> checkState()
      Checks the current state of the screen wake lock for the current UI instance.

      This is a convenience method that calls checkState(UI) with the current UI.

      Returns:
      a CompletionStage that completes with the wake lock state
      See Also: