com.gluonhq.charm.down.plugins

Interface PositionService

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.charm.down.plugins.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

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

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.impl.charm.down.plugins.android.AndroidPositionBackgroundService" 
             android:process=":positionBackgroundService" />
    <activity android:name="com.gluonhq.impl.charm.down.plugins.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

Type	Property and 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 and Description
static Parameters	DEFAULT_PARAMETERS Default parameters used when the service is initalized with start().

Method Summary

Modifier and Type	Method and Description
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 Detail

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:

getPosition()

Field Detail

DEFAULT_PARAMETERS

static final Parameters DEFAULT_PARAMETERS

Default parameters used when the service is initalized with start(). These include Medium accuracy and service only working when the app is active on foreground. To use custom parameters, see start(com.gluonhq.charm.down.plugins.Parameters)

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.

See Also:

getPosition()

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.charm.down.plugins.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