-
- 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 aChangeListener
to theposition property
.The service gets started by calling either
start()
orstart(com.gluonhq.attach.position.Parameters)
, and can be stopped at any time by callingstop()
.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/orandroid.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
-
-
Field Summary
Fields Modifier and Type Field Description static Parameters
DEFAULT_PARAMETERS
Default parameters used when the service is initalized withstart()
.
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Modifier and Type Method Description static java.util.Optional<PositionService>
create()
Returns an instance ofPositionService
.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 withDEFAULT_PARAMETERS
.void
start(Parameters parameters)
Starts the service.void
stop()
Stops the service.
-
-
-
Field Detail
-
DEFAULT_PARAMETERS
static final Parameters DEFAULT_PARAMETERS
Default parameters used when the service is initalized withstart()
. These include Medium accuracy and service only working when the app is active on foreground. To use custom parameters, seestart(com.gluonhq.attach.position.Parameters)
-
-
Method Detail
-
create
static java.util.Optional<PositionService> create()
Returns an instance ofPositionService
.- 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 anull
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 returnnull
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 withDEFAULT_PARAMETERS
. Developer must call either this method orstart(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 orstart()
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
-
-