public class

LocationDisplayManager

extends Object
java.lang.Object
   ↳ com.esri.android.map.LocationDisplayManager

Class Overview

Class providing UI support to display the current location of the device on a MapView. The LocationDisplayManager.AutoPanMode determines the automatic panning behavior of the map to show the current device location. By default, the map does not automatically pan to show the current location.

To turn on automatic panning:

The pause() and resume() methods can be used to temporarily pause and resume the location manager, which can save device battery usage while the parent Activity or Fragment is paused. Call the stop() method when the containing Activity is destroyed.

Different pan modes are available, each being most appropriate for a specific type of map use; to automatically pan the center of the map to the current location, use LOCATION. Alternative modes are available to suit apps that give compass directions, or help a user navigate along a route. Various methods are available to customize aspects of the location appearance, including the symbols used to indicate the current location, updates to the location, location acquisition, and direction of travel.

If both the GPS and the Network location providers are disabled, then the LocationDisplayManager will not start and a warning will be logged. At least one of these providers needs to be enabled.

Summary

Nested Classes
enum LocationDisplayManager.AutoPanMode Modes of automatically panning the map to center on the current location. 
interface LocationDisplayManager.LocationFilterCallback Defines a custom location filter to apply to the LocationDisplayManager, which determines whether an incoming location update is applied or discarded. 
Public Methods
FillSymbol getAccuracySymbol()
Gets the symbol used to represent location accuracy.
LocationDisplayManager.AutoPanMode getAutoPanMode()
Checks the current LocationDisplayManager.AutoPanMode being used.
MarkerSymbol getCourseSymbol()
Gets the course symbol, used to display the current location for mode NAVIGATION when the current location is moving.
MarkerSymbol getDefaultSymbol()
Gets the symbol used to display the current location for modes OFF and LOCATION.
MarkerSymbol getHeadingSymbol()
Gets the symbol used for COMPASS.
Location getLocation()
Returns the current location in the spatial reference WGS84 (WKID=4326).
MarkerSymbol getLocationAcquiringSymbol()
Gets the symbol used to display last known location, while current location is being acquired.
LocationDisplayManager.LocationFilterCallback getLocationFilterCallback()
Gets the custom location filter callback, or null if default logic is being used.
LocationListener getLocationListener()
Gets the Android LocationListener instance.
float getNavigationPointHeightFactor()
Gets the factor by which the location symbol is positioned vertically from the bottom of the map when using NAVIGATION.
float getOpacity()
Gets the opacity of location symbols used for location, accuracy, and location pings.
MarkerSymbol getPingSymbol()
Gets the symbol used for indicating location updates.
Point getPoint()
Returns the current location in the map's spatial reference.
float getWanderExtentFactor()
Gets the wander extent factor, which affects autopanning.
boolean isAccuracyCircleOn()
Checks if the accuracy circle is displayed or not.
boolean isAllowNetworkLocation()
Checks if the network (cellular network and WiFi if available) is allowed to determine the current location.
boolean isShowLocation()
Checks if the current location symbol is shown.
boolean isShowPings()
Checks if the ping symbol is shown when location updates are received.
boolean isStarted()
Checks if the LocationDisplayManager has been started.
boolean isSymbolFound(float x, float y, int tolerance)
Checks if location symbol is found for the given coordinates and tolerance.
boolean isUseCourseSymbolOnMovement()
Gets whether the course symbol should be shown when the location update has a positive speed.
void pause()
Pauses the LocationDisplayManager; turns off location updates until the resume() method is called.
void resume()
Resumes LocationDisplayManager; turns location updates back on after the pause() method was called.
void setAccuracyCircleOn(boolean accuracyCircleOn)
Enables or disables the display of the accuracy circle.
void setAccuracySymbol(FillSymbol accuracySymbol)
Sets the symbol used to represent location accuracy.
void setAllowNetworkLocation(boolean allowNetworkLocation)
Controls whether the network (cellular network and WiFi if available) can be used to determine the current location.
void setAutoPanMode(LocationDisplayManager.AutoPanMode autoPanMode)
void setCourseSymbol(MarkerSymbol courseSymbol)
Sets the course symbol, used to display the current location for mode NAVIGATION when the current location is moving.
void setDefaultSymbol(MarkerSymbol defaultSymbol)
Sets the symbol used to display the current location for modes OFF and LOCATION.
void setHeadingSymbol(MarkerSymbol headingSymbol)
Sets the symbol used for COMPASS.
void setLocationAcquiringSymbol(MarkerSymbol locationAcquiringSymbol)
Sets the symbol used to display last known location, while current location is being acquired.
void setLocationFilterCallback(LocationDisplayManager.LocationFilterCallback locationFilterCallback)
Sets a custom location filter callback.
void setLocationListener(LocationListener locationListener)
Sets the Android LocationListener instance.
void setNavigationPointHeightFactor(float navigationPointHeightFactor)
Sets the factor by which the location symbol is positioned vertically from the bottom of the map when using NAVIGATION.
void setOpacity(float opacity)
Sets the opacity of location symbols used for location, accuracy, and location pings.
void setPingSymbol(MarkerSymbol pingSymbol)
Sets the symbol used for indicating location updates.
void setShowLocation(boolean showLocation)
Controls whether or not the current location symbol is shown.
void setShowPings(boolean showPings)
Controls whether to show the ping symbol when location updates are received.
void setUseCourseSymbolOnMovement(boolean useCourseSymbolOnMovement)
Sets whether the course symbol should be shown when the location update has a positive speed.
void setWanderExtentFactor(float wanderExtentFactor)
Sets the wander extent factor, which affects autopanning.
void start()
void stop()
[Expand]
Inherited Methods
From class java.lang.Object

Public Methods

public FillSymbol getAccuracySymbol ()

Gets the symbol used to represent location accuracy.

Returns
FillSymbol the symbol used to represent location accuracy
Throws
Exception

public LocationDisplayManager.AutoPanMode getAutoPanMode ()

Checks the current LocationDisplayManager.AutoPanMode being used. The default is OFF.

Returns
LocationDisplayManager.AutoPanMode The LocationDisplayManager.AutoPanMode being used.

public MarkerSymbol getCourseSymbol ()

Gets the course symbol, used to display the current location for mode NAVIGATION when the current location is moving. If not moving, the default symbol will be used instead.

Additionally, when in OFF or LOCATION, if the location updates have a positive speed, then this symbol will be rotated according to the location's bearing and displayed instead of the default symbol. Use setUseCourseSymbolOnMovement(boolean) with a value of false to disable this additional use of the course symbol.

Returns
MarkerSymbol the course symbol
Throws
Exception

public MarkerSymbol getDefaultSymbol ()

Gets the symbol used to display the current location for modes OFF and LOCATION. Additionally, if location updates do not indicate positive speed, this symbol will be used for NAVIGATION.

Returns
MarkerSymbol the symbol used for OFF and LOCATION
Throws
Exception

public MarkerSymbol getHeadingSymbol ()

Gets the symbol used for COMPASS.

Returns
MarkerSymbol the symbol used for COMPASS
Throws
Exception

public Location getLocation ()

Returns the current location in the spatial reference WGS84 (WKID=4326). To return the current location in the maps spatial reference instead, use the getPoint() method.

Returns
Location the current Location.

public MarkerSymbol getLocationAcquiringSymbol ()

Gets the symbol used to display last known location, while current location is being acquired. This is used in all modes of LocationDisplayManager.AutoPanMode until a new location fix is made.

Returns
MarkerSymbol the symbol used while location is being acquired
Throws
Exception

public LocationDisplayManager.LocationFilterCallback getLocationFilterCallback ()

Gets the custom location filter callback, or null if default logic is being used. See setLocationFilterCallback(LocationFilterCallback) for more information.

Returns
LocationDisplayManager.LocationFilterCallback the custom location filter callback, or null if using default logic

public LocationListener getLocationListener ()

Gets the Android LocationListener instance. The LocationListener can be used to listen to location updates, in order to perform work in addition to the work done by the LocationDisplayManager, for example, to update a TextBox displaying the current location's latitude and longitude.

Returns
LocationListener the LocationListener

public float getNavigationPointHeightFactor ()

Gets the factor by which the location symbol is positioned vertically from the bottom of the map when using NAVIGATION. When navigating in a map, the current location is typically vertically positioned near the bottom of the map, and horizontally centered in the map, so that the map displays as much of the route ahead as possible. Values should be between 0.0 (the bottom of the screen) and 1.0 (the top of the screen).

Returns
float The factor of the map height at which to vertically center the location graphic. Default value is 0.125.

public float getOpacity ()

Gets the opacity of location symbols used for location, accuracy, and location pings. Value will be between 0.0 and 1.0

Returns
float the opacity value, between 0.0 (completely transparent) and 1.0 (completely opaque).

public MarkerSymbol getPingSymbol ()

Gets the symbol used for indicating location updates.

Returns
MarkerSymbol the symbol used for indicating location updates
Throws
Exception

public Point getPoint ()

Returns the current location in the map's spatial reference.

Returns
Point the Point containing the current location.

public float getWanderExtentFactor ()

Gets the wander extent factor, which affects autopanning. If autopanning is LOCATION, this property determines how far from the center the current location may wander before the map will center on the location again. For example, with the default value of 0.5f, current location may wander up to half of the current extent. Once a location update is received that is outside this extent, the map will re-center again on the current location. Only works with LOCATION.

Returns
float The factor of how far current location may wander before autopanning. Default value is 0.5.

public boolean isAccuracyCircleOn ()

Checks if the accuracy circle is displayed or not.

Returns
boolean true if the accuracy circle is displayed; false otherwise.

public boolean isAllowNetworkLocation ()

Checks if the network (cellular network and WiFi if available) is allowed to determine the current location. Default is true.

Returns
boolean true if the network can be used to determine the current location; false otherwise.

public boolean isShowLocation ()

Checks if the current location symbol is shown.

Returns
boolean true true if the symbol is shown; false otherwise.

public boolean isShowPings ()

Checks if the ping symbol is shown when location updates are received.

Returns
boolean true if the ping symbol is shown; false otherwise.

public boolean isStarted ()

Checks if the LocationDisplayManager has been started.

Returns
boolean true if the LocationDisplayManager has been started; false otherwise.

public boolean isSymbolFound (float x, float y, int tolerance)

Checks if location symbol is found for the given coordinates and tolerance.

Parameters
x float: the screen coordinate along x axis in pixels.
y float: the screen coordinate along y axis in pixels.
tolerance int: tolerance in DP (density independent pixels).
Returns
boolean true if the location symbol is found; false otherwise.

public boolean isUseCourseSymbolOnMovement ()

Gets whether the course symbol should be shown when the location update has a positive speed. When using OFF or LOCATION, if the device is actively moving (the location has a positive speed), then the course symbol will be rotated to the device bearing (direction of movement) and will be displayed instead of the default symbol. Setting this to false will force the use of the default symbol, regardless of the device movement. This has no impact when using NAVIGATION or COMPASS.

Returns
boolean true if the course symbol is used when current location is moving; false otherwise.

public void pause ()

Pauses the LocationDisplayManager; turns off location updates until the resume() method is called. Call this method from the Activity or Fragment onPause method, in order to save device battery usage by the GPS sensor while the app is paused. Call the resume() method to receive location updates again.

See also:

public void resume ()

Resumes LocationDisplayManager; turns location updates back on after the pause() method was called. Call this method from the Activity or Fragment onResume method, in order to receive location updates again after updating was paused by calling the pause() method.

See also:

public void setAccuracyCircleOn (boolean accuracyCircleOn)

Enables or disables the display of the accuracy circle.

Parameters
accuracyCircleOn boolean: Set to true to display the accuracy circle; set to false if the symbol should not be displayed.

public void setAccuracySymbol (FillSymbol accuracySymbol)

Sets the symbol used to represent location accuracy.

Parameters
accuracySymbol FillSymbol: the symbol used to represent location accuracy
Throws
Exception

public void setAllowNetworkLocation (boolean allowNetworkLocation)

Controls whether the network (cellular network and WiFi if available) can be used to determine the current location.

Parameters
allowNetworkLocation boolean: Set to true if the network should be used to determine the current location, or false to use only the GPS.

public void setAutoPanMode (LocationDisplayManager.AutoPanMode autoPanMode)

Sets the LocationDisplayManager.AutoPanMode to be used. The default is OFF.

Parameters
autoPanMode LocationDisplayManager.AutoPanMode: the LocationDisplayManager.AutoPanMode to be used.

public void setCourseSymbol (MarkerSymbol courseSymbol)

Sets the course symbol, used to display the current location for mode NAVIGATION when the current location is moving. If not moving, the default symbol will be used instead.

Additionally, when in OFF or LOCATION, if the location updates have a positive speed, then this symbol will be rotated according to the location's bearing and displayed instead of the default symbol. Use setUseCourseSymbolOnMovement(boolean) with a value of false to disable this additional use of the course symbol.

Parameters
courseSymbol MarkerSymbol: the course symbol
Throws
Exception

public void setDefaultSymbol (MarkerSymbol defaultSymbol)

Sets the symbol used to display the current location for modes OFF and LOCATION. Additionally, if location updates do not indicate positive speed, this symbol will be used for NAVIGATION.

Parameters
defaultSymbol MarkerSymbol: the symbol used for OFF and LOCATION
Throws
Exception

public void setHeadingSymbol (MarkerSymbol headingSymbol)

Sets the symbol used for COMPASS.

Parameters
headingSymbol MarkerSymbol: the symbol used for COMPASS
Throws
Exception

public void setLocationAcquiringSymbol (MarkerSymbol locationAcquiringSymbol)

Sets the symbol used to display last known location, while current location is being acquired. This is used in all modes of LocationDisplayManager.AutoPanMode until a new location fix is found.

Parameters
locationAcquiringSymbol MarkerSymbol: the symbol used while location is being acquired
Throws
Exception

public void setLocationFilterCallback (LocationDisplayManager.LocationFilterCallback locationFilterCallback)

Sets a custom location filter callback. This callback will be used to determine whether incoming location updates should be applied or discarded. If not set, or if null is set, default logic will be used. See LocationDisplayManager.LocationFilterCallback for more information.

Parameters
locationFilterCallback LocationDisplayManager.LocationFilterCallback: the location filter callback to set, or null to use default logic

public void setLocationListener (LocationListener locationListener)

Sets the Android LocationListener instance.

Parameters
locationListener LocationListener: the LocationListener to set.

public void setNavigationPointHeightFactor (float navigationPointHeightFactor)

Sets the factor by which the location symbol is positioned vertically from the bottom of the map when using NAVIGATION. When navigating in a map, the current location is typically vertically positioned near the bottom of the map, and horizontally centered in the map, so that the map displays as much of the route ahead as possible. Values should be between 0.0 (the bottom of the screen) and 1.0 (the top of the screen).

Parameters
navigationPointHeightFactor float: The factor of the map height at which to vertically center the location graphic. Default value is 0.125.

public void setOpacity (float opacity)

Sets the opacity of location symbols used for location, accuracy, and location pings. Value must be between 0.0 and 1.0

Parameters
opacity float: A value between 0.0 (completely transparent) and 1.0 (completely opaque).

public void setPingSymbol (MarkerSymbol pingSymbol)

Sets the symbol used for indicating location updates.

Parameters
pingSymbol MarkerSymbol: the symbol used for indicating location updates
Throws
Exception

public void setShowLocation (boolean showLocation)

Controls whether or not the current location symbol is shown.

Parameters
showLocation boolean: Set to true to show the location symbol, or false if the symbol should not be shown.

public void setShowPings (boolean showPings)

Controls whether to show the ping symbol when location updates are received.

Parameters
showPings boolean: Set to true to show the ping symbol, or false if the symbol should not be shown.

public void setUseCourseSymbolOnMovement (boolean useCourseSymbolOnMovement)

Sets whether the course symbol should be shown when the location update has a positive speed. When using OFF or LOCATION, if the device is actively moving (the location has a positive speed), then the course symbol will be rotated to the device bearing (direction of movement) and will be displayed instead of the default symbol. Setting this to false will force the use of the default symbol, regardless of the device movement. This has no impact when using NAVIGATION or COMPASS.

Parameters
useCourseSymbolOnMovement boolean: Set to true to use the course symbol upon device movement; set to false to maintain use of the default symbol.

public void setWanderExtentFactor (float wanderExtentFactor)

Sets the wander extent factor, which affects autopanning. If autopanning is LOCATION, this property determines how far from the center the current location may wander before the map will center on the location again. For example, with the default value of 0.5f, current location may wander up to half of the current extent. Once a location update is received that is outside this extent, the map will re-center again on the current location. Only works with LOCATION.

Parameters
wanderExtentFactor float: the factor of how far current location may wander before autopanning

public void start ()

Starts the LocationDisplayManager. Use the isStarted() method to check that the LocationDisplayManager started correctly.

See also:

public void stop ()

Stops the LocationDisplayManager. Call this method when the Activity or Fragment that contains the LocationDisplayManager is destroyed, in order to stop the location listener receiving location updates.

See also: