Module com.gluonhq.attach.position
Package com.gluonhq.attach.position

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

  • Property Summary

    Properties
    Type
    Property
    Description
    javafx.beans.property.ReadOnlyObjectProperty<Position>
    position
    A read-only property containing information about the device's current location on earth.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final Parameters
    DEFAULT_PARAMETERS
    Default parameters used when the service is initalized with start().

  • Method Summary

    Modifier and Type
    Method
    Description
    static Optional<PositionService>
    create()
    Returns an instance of PositionService.
    Position
    getPosition()
    The current position on earth of the device.
    javafx.beans.property.ReadOnlyObjectProperty<Position>
    positionProperty()
    A read-only property containing information about the device's current location on earth.
    void
    start()
    Starts the service with DEFAULT_PARAMETERS.
    void
    start(Parameters parameters)
    Starts the service.
    void
    stop()
    Stops the service.

  • Property Details

    • position

      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.
      See Also:

  • Field Details

  • Method Details

    • create

      static Optional<PositionService> create()
      Returns an instance of PositionService.
      Returns:
      An instance of PositionService.

    • 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.
      See Also:

    • 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()
      Starts the service with DEFAULT_PARAMETERS. Developer must call either this method or start(com.gluonhq.attach.position.Parameters) to start the service
      Since:
      3.8.0

    • 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