public abstract class LocationManager

  1. Object
  2. LocationManager

The LocationManager is the main entry to retrieveLocation or to bind a LocationListener, important: in order to use location on iOS you will need to define the build argument ios.locationUsageDescription. This build argument should be used to describe to Apple & the users why you need to use the location functionality.

Trivial one time usage of location data can look like this sample:

Location position = LocationManager.getLocationManager().getCurrentLocationSync();

You can also track location in the foreground using API calls like this:

public class MyListener implements LocationListener {
    public void locationUpdated(Location location) {
        // update UI etc.
    }

    public void providerStateChanged(int newState) {
        // handle status changes/errors appropriately
    }
}
LocationManager.getLocationManager().setLocationListener(new MyListener());

The sample below demonstrates the usage of the background geofencing API:

// File: GeofenceListenerImpl.java
public class GeofenceListenerImpl implements GeofenceListener {
@Override
    public void onExit(String id) {
    }
@Override
    public void onEntered(String id) {
        if(!Display.getInstance().isMinimized()) {
            Display.getInstance().callSerially(() -> {
                Dialog.show("Welcome", "Thanks for arriving", "OK", null);
            });
        } else {
            LocalNotification ln = new LocalNotification();
            ln.setId("LnMessage");
            ln.setAlertTitle("Welcome");
            ln.setAlertBody("Thanks for arriving!");
            Display.getInstance().scheduleLocalNotification(ln, System.currentTimeMillis() + 10, LocalNotification.REPEAT_NONE);
        }
    }
}
// File: GeofenceSample.java
Geofence gf = new Geofence("test", loc, 100, 100000);
LocationManager.getLocationManager().addGeoFencing(GeofenceListenerImpl.class, gf);

Fields

public static final int AVAILABLE = 0
public static final int OUT_OF_SERVICE = 1
public static final int TEMPORARILY_UNAVAILABLE = 2

Constructors

public LocationManager()

Methods

public static LocationManager getLocationManager()Gets the LocationManager instance
public int getStatus()Gets the Manager status: AVAILABLE, OUT_OF_SERVICE or TEMPORARILY_UNAVAILABLE
protected void setStatus(int status)Allows the implementation to set the status of the location
public abstract Location getCurrentLocation() throws IOExceptionGets the current Location of the device, in most cases this uses the GPS.
protected final LocationListener getListener()
public Location getCurrentLocationSync()Returns the current location synchronously, this is useful if you just want to know the location NOW and don’t care about tracking location.
public Location getCurrentLocationSync(long timeout)Returns the current location synchronously, this is useful if you just want to know the location NOW and don’t care about tracking location.
public abstract Location getLastKnownLocation()Gets the last known Location of the device.
public void setLocationListener(LocationListener l, LocationRequest req)Sets a LocationListener on the device, use this method if you need to be updated on the device Locations rather then calling getCurrentLocation.
public void addGeoFencing(Class geofenceListenerClass, Geofence gf)Adds a geo fence listener to gets an event once the device is in/out of the Geofence range.
public void removeGeoFencing(String id)Stop tracking a Geofence if isGeofenceSupported() returns false this method does nothing
protected LocationListener getLocationListener()Allows the implementation to notify the location listener of changes to location
public void setLocationListener(LocationListener l)Sets a LocationListener on the device, use this method if you need to be updated on the device Locations rather then calling getCurrentLocation.
protected LocationRequest getRequest()Gets the LocationRequest
protected Class getBackgroundLocationListener()Gets the LocationListener class that handles background location updates.
public void setBackgroundLocationListener(Class locationListener)Use this method to track background location updates when the application is not running anymore.
protected abstract void bindListener()Bind the LocationListener to get events
protected abstract void clearListener()Stop deliver events for the LocationListener
protected void bindBackgroundListener()Bind the Background LocationListener to get events
protected void clearBackgroundListener()Stop deliver events for the Background LocationListener
public boolean isGPSDetectionSupported()Returns true if the platform is able to detect if the GPS is on or off.
public boolean isBackgroundLocationSupported()Returns true if the platform is able to track background location.
public boolean isGeofenceSupported()Returns true if the platform supports Geofence
public boolean isGPSEnabled()Returns GPS on/off state if isGPSDetectionSupported() returns true

Inherited methods

Field details

AVAILABLE

public static final int AVAILABLE = 0

OUT_OF_SERVICE

public static final int OUT_OF_SERVICE = 1

TEMPORARILY_UNAVAILABLE

public static final int TEMPORARILY_UNAVAILABLE = 2

Constructor details

LocationManager

public LocationManager()

Method details

getLocationManager

public static LocationManager getLocationManager()
Gets the LocationManager instance

getStatus

public int getStatus()
Gets the Manager status: AVAILABLE, OUT_OF_SERVICE or TEMPORARILY_UNAVAILABLE

Returns

the status of the LoactionManager

setStatus

protected void setStatus(int status)
Allows the implementation to set the status of the location

Parameters

status int
the new status

getCurrentLocation

public abstract Location getCurrentLocation() throws IOException
Gets the current Location of the device, in most cases this uses the GPS. Notice! This method will only return a valid value after the location listener callback returns

Returns

a Location Object

Throws

IOException
if Location cannot be retrieve from the device

getListener

protected final LocationListener getListener()

getCurrentLocationSync

public Location getCurrentLocationSync()
Returns the current location synchronously, this is useful if you just want to know the location NOW and don’t care about tracking location. Notice that this method will block until a result is returned so you might want to use something like InfiniteProgress while this is running

Returns

the current location or null in case of an error

getCurrentLocationSync

public Location getCurrentLocationSync(long timeout)
Returns the current location synchronously, this is useful if you just want to know the location NOW and don’t care about tracking location. Notice that this method will block until a result is returned so you might want to use something like InfiniteProgress while this is running

Parameters

timeout long
timeout in milliseconds or -1 to never timeout

Returns

the current location or null in case of an error

getLastKnownLocation

public abstract Location getLastKnownLocation()
Gets the last known Location of the device.

Returns

a Location Object

setLocationListener

public void setLocationListener(LocationListener l, LocationRequest req)
Sets a LocationListener on the device, use this method if you need to be updated on the device Locations rather then calling getCurrentLocation.

Parameters

l LocationListener
a LocationListener or null to stop the current listener from getting updates
req LocationRequest
provide the settings in which we are interested to get updates to the Listener.

addGeoFencing

public void addGeoFencing(Class geofenceListenerClass, Geofence gf)

Adds a geo fence listener to gets an event once the device is in/out of the Geofence range. The GeoFence events can arrive in the background therefore it is recommended to check the app state before deciding how to process this event. Use Display.isMinimized() to know if the app is currently running. if isGeofenceSupported() returns false this method does nothing

NOTE: For iOS you must include the ios.background_modes build hint with a value that includes “location” for geofencing to work.

Parameters

geofenceListenerClass Class
a Class that implements the GeofenceListener interface this class must have an empty constructor
gf Geofence
a Geofence to track

removeGeoFencing

public void removeGeoFencing(String id)

Stop tracking a Geofence if isGeofenceSupported() returns false this method does nothing

NOTE: For iOS you must include the ios.background_modes build hint with a value that includes “location” for geofencing to work.

Parameters

id String
a Geofence id to stop tracking

getLocationListener

protected LocationListener getLocationListener()
Allows the implementation to notify the location listener of changes to location

Returns

location listener instance

setLocationListener

public void setLocationListener(LocationListener l)
Sets a LocationListener on the device, use this method if you need to be updated on the device Locations rather then calling getCurrentLocation.

Parameters

l LocationListener
a LocationListener or null to stop the current listener from getting updates

getRequest

protected LocationRequest getRequest()
Gets the LocationRequest

getBackgroundLocationListener

protected Class getBackgroundLocationListener()

Gets the LocationListener class that handles background location updates.

NOTE: For iOS you must include the ios.background_modes build hint with a value that includes “location” for background locations to work.

setBackgroundLocationListener

public void setBackgroundLocationListener(Class locationListener)
Use this method to track background location updates when the application is not running anymore. Do not perform long operations here, iOS wake-up time is very short(around 10 seconds). Notice this listener can sends events also when the app is in the foreground, therefore it is recommended to check the app state before deciding how to process this event. Use Display.isMinimized() to know if the app is currently running.

Parameters

locationListener Class
a class that implements the LocationListener interface this class must have an empty constructor since the underlying implementation will try to create an instance and invoke the locationUpdated method

bindListener

protected abstract void bindListener()
Bind the LocationListener to get events

clearListener

protected abstract void clearListener()
Stop deliver events for the LocationListener

bindBackgroundListener

protected void bindBackgroundListener()
Bind the Background LocationListener to get events

clearBackgroundListener

protected void clearBackgroundListener()
Stop deliver events for the Background LocationListener

isGPSDetectionSupported

public boolean isGPSDetectionSupported()
Returns true if the platform is able to detect if the GPS is on or off. see also isGPSEnabled()

Returns

true if platform is able to detect GPS on/off

isBackgroundLocationSupported

public boolean isBackgroundLocationSupported()

Returns true if the platform is able to track background location.

NOTE: For iOS you must include the ios.background_modes build hint with a value that includes “location” for background locations to work.

Returns

true if platform supports background location

isGeofenceSupported

public boolean isGeofenceSupported()

Returns true if the platform supports Geofence

NOTE: For iOS you must include the ios.background_modes build hint with a value that includes “location” for geofencing to work.

Returns

true if platform supports Geofence

isGPSEnabled

public boolean isGPSEnabled()
Returns GPS on/off state if isGPSDetectionSupported() returns true

Returns

true if GPS is on