Package org.vaadin.firitin.devicemotion

Class DeviceOrientation

java.lang.Object
org.vaadin.firitin.devicemotion.DeviceOrientation
public class DeviceOrientation extends Object
A helper class to detect device orientation events.

This class uses the Device Orientation API in the browser to detect the orientation of the device. The API mimics the JS counterpart.

Note that this API is primarily useful on mobile devices with accelerometers and gyroscopes. Desktop browsers may not support this API or may not have the necessary hardware. The API requires a secure context (HTTPS).

On iOS 13+, you must request permission before accessing device orientation data. Use requestPermission(Runnable, Runnable) to request permission.

Author:
mstahv

  • Constructor Details

    • DeviceOrientation

      public DeviceOrientation()

  • Method Details

    • listen

      public static DeviceOrientation listen(DeviceOrientation.OrientationListener listener)
      Starts listening to device orientation events and notifies the listener with orientation data. Note: On iOS 13+, you must request permission first using DeviceSensorPermissions.configurePermissionRequest(com.vaadin.flow.component.button.Button, org.vaadin.firitin.devicemotion.DeviceSensorPermissions.SensorType, java.lang.Runnable, java.lang.Runnable) or call requestPermissionAndListen(com.vaadin.flow.component.button.Button, org.vaadin.firitin.devicemotion.DeviceOrientation.OrientationListener, java.lang.Runnable) instead.
      Parameters:
      listener - the listener called when device orientation changes
      Returns:
      a DeviceOrientation instance that can be used to stop listening

    • requestPermissionAndListen

      public static com.vaadin.flow.component.button.Button requestPermissionAndListen(com.vaadin.flow.component.button.Button button, DeviceOrientation.OrientationListener listener, Runnable onError)
      Requests permission (if needed) and then starts listening to device orientation events. This is a convenience method that combines permission request with listening. The button click will trigger the permission request on iOS 13+.
      Parameters:
      button - the button that will trigger the permission request
      listener - the listener called when device orientation changes
      onError - callback if permission is denied
      Returns:
      the configured button

    • requestPermissionAndListen

      public static com.vaadin.flow.component.button.Button requestPermissionAndListen(com.vaadin.flow.component.button.Button button, DeviceOrientation.OrientationListener listener, boolean absolute, Runnable onError)
      Requests permission (if needed) and then starts listening to device orientation events. This is a convenience method that combines permission request with listening. The button click will trigger the permission request on iOS 13+.
      Parameters:
      button - the button that will trigger the permission request
      listener - the listener called when device orientation changes
      absolute - if true, listens to deviceorientationabsolute events
      onError - callback if permission is denied
      Returns:
      the configured button

    • listen

      public static DeviceOrientation listen(DeviceOrientation.OrientationListener listener, boolean absolute)
      Starts listening to device orientation events and notifies the listener with orientation data.
      Parameters:
      listener - the listener called when device orientation changes
      absolute - if true, listens to deviceorientationabsolute events (provides absolute orientation relative to Earth's coordinate frame)
      Returns:
      a DeviceOrientation instance that can be used to stop listening

    • listen

      public static DeviceOrientation listen(com.vaadin.flow.component.UI ui, DeviceOrientation.OrientationListener listener, boolean absolute)
      Starts listening to device orientation events and notifies the listener with orientation data.
      Parameters:
      ui - the UI in which context the orientation listener is to be registered
      listener - the listener called when device orientation changes
      absolute - if true, listens to deviceorientationabsolute events (provides absolute orientation relative to Earth's coordinate frame)
      Returns:
      a DeviceOrientation instance that can be used to stop listening

    • cancel

      public void cancel()
      Stops listening to device orientation events.

    • throttleEvents

      public void throttleEvents(int milliseconds)
      Sets a throttle timeout for device orientation events. Events will be sent at most once per the specified milliseconds. Default is 1000 ms (1 second).
      Parameters:
      milliseconds - the minimum interval between events in milliseconds

    • requestPermission

      public static void requestPermission(Runnable onSuccess, Runnable onError)
      Requests permission to access device orientation data. On iOS 13+, this must be called before listening to device orientation events. The request must be triggered by a user action (e.g., button click).
      Parameters:
      onSuccess - callback to run if permission is granted
      onError - callback to run if permission is denied or an error occurs

    • requestPermission

      public static void requestPermission(com.vaadin.flow.component.UI ui, Runnable onSuccess, Runnable onError)
      Requests permission to access device orientation data. On iOS 13+, this must be called before listening to device orientation events. The request must be triggered by a user action (e.g., button click).
      Parameters:
      ui - the UI in which context to request permission
      onSuccess - callback to run if permission is granted
      onError - callback to run if permission is denied or an error occurs

    • isPermissionRequired

      public static CompletableFuture<Boolean> isPermissionRequired()
      Checks if permission is required for device orientation events. Returns true on iOS 13+ Safari, false otherwise.
      Returns:
      CompletableFuture that resolves to true if permission API exists

    • isPermissionRequired

      public static CompletableFuture<Boolean> isPermissionRequired(com.vaadin.flow.component.UI ui)
      Checks if permission is required for device orientation events. Returns true on iOS 13+ Safari, false otherwise.
      Parameters:
      ui - the UI in which context to check
      Returns:
      CompletableFuture that resolves to true if permission API exists

    • checkPermission

      public static CompletableFuture<DeviceOrientation.Permission> checkPermission()
      Checks the current permission state for device orientation events.
      Returns:
      CompletableFuture that resolves to the permission state

    • checkPermission

      public static CompletableFuture<DeviceOrientation.Permission> checkPermission(com.vaadin.flow.component.UI ui)
      Checks the current permission state for device orientation events.
      Parameters:
      ui - the UI in which context to check
      Returns:
      CompletableFuture that resolves to the permission state