Interface PositionService

  • All Known Implementing Classes:
    AndroidPositionService, DummyPositionService, IOSPositionService

    public interface PositionService
    The PositionService provides details about a device's current location on earth.

    The PositionService provides a read-only position property that will be updated at regular intervals by the underlying platform implementation. A user of the PositionService can listen to changes of the position by registering a ChangeListener to the position property.

    The service gets started by calling either start() or start(com.gluonhq.attach.position.Parameters), and can be stopped at any time by calling stop().

    The desired accuracy can be modified by setting the proper Parameters, but the developer has to be aware of the risk of using higher precision, in terms of battery consumption.

    The service can be used also in background mode

    Example

     PositionService.create().ifPresent(service -> {
          service.positionProperty().addListener((obs, ov, nv) ->
              System.out.printf("Current position: %.5f, %.5f",
                  nv.getLatitude(), nv.getLongitude()));
          service.start();
      });

    Requirements

    The service requires the following changes on Android and iOS.

    However, these are handled automatically by the GluonFX plugin, when used.

    Android Configuration

    The permissions android.permission.ACCESS_COARSE_LOCATION and/or android.permission.ACCESS_FINE_LOCATION need to be added to the Android manifest.

    For background updates, the service positionBackgroundService has to be included as well. Note that in this mode the accuracy could be reduced by the system.

     <manifest ...>
        <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
        <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
        ...
        <service android:name="com.gluonhq.attach.android.AndroidPositionBackgroundService"
                 android:process=":positionBackgroundService" />
        <activity android:name="com.gluonhq.attach.android.PermissionRequestActivity" />
      </manifest>

    iOS Configuration

    Typically, the following keys are required:

     <key>NSLocationUsageDescription</key>
      <string>Reason to use Location Service (iOS 6+)</string>
      <key>NSLocationWhenInUseUsageDescription</key>
      <string>Reason to use Location Service (iOS 8+)</string>

    With Background mode enabled these are the required keys:

     
             <key>UIBackgroundModes</key>
             <array>
                 <string>location</string>
             </array>
             <key>NSLocationUsageDescription</key>
             <string>Reason to use Location Service (iOS 6+)</string>
             <key>NSLocationAlwaysUsageDescription</key>
             <string>Reason to use Location Service (iOS 8+) in background</string>
             <key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
             <string>Reason to use Location Service (iOS 8+) in background</string>
     

    Note that in this mode, UI updates are not allowed

    Since:
    3.0.0
    • Method Detail

      • positionProperty

        javafx.beans.property.ReadOnlyObjectProperty<Position> positionProperty()
        A read-only property containing information about the device's current location on earth. The property can contain a null object when the position of the device could be determined.
        Returns:
        a read-only object property containing the device's current location
      • getPosition

        Position getPosition()
        The current position on earth of the device. Can return null when the position of the device could not be determined, for instance when the GPS has been turned off.
        Returns:
        the current position of the device
      • start

        void start​(Parameters parameters)
        Starts the service. Developer must call either this method or start() to start the service
        Parameters:
        parameters - Parameters for configuring the service, including desired accuracy, minimum distance and time interval between notifications, or background mode
        Since:
        3.8.0
      • stop

        void stop()
        Stops the service. Developer may call this method to stop the service on demand
        Since:
        3.8.0