Package org.vaadin.firitin.devicemotion

Class DeviceMotion

java.lang.Object
org.vaadin.firitin.devicemotion.DeviceMotion
public class DeviceMotion extends Object
A helper class to detect device motion events including acceleration and rotation.

This class uses the Device Motion API in the browser to detect motion 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 motion data. Use requestPermission(Runnable, Runnable) to request permission.

Author:
mstahv

  • Constructor Details

    • DeviceMotion

      public DeviceMotion()

  • Method Details

    • listen

      public static DeviceMotion listen(DeviceMotion.MotionListener listener)
      Starts listening to device motion events and notifies the listener with motion 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.DeviceMotion.MotionListener, org.vaadin.firitin.devicemotion.DeviceMotion.DeviceMotionHandler, java.lang.Runnable) instead.
      Parameters:
      listener - the listener called when device motion is detected
      Returns:
      a DeviceMotion 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, DeviceMotion.MotionListener listener, DeviceMotion.DeviceMotionHandler handler, Runnable onError)
      Requests permission (if needed) and then starts listening to device motion events. This is a convenience method that combines permission request with listening. The button click will trigger the permission request on iOS 13+. The handler is called with the DeviceMotion instance so you can configure it (e.g., throttling).
      Parameters:
      button - the button that will trigger the permission request
      listener - the listener called when device motion is detected
      handler - callback with DeviceMotion instance for configuration (can be null)
      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, DeviceMotion.MotionListener listener, Runnable onError)
      Requests permission (if needed) and then starts listening to device motion 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 motion is detected
      onError - callback if permission is denied
      Returns:
      the configured button

    • listen

      public static DeviceMotion listen(com.vaadin.flow.component.UI ui, DeviceMotion.MotionListener listener)
      Starts listening to device motion events and notifies the listener with motion data.
      Parameters:
      ui - the UI in which context the motion listener is to be registered
      listener - the listener called when device motion is detected
      Returns:
      a DeviceMotion instance that can be used to stop listening

    • cancel

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

    • throttleEvents

      public void throttleEvents(int milliseconds)
      Sets a throttle timeout for device motion 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 motion data. On iOS 13+, this must be called before listening to device motion 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 motion data. On iOS 13+, this must be called before listening to device motion 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 motion 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 motion 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<DeviceMotion.Permission> checkPermission()
      Checks the current permission state for device motion events.
      Returns:
      CompletableFuture that resolves to the permission state

    • checkPermission

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