Module com.esri.arcgisruntime
Package com.esri.arcgisruntime.mapping.view

Class LocationDisplay

java.lang.Object
com.esri.arcgisruntime.mapping.view.LocationDisplay
public final class LocationDisplay extends Object
Manages the display of a device's location in a MapView.

Location display can retrieve the device's current location from a LocationDataSource and display it on top of an ArcGISMap. As the device moves, the map view can respond to new locations by updating the position of the location symbol on the display. It can also set the viewpoint when an updated location is received, or automatically pan and rotate the map when the current location, heading, or course changes.

Each MapView has its own instance of LocationDisplay so you don't have to explicitly instantiate the location display. The location information is provided by a LocationDataSource. The current position of the device is provided by default from the operating system. To start receiving location updates, and display the current location, you must start the location display's data source.

Apart from the device operating system's built-in location, you can also display locations from other sources, including external (high accuracy) GPS, or simulated locations (for mocking location updates) using the following location data sources:

By default, the location display uses a blue, round symbol to show the current location. Depending on signal strength, satellite positions, and other factors, the accuracy of the reported location can vary. An additional blue circle (getAccuracySymbol()) around the location symbol indicates the estimated range of accuracy for the current location. As locations are read from the configured LocationDataSource, this outer circle may contract and expand as accuracy increases or decreases. You can display further information about the location using the following symbols: You can change the default symbology of these symbols to make them more visible against the underlying map cartography, increase their visibility for visually impaired users, or match an app's visual appearance.
Since:
100.9.0
See Also:

  • Method Details

    • setLocationDataSource

      public void setLocationDataSource(LocationDataSource locationDataSource)
      Sets the location data source used for generating location updates.

      LocationDisplay uses a location data source to provide the current position of the device. To start receiving location updates, and display the current location, you must start the location data source.

      By default the location data source obtains locations from the device's operating system.

      Alternative location data sources include:

      Parameters:
      locationDataSource - A LocationDataSource object
      Throws:
      IllegalArgumentException - if locationDataSource is null
      Since:
      100.9.0

    • getLocationDataSource

      public LocationDataSource getLocationDataSource()
      Gets the location data source used for generating location updates.

      LocationDisplay uses a location data source to provide the current position of the device. To start receiving location updates, and display the current location, you must start the location data source.

      By default the location data source obtains locations from the device's operating system.

      Alternative location data sources include:

      Returns:
      the LocationDataSource object, or null if it has not yet been set
      Since:
      100.9.0

    • getLocation

      public LocationDataSource.Location getLocation()
      Gets the current LocationDataSource.Location, in the same spatial reference as the input provided by the LocationDataSource.

      Alternatively, use the getMapLocation() method to return the current location in the map's spatial reference.

      Typically the coordinates from a device's GPS or network location provider (via the platform location services) are given as latitude and longitude, using the WGS 1984 geographic coordinate system. You can find out which spatial reference is used by checking the Geometry.getSpatialReference() method of the location data source's position.

      Returns:
      the current LocationDataSource.Location in the current location data source's spatial reference
      Since:
      100.9.0

    • getMapLocation

      public Point getMapLocation()
      Gets a Point representing the current location, in the same spatial reference as the map.
      Returns:
      the current location in the map's spatial reference
      Since:
      100.9.0

    • getHeading

      public double getHeading()
      Gets the heading angle of the current location in degrees relative to north.

      This is only applicable when the auto-pan mode is LocationDisplay.AutoPanMode.COMPASS_NAVIGATION. The value 0 means the device is pointed toward magnetic north, 90 means it is pointed due east, 180 means it is pointed due south, and so on. A negative value indicates that the heading could not be determined.

      Returns:
      the heading angle, in degrees clockwise, relative from north
      Since:
      100.9.0

    • setDefaultSymbol

      public void setDefaultSymbol(Symbol defaultSymbol)
      Sets the symbol used for the location when not moving.

      Changing the location symbols is typically done if the existing symbols do not work well with the underlying map cartography, to increase visibility for visually impaired users, or to match an apps visual appearance.

      Parameters:
      defaultSymbol - the new symbol to be used to display current location
      Throws:
      IllegalArgumentException - if defaultSymbol is null
      Since:
      100.9.0

    • getDefaultSymbol

      public Symbol getDefaultSymbol()
      Gets the symbol used for the location when not moving.

      Changing the location symbols is typically done if the existing symbols do not work well with the underlying map cartography, to increase visibility for visually impaired users, or to match an apps visual appearance.

      Returns:
      the symbol used to display current location
      Since:
      100.9.0

    • setPingAnimationSymbol

      public void setPingAnimationSymbol(Symbol pingAnimationSymbol)
      Sets the symbol that will be animated around the location symbol, to indicate when location updates are received.

      Location update animations are only shown when isShowPingAnimation() is true. Set any type of marker, composite, or multilayer symbol as the ping animation symbol, and the LocationDisplay will take care of the animation.

      Parameters:
      pingAnimationSymbol - the new symbol that will be animated to indicate location updates
      Throws:
      IllegalArgumentException - if pingAnimationSymbol is null
      Since:
      100.9.0

    • getPingAnimationSymbol

      public Symbol getPingAnimationSymbol()
      Gets the symbol animated around the location symbol, to indicate when location updates are received. Default symbol is a circle with a blue outline.

      Location update animations are only shown when isShowPingAnimation() is true.

      Returns:
      the symbol animated to indicate location updates
      Since:
      100.9.0

    • setOpacity

      public void setOpacity(float opacity)
      Sets the opacity of the location symbols displayed on the map. Applies to getDefaultSymbol(), getCourseSymbol(), getHeadingSymbol(), getAcquiringSymbol(), and getAccuracySymbol(). Permitted values are between 0.0 (completely transparent) and 1.0 (completely opaque).
      Parameters:
      opacity - the new opacity value indicating how the location symbols should be displayed
      Throws:
      IllegalArgumentException - if opacity is less than 0.0 or greater than 1.0
      Since:
      100.9.0

    • getOpacity

      public float getOpacity()
      Gets the opacity of the location symbols displayed on the map. Applies to getDefaultSymbol(), getCourseSymbol(), getHeadingSymbol(), getAcquiringSymbol(), and getAccuracySymbol(). The default value is 1.0, indicating symbols are drawn completely opaque.
      Returns:
      a value indicating the current opacity of the location symbol display, between 0.0 (completely transparent) and 1.0 (completely opaque)
      Since:
      100.9.0

    • setShowAccuracy

      public void setShowAccuracy(boolean enable)
      Sets whether a symbol is displayed to indicate an approximate area of location horizontal accuracy.
      Parameters:
      enable - true if the accuracy symbol should be displayed; false otherwise
      Since:
      100.9.0

    • isShowAccuracy

      public boolean isShowAccuracy()
      Indicates if a symbol is displayed to indicate an approximate area of location horizontal accuracy. If true, an area surrounding the location symbol is displayed using getAccuracySymbol(). The default value is true.
      Returns:
      true if the accuracy symbol is displayed; false otherwise
      Since:
      100.9.0

    • setShowPingAnimation

      public void setShowPingAnimation(boolean enable)
      Sets whether the location update animated symbol is displayed or not. This animated symbol visually indicates to the user when the current location is being updated.
      Parameters:
      enable - true if the location update animated symbol should be shown; false otherwise
      Since:
      100.9.0

    • isShowPingAnimation

      public boolean isShowPingAnimation()
      Returns whether the ping animation symbol is displayed or not. The ping animation symbol visually indicates the current location is being adjusted and updated with the new one. The default value is true.

      By default, the animation shows an expanding blue circle around the location, using the getPingAnimationSymbol().

      Returns:
      true if the location update animated symbol will currently be shown when updates are received; false otherwise
      Since:
      100.9.0

    • setAccuracySymbol

      public void setAccuracySymbol(Symbol accuracySymbol)
      Sets the symbol used to represent location accuracy.

      The accuracy of the location can vary depending on signal strength, satellite positions, and other factors. This circle may contract and expand as the accuracy of the locations, read from the LocationDataSource, increases or decreases.

      Parameters:
      accuracySymbol - the new symbol to be used to display location horizontal accuracy
      Throws:
      IllegalArgumentException - if accuracySymbol is null
      Since:
      100.9.0

    • getAccuracySymbol

      public Symbol getAccuracySymbol()
      Gets the symbol used to represent location accuracy.

      The accuracy of the location can vary depending on signal strength, satellite positions, and other factors. This circle may contract and expand as the accuracy of the locations, read from the LocationDataSource, increases or decreases.

      The default symbol is a blue outline with a semi-transparent white fill.

      Returns:
      accuracySymbol the symbol used to represent location accuracy
      Since:
      100.9.0

    • setAcquiringSymbol

      public void setAcquiringSymbol(Symbol acquiringSymbol)
      Sets the symbol used to display the last known location while the current location is being acquired.

      The symbol will be shown until a new location fix is found. This symbol may be used immediately after starting the LocationDisplay. Once an up-to-date location is acquired, the getDefaultSymbol(), getCourseSymbol(), or getHeadingSymbol() is used, depending on the current settings of the LocationDisplay.

      Parameters:
      acquiringSymbol - the new symbol to be used when location is being acquired
      Throws:
      IllegalArgumentException - if acquiringSymbol is null
      Since:
      100.9.0

    • getAcquiringSymbol

      public Symbol getAcquiringSymbol()
      Gets the symbol used to display the last known location while the current location is being acquired.

      The symbol will be shown until a new location fix is found. This symbol may be used immediately after starting the LocationDisplay. Once an up-to-date location is acquired, the getDefaultSymbol(), getCourseSymbol(), or getHeadingSymbol() is used, depending on the current settings of the LocationDisplay. The default symbol is a grey circle.

      Returns:
      acquiringSymbol the symbol used when location is being acquired
      Since:
      100.9.0

    • setAutoPanMode

      public void setAutoPanMode(LocationDisplay.AutoPanMode autoPanMode)
      Sets auto-pan mode, which defines how the MapView reacts when location updates are received.

      The different auto-pan modes are suited for different types of app, including modes designed for navigation on foot and in a vehicle. They affect the symbols used to display device location, the initial zooming behavior, and the panning behavior of the MapView.

      The auto-pan modes include:

      • RECENTER - the map view attempts to keep the location symbol on-screen by re-centering the location symbol when the symbol moves outside an extent defined by the getWanderExtentFactor().
      • NAVIGATION - the location symbol is pinned to a point on the screen and always points toward the top edge of the device. The map pans and rotates based on location updates and the direction of travel.
      • COMPASS_NAVIGATION - the location symbol is pinned to a point on the screen and always points toward the top edge of the device. The map rotates based on the user's bearing relative to magnetic north.
      • OFF - the map only updates the position of the location symbol on the map.
      To start the LocationDisplay in a specific mode, call this method before you start the LocationDataSource.

      Any default zooming behavior (besides scrolling) or any operation that modifies the Viewpoint will automatically set the auto-pan mode to LocationDisplay.AutoPanMode.OFF.

      Parameters:
      autoPanMode - the new AutoPanMode
      Throws:
      IllegalArgumentException - if autoPanMode is null
      Since:
      100.9.0

    • getAutoPanMode

      public LocationDisplay.AutoPanMode getAutoPanMode()
      Gets auto-pan mode, which defines how the MapView reacts when location updates are received.

      The different auto-pan modes are suited for different types of app, including modes designed for navigation on foot and in a vehicle. They affect the symbols used to display device location, the initial zooming behavior, and the panning behavior of the MapView.

      The auto-pan modes include:

      • RECENTER - the map view attempts to keep the location symbol on-screen by re-centering the location symbol when the symbol moves outside an extent defined by the getWanderExtentFactor().
      • NAVIGATION - the location symbol is pinned to a point on the screen and always points toward the top edge of the device. The map pans and rotates based on location updates and the direction of travel.
      • COMPASS_NAVIGATION - the location symbol is pinned to a point on the screen and always points toward the top edge of the device. The map rotates based on the user's bearing relative to magnetic north.
      • OFF - the map only updates the position of the location symbol on the map.
      Any default zooming behavior (besides scrolling) or any operation that modifies the Viewpoint will automatically set the auto-pan mode to LocationDisplay.AutoPanMode.OFF.

      The default auto-pan mode is AutoPanMode.OFF.

      Returns:
      the current AutoPanMode
      Since:
      100.9.0

    • setInitialZoomScale

      public void setInitialZoomScale(double initialZoomScale)
      Sets the scale that the map should automatically be zoomed to upon receiving the first location update.

      The initial map scale to which the MapView will zoom when the first location update is received after the auto-pan mode is changed from LocationDisplay.AutoPanMode.OFF to any other value. The default value is 10,000.

      Parameters:
      initialZoomScale - the map scale to zoom to when first location update is received
      Throws:
      IllegalArgumentException - if initialZoomScale is less than 0
      Since:
      100.9.0
      See Also:

    • getInitialZoomScale

      public double getInitialZoomScale()
      Gets the scale that the map should automatically be zoomed to upon receiving the first location update.

      The initial map scale to which the MapView will zoom when the first location update is received after the auto-pan mode is changed from LocationDisplay.AutoPanMode.OFF to any other value. The default value is 10,000.

      Returns:
      the map scale to zoom to when first location update is received
      Since:
      100.9.0
      See Also:

    • getNavigationPointHeightFactor

      public float getNavigationPointHeightFactor()
      Gets the factor of map height at which the location symbol is positioned, vertically from the bottom of the MapView, when using LocationDisplay.AutoPanMode.NAVIGATION or LocationDisplay.AutoPanMode.COMPASS_NAVIGATION. The default value is 0.125 (1/8th of the distance up the MapView). A value of 0.0 indicates the location symbol is positioned at the bottom edge of the MapView, and a value of 1.0 indicates the top edge.

      When using a map for navigation of a route, current device location is typically positioned near the bottom of the map and centered horizontally across the map, so that the map displays as much of the route ahead as possible. The map moves underneath this symbol, while the symbol stays fixed, relative to the MapView boundary.

      Returns:
      the factor of map height at which the location symbol is vertically positioned
      Since:
      100.9.0

    • setNavigationPointHeightFactor

      public void setNavigationPointHeightFactor(float navigationPointHeightFactor)
      Sets the factor of map height at which the location symbol is positioned, vertically from the bottom of the MapView, when using LocationDisplay.AutoPanMode.NAVIGATION or LocationDisplay.AutoPanMode.COMPASS_NAVIGATION. Setting a value of 0.0 will draw the location symbol at the bottom of the screen, and a value of 1.0 at the top of the screen.
      Parameters:
      navigationPointHeightFactor - the new factor of map height at which the location symbol should be vertically positioned
      Throws:
      IllegalArgumentException - if navigationPointHeightFactor is less than 0.0 or greater than 1.0
      Since:
      100.9.0

    • setWanderExtentFactor

      public void setWanderExtentFactor(float wanderExtentFactor)
      Sets the wander extent factor, which controls the re-centering behavior of the MapView when the location changes.

      This is the proportion of the current extent within which the location can be without automatically panning the map. Permitted values are in the range between 0 (continuous panning) and 1 (only pan when the location reaches the edge of the current extent). This value only applies when the auto-pan mode is LocationDisplay.AutoPanMode.RECENTER. Lower values within this range will cause the map to re-center more often, leading to higher CPU and battery consumption.

      Parameters:
      wanderExtentFactor - the factor of map extent within which the current location may move before the map is re-centered
      Throws:
      IllegalArgumentException - if wanderExtentFactor is less than 0.0 or greater than 1.0
      Since:
      100.9.0

    • getWanderExtentFactor

      public float getWanderExtentFactor()
      Gets the wander extent factor, which controls the re-centering behavior of the MapView when the location changes.

      This is the proportion of the current extent within which the location can be without automatically panning the map. Permitted values are in the range between 0 (continuous panning) and 1 (only pan when the location reaches the edge of the current extent). This value only applies when the auto-pan mode is LocationDisplay.AutoPanMode.RECENTER. Lower values within this range will cause the map to re-center more often, leading to higher CPU and battery consumption.

      Returns:
      the factor of map extent within which the current location may move before the map is re-centered
      Since:
      100.9.0

    • setUseCourseSymbolOnMovement

      public void setUseCourseSymbolOnMovement(boolean useCourseSymbolOnMovement)
      Sets whether the getCourseSymbol() is used to display current location, when the location updates indicate the device is moving.

      If no course information is available, the default symbol will be used instead. The course symbol is rotated in order to indicate the device's direction of travel.

      Generally, course information is only available if the device is actively moving (the location has a positive speed).

      Parameters:
      useCourseSymbolOnMovement - true to use the course symbol to display the location; false to use the default symbol
      Since:
      100.9.0
      See Also:

    • isUseCourseSymbolOnMovement

      public boolean isUseCourseSymbolOnMovement()
      Indicates if the getCourseSymbol() is used to display current location, when the location updates indicate the device is moving.

      If no course information is available, the default symbol will be used instead. The course symbol is rotated in order to indicate the device's direction of travel.

      Generally, course information is only available if the device is actively moving (the location has a positive speed).

      Returns:
      true if the course symbol is used when the device is moving; false if the default symbol is used
      Since:
      100.9.0

    • setCourseSymbol

      public void setCourseSymbol(Symbol courseSymbol)
      Sets the symbol used to display the current location and the course (direction of travel) when moving.

      This symbol rotates with the heading of the movement. If course information is not available (for example if the device is not moving), the getDefaultSymbol() is used.

      Parameters:
      courseSymbol - the new symbol to be used to display current location and course
      Throws:
      IllegalArgumentException - if courseSymbol is null
      Since:
      100.9.0

    • getCourseSymbol

      public Symbol getCourseSymbol()
      Gets the symbol used to display the current location and the course (direction of travel) when moving.

      This symbol rotates with the heading of the movement. If course information is not available (for example if the device is not moving), the getDefaultSymbol() is used.

      Returns:
      the symbol used to display current location and course
      Since:
      100.9.0

    • setHeadingSymbol

      public void setHeadingSymbol(Symbol headingSymbol)
      Sets the symbol used for the location when the auto-pan mode is LocationDisplay.AutoPanMode.COMPASS_NAVIGATION.

      The symbol is rotated to match with the heading of the compass. If there is no heading information (for example, if the device does not have a compass sensor), the getDefaultSymbol() is used.

      When setting a new heading symbol, ensure that it indicates a direction - for example, depicts an arrow. When not rotated, the arrow should point directly upwards.

      Parameters:
      headingSymbol - the symbol used to display current location and heading in COMPASS_NAVIGATION mode
      Throws:
      IllegalArgumentException - if headingSymbol is null
      Since:
      100.9.0

    • getHeadingSymbol

      public Symbol getHeadingSymbol()
      Gets the symbol used for the location when the auto-pan mode is LocationDisplay.AutoPanMode.COMPASS_NAVIGATION.

      The symbol is rotated to match with the heading of the compass. If there is no heading information (for example, if the device does not have a compass sensor), the getDefaultSymbol() is used.

      Returns:
      the symbol used to display current location and heading in COMPASS_NAVIGATION mode
      Since:
      100.9.0

    • setShowLocation

      public void setShowLocation(boolean enable)
      Sets whether the location symbol is displayed when the LocationDisplay has been started.

      Passing in false means that the LocationDisplay will continue to receive updates, but no location symbol will be shown on the map.

      Parameters:
      enable - true to display the location symbol in the map; false otherwise
      Since:
      100.9.0
      See Also:

    • isShowLocation

      public boolean isShowLocation()
      Indicates whether the location symbol is displayed when the LocationDisplay has been started. When false, none of the location symbols (getDefaultSymbol(), getCourseSymbol(), getHeadingSymbol(), or getAcquiringSymbol()) will be displayed.

      This method does not affect the display of getPingAnimationSymbol() or getAccuracySymbol(); these symbols can be disabled individually using setShowPingAnimation(boolean) and setShowAccuracy(boolean).

      Returns:
      true if location symbols are displayed in the map; false otherwise
      Since:
      100.9.0

    • addAutoPanModeChangedListener

      public void addAutoPanModeChangedListener(LocationDisplay.AutoPanModeChangedListener autoPanModeChangedListener)
      Registers the given AutoPanModeChangedListener to be called when the setAutoPanMode(LocationDisplay.AutoPanMode) is changed.

      If the visible map extent is changed by the user navigating the map interactively, or by a programmatic navigation method, this will cause AutoPanMode to be reset to OFF. You can respond to this event if your app needs to revert to the previously set mode after that navigation has finished.

      Adding this listener on the UI thread will cause it to be invoked on the UI thread, otherwise it is not guaranteed on which thread the listener is invoked.

      Parameters:
      autoPanModeChangedListener - the listener to register
      Throws:
      IllegalArgumentException - if the autoPanModeChangedListener is null
      Since:
      100.9.0
      See Also:

    • removeAutoPanModeChangedListener

      public boolean removeAutoPanModeChangedListener(LocationDisplay.AutoPanModeChangedListener autoPanModeChangedListener)
      Unregisters the given AutoPanModeChangedListener that was previously added using addAutoPanModeChangedListener(LocationDisplay.AutoPanModeChangedListener).
      Parameters:
      autoPanModeChangedListener - the listener to unregister
      Returns:
      true if the listener was successfully removed; false otherwise
      Throws:
      IllegalArgumentException - if the autoPanModeChangedListener is null
      Since:
      100.9.0

    • addLocationChangedListener

      public void addLocationChangedListener(LocationDisplay.LocationChangedListener locationChangedListener)
      Registers the given LocationChangedListener to be called when a location update is received from the LocationDataSource.

      Location updates are only received when isStarted() is true.

      Adding this listener on the UI thread will cause it to be invoked on the UI thread, otherwise it is not guaranteed on which thread the listener is invoked.

      Parameters:
      locationChangedListener - the listener to register
      Throws:
      IllegalArgumentException - if the locationChangedListener is null
      Since:
      100.9.0
      See Also:

    • removeLocationChangedListener

      public boolean removeLocationChangedListener(LocationDisplay.LocationChangedListener locationChangedListener)
      Unregisters the given LocationChangedListener that was previously added using addLocationChangedListener(LocationChangedListener).
      Parameters:
      locationChangedListener - the listener to unregister
      Returns:
      true if the listener was successfully removed; false otherwise
      Throws:
      IllegalArgumentException - if the locationChangedListener is null
      Since:
      100.9.0

    • addDataSourceStatusChangedListener

      public void addDataSourceStatusChangedListener(LocationDisplay.DataSourceStatusChangedListener dataSourceStatusChangedListener)
      Registers the given DataSourceStatusChangedListener to be called when the status of the LocationDataSource changes - when the LocationDisplay has been started or stopped.

      Adding this listener on the UI thread will cause it to be invoked on the UI thread, otherwise it is not guaranteed on which thread the listener is invoked.

      Parameters:
      dataSourceStatusChangedListener - the listener to register
      Throws:
      IllegalArgumentException - if the dataSourceStatusChangeListener is null
      Since:
      100.9.0
      See Also:

    • removeDataSourceStatusChangedListener

      public boolean removeDataSourceStatusChangedListener(LocationDisplay.DataSourceStatusChangedListener dataSourceStatusChangedListener)
      Unregisters the given DataSourceStatusChangedListener that was previously added using addDataSourceStatusChangedListener(DataSourceStatusChangedListener).
      Parameters:
      dataSourceStatusChangedListener - the listener to unregister
      Returns:
      true if the listener was successfully removed; false otherwise
      Throws:
      IllegalArgumentException - if the dataSourceStatusChangedListener is null
      Since:
      100.9.0

    • startAsync

      public final void startAsync()
      Asynchronously starts the LocationDataSource of this LocationDisplay, to begin receiving location updates. As the updates are received they will be displayed on the map. This is a convenience method that calls LocationDataSource.startAsync().

      To be notified when the LocationDataSource has started, use the addDataSourceStatusChangedListener(DataSourceStatusChangedListener) method. Calling start on a LocationDisplay that has previously failed to start will attempt to start it again.

      Since:
      100.9.0
      See Also:

    • stop

      public final void stop()
      Stops the LocationDataSource of this LocationDisplay from receiving location updates. Location updates will no longer be received, and location symbols will no longer be displayed on the map.
      Since:
      100.9.0
      See Also:

    • isStarted

      public final boolean isStarted()
      Indicates if the location display is currently active, that is, has been successfully started.

      To be notified when the LocationDataSource starts or stops, use the addDataSourceStatusChangedListener(DataSourceStatusChangedListener) method.

      Returns:
      true if the LocationDataSource is active; false otherwise
      Since:
      100.9.0