Package com.esri.arcgisruntime.mapping.view

Class LocationDisplay

  • public final class LocationDisplay
extends java.lang.Object
    Manages display of current location in a MapView. It controls the symbology used to indicate the current location on the map, setting the viewpoint of the map when location is received, and automatic panning and rotating of the map when the current location, heading, or course changes.

    To use this class, the app must be granted Location permissions in the Android platform settings.

    You do not instantiate LocationDisplay directly; instead, retrieve it from MapView.getLocationDisplay(). To start receiving location updates, and display the device location, call startAsync(). By default, a round, blue symbol is used to display the device's location. Use stop() and startAsync() respectively to stop and start receiving updates when the app switches between background and foreground processes.

    As the device moves and new location updates are received, the location symbol will be repositioned on the map. Depending on the current LocationDisplay.AutoPanMode, the map may pan and rotate when the location changes. By default, the AutoPanMode is OFF, and the map does not automatically pan to keep the current location within the maps viewpoint.

    Different pan modes are available, each being appropriate for a specific type of map use; to automatically pan the map to re-center at the current location, use LocationDisplay.AutoPanMode.RECENTER. Alternative modes are available to suit apps that give compass directions (LocationDisplay.AutoPanMode.COMPASS_NAVIGATION, or help a user navigate along a route, typically when driving LocationDisplay.AutoPanMode.NAVIGATION. For example, to start the LocationDisplay in NAVIGATION mode, use code like this: 

    locationDisplay = mapView.getLocationDisplay();
 locationDisplay.setAutoPanMode(LocationDisplay.AutoPanMode.NAVIGATION);
 locationDisplay.startAsync();

    The symbol used (either getDefaultSymbol(), getHeadingSymbol(), or getCourseSymbol()) to indicate current location depends on both the current LocationDisplay.AutoPanMode, and whether heading (device direction of orientation) and course (device direction of travel) information is available from the LocationDataSource. Various methods are available to customize the location display, including the symbols used to indicate the current location, heading, and course, and the symbols used to indicate accuracy and highlight when location updates are received.

    Location information is retrieved and updated via the LocationDataSource. The default LocationDataSource will try to get the most accurate location available, but depending upon signal strength, satellite positions, and other factors, the location reported could be a best possible approximation; a semi-transparent circle around the location symbol indicates the range of accuracy.

    Instances of LocationDisplay and LocationDataSource are not shared as by multiple MapViews, and therefore each location display can be started and stopped independently on multiple MapViews without affecting each other. However, since the LocationDataSources by default are based on the platform location service, each will receive identical location updates from the platform.

    Since:
    100.0.0

    • Method Detail

      • setLocationDataSource

        public void setLocationDataSource​(LocationDataSource locationDataSource)
        Sets a new LocationDataSource for this LocationDisplay.
        Parameters:
        locationDataSource - A LocationDataSource object
        Throws:
        java.lang.IllegalArgumentException - if locationDataSource is null
        Since:
        100.0.0

      • getLocationDataSource

        public LocationDataSource getLocationDataSource()
        Returns the LocationDataSource for this LocationDisplay. By default, this is an AndroidLocationDataSource.
        Returns:
        the LocationDataSource object, or null if it has not yet been set
        Since:
        100.0.0

      • setAutoPanMode

        public void setAutoPanMode​(LocationDisplay.AutoPanMode autoPanMode)
        Sets the LocationDisplay.AutoPanMode for the LocationDisplay that affects the symbols used to display device location, the initial zooming behaviour, and the panning behavior of the MapView. Different modes are designed for different types of app, including modes designed for navigation on foot and in a vehicle.

        To start the LocationDisplay in a specific mode, first set call this method to set the mode, and then call the startAsync() method.

        Parameters:
        autoPanMode - the new AutoPanMode
        Since:
        100.0.0
        See Also:
        setInitialZoomScale(double)

      • setInitialZoomScale

        public void setInitialZoomScale​(double initialZoomScale)
        Sets the initial map scale to which the MapView will zoom in when the first location update is received, unless the AutoPanMode is OFF. The map will also zoom in to this scale if setAutoPanMode(AutoPanMode) is called after the LocationDisplay was started; for example, if re-setting the AutoPanMode after it has been turned off by interactive user navigation.
        Parameters:
        initialZoomScale - the denominator value of a map scale, the default value is 10,000. Values smaller than the current map scale when update is received will be ignored. Pass in NaN to prevent this initial zooming behavior entirely.
        Throws:
        java.lang.IllegalArgumentException - if initialZoomScale is less than 0
        Since:
        100.0.0
        See Also:
        setAutoPanMode(AutoPanMode)

      • getInitialZoomScale

        public double getInitialZoomScale()
        Gets the initial map scale to which the MapView will zoom when the first location update is received after AutoPanMode is changed from OFF to any other value. The default value is 10,000.

        Zooming only occurs if:

        • current map scale is larger than the initial zoom scale (e.g. the map will zoom in)
        • getAutoPanMode() is is not LocationDisplay.AutoPanMode.OFF (e.g. the mode indicates that the map is expected to update it's Viewpoint in response to a location update)
        • initial zoom scale is greater than 0
        Returns:
        the map scale to zoom to when first location update is received
        Since:
        100.0.0
        See Also:
        MapView.getMapScale()

      • 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. 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.0.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. 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:
        java.lang.IllegalArgumentException - if navigationPointHeightFactor is less than 0.0 or greater than 1.0
        Since:
        100.0.0

      • setWanderExtentFactor

        public void setWanderExtentFactor​(float wanderExtentFactor)
        Sets the factor of map extent within which the location symbol may move before causing auto-panning to re-center the map on the current location. Applies only to LocationDisplay.AutoPanMode.RECENTER mode.

        Permitted values are between 1 (indicating the symbol may move within the current extent of the MapView without causing re-centering), and 0 (indicating that any location movement will re-center the map). 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:
        java.lang.IllegalArgumentException - if wanderExtentFactor is less than 0.0 or greater than 1.0
        Since:
        100.0.0

      • getWanderExtentFactor

        public float getWanderExtentFactor()
        Gets the factor of map extent within which the location symbol may move before causing auto-panning to re-center the map on the current location. Applies only to LocationDisplay.AutoPanMode.RECENTER mode. The default value is 0.5, indicating the location may wander up to half of the extent before re-centering occurs.
        Returns:
        the new factor of map extent within which the current location may move before the map is re-centered
        Since:
        100.0.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.0.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.0.0

      • getHeading

        public double getHeading()
        Gets the heading angle (the direction the device is pointing) in degrees relative to north. If AndroidLocationDataSource is set, a value of 0.0 indicates the device is pointed toward true north, a value of 90.0 indicates due east, 180 indicates due south,and so on. A NaN value indicates that the heading could not be determined. The heading is determined by the current getLocationDataSource().

        Heading information is retrieved by using system sensors such as the accelerometer or magnetic field compass.

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

      • setUseCourseSymbolOnMovement

        public void setUseCourseSymbolOnMovement​(boolean useCourseSymbolOnMovement)
        Sets whether the course symbol should be used, indicating the direction of travel, when the location updates indicate the device is moving. This symbol does not apply to LocationDisplay.AutoPanMode.COMPASS_NAVIGATION mode.

        If set to false, or the location updates indicate the device is stationary, then getDefaultSymbol() will be used to display the current location instead.

        Parameters:
        useCourseSymbolOnMovement - true to use the course symbol to display the location; false to use the default symbol
        Since:
        100.0.0
        See Also:
        isUseCourseSymbolOnMovement()

      • isUseCourseSymbolOnMovement

        public boolean isUseCourseSymbolOnMovement()
        Indicates if the course symbol is used to display current location, when location updates indicate the device is moving. If no course information is available, the default symbol will be used instead. The getCourseSymbol() is rotated in order to indicate both the device location and it's direction of travel. Does not apply to LocationDisplay.AutoPanMode.COMPASS_NAVIGATION mode.

        Generally, course information is only available if the device is actively moving (i.e. the location has a positive speed); course information may also be available from mock location sources.

        Returns:
        true if the course symbol is used when the device is moving; false if the default symbol is used
        Since:
        100.0.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:
        java.lang.IllegalArgumentException - if opacity is less than 0.0 or greater than 1.0
        Since:
        100.0.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.0.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.0.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.0.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.0.0

      • setAccuracySymbol

        public void setAccuracySymbol​(Symbol accuracySymbol)
        Sets the fill symbol used to indicate an approximate area of location horizontal accuracy. To turn this symbol off or on, use isShowAccuracy().
        Parameters:
        accuracySymbol - the new fill symbol to be used to display location horizontal accuracy
        Throws:
        java.lang.IllegalArgumentException - if accuracySymbol is null
        Since:
        100.0.0

      • getAccuracySymbol

        public Symbol getAccuracySymbol()
        Gets the fill symbol used to indicate an approximate area of location horizontal accuracy, if isShowAccuracy() is true. The default symbol is a blue outline with a semi-transparent white fill.
        Returns:
        accuracySymbol the symbol used to represent location accuracy
        Since:
        100.0.0

      • setAcquiringSymbol

        public void setAcquiringSymbol​(Symbol acquiringSymbol)
        Sets the marker symbol used to display the last known location, while location is being acquired.
        Parameters:
        acquiringSymbol - the new marker symbol to be used when location is being acquired
        Throws:
        java.lang.IllegalArgumentException - if acquiringSymbol is null
        Since:
        100.0.0

      • getAcquiringSymbol

        public Symbol getAcquiringSymbol()
        Gets the marker symbol used to display the last known location, while location is being acquired. The default symbol is a grey circle. This symbol may be used immediately after starting the LocationDisplay. Once an up to date location is acquired, the getDefaultSymbol(), getCourseSymbol(), or getHeadingSymbol() will be used instead, depending on the current settings of the LocationDisplay.
        Returns:
        acquiringSymbol the marker symbol used when location is being acquired
        Since:
        100.0.0

      • setDefaultSymbol

        public void setDefaultSymbol​(Symbol defaultSymbol)
        Sets the default marker symbol used to display current location. This symbol is used in all AutoPan modes when the location updates do not contain course (direction of travel) and heading (direction the device is pointing) information.

        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 marker symbol to be used to display current location
        Throws:
        java.lang.IllegalArgumentException - if defaultSymbol is null
        Since:
        100.0.0

      • getDefaultSymbol

        public Symbol getDefaultSymbol()
        Gets the default marker symbol used to display current location. This symbol is used in all AutoPanModes when the location updates do not contain course (direction of travel) and heading (direction the device is pointing) information.

        If position and course information are available, and the AutoPanMode is OFF, RECENTER, or NAVIGATION, getCourseSymbol() will be used instead. If position and heading information are available, and the AutoPanMode is COMPASS_NAVIGATION, getHeadingSymbol() will be used instead.

        Returns:
        the marker symbol used to display current location
        Since:
        100.0.0

      • setPingAnimationSymbol

        public void setPingAnimationSymbol​(Symbol pingAnimationSymbol)
        Sets the marker 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 symbol as the ping animation symbol, and the LocationDisplay will take care of the animation.

        Parameters:
        pingAnimationSymbol - the new marker symbol that will be animated to indicate location updates
        Throws:
        java.lang.IllegalArgumentException - if pingAnimationSymbol is null
        Since:
        100.0.0

      • getPingAnimationSymbol

        public Symbol getPingAnimationSymbol()
        Gets the marker symbol animated around the location symbol, to indicate when location updates are received. Only applies if isShowPingAnimation() is true. Default symbol is a circle with a blue outline.
        Returns:
        the marker symbol animated to indicate location updates
        Since:
        100.0.0

      • setCourseSymbol

        public void setCourseSymbol​(Symbol courseSymbol)
        Sets the marker symbol used to display current location, rotated to indicate the course (direction of travel). This symbol is used in OFF, RECENTER, and NAVIGATION AutoPanModes when the location updates contain position and course information, and isUseCourseSymbolOnMovement() is true.

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

        Parameters:
        courseSymbol - the new marker symbol to be used to display current location and course
        Throws:
        java.lang.IllegalArgumentException - if courseSymbol is null
        Since:
        100.0.0

      • getCourseSymbol

        public Symbol getCourseSymbol()
        Gets the marker symbol used to display current location, rotated to indicate the course (direction of travel). This symbol is used in OFF, RECENTER, and NAVIGATION AutoPanModes when the location updates contain position and course information, and isUseCourseSymbolOnMovement() is true.

        If course information is not available (for example if device is not moving), getDefaultSymbol() will be used instead. This symbol is never used in LocationDisplay.AutoPanMode.COMPASS_NAVIGATION.

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

      • setHeadingSymbol

        public void setHeadingSymbol​(Symbol headingSymbol)
        Sets the marker symbol used to display current location, rotated to indicate the getHeading() (direction of device orientation). This symbol is only used in LocationDisplay.AutoPanMode.COMPASS_NAVIGATION, when the location updates contain position and heading.

        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 marker symbol used to display current location and heading in COMPASS_NAVIGATION mode
        Throws:
        java.lang.IllegalArgumentException - if headingSymbol is null
        Since:
        100.0.0

      • getHeadingSymbol

        public Symbol getHeadingSymbol()
        Gets the marker symbol used to display current location, rotated to indicate the getHeading() (direction of device orientation). This symbol is only used in LocationDisplay.AutoPanMode.COMPASS_NAVIGATION mode, when the location updates contain position and heading.

        If heading information is not available (for example if the device does not have a compass sensor), getDefaultSymbol() will be used instead.

        Returns:
        the marker symbol used to display current location and heading in COMPASS_NAVIGATION mode
        Since:
        100.0.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. The AutoPanMode is not affected by this method; if in RECENTER, COMPASS_NAVIGATION or NAVIGATION modes, the map will continue to automatically pan to the location, despite the location not being shown.

        Parameters:
        enable - true to display the location symbol in the map; false otherwise
        Since:
        100.0.0
        See Also:
        isShowLocation(), isShowAccuracy(), isShowPingAnimation()

      • 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 received when the LocationDisplay isStarted().

        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:
        java.lang.IllegalArgumentException - if the locationChangedListener is null
        Since:
        100.0.0
        See Also:
        removeLocationChangedListener(LocationChangedListener)

      • 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:
        java.lang.IllegalArgumentException - if the locationChangedListener is null
        Since:
        100.0.0

      • addAutoPanModeChangedListener

        public void addAutoPanModeChangedListener​(LocationDisplay.AutoPanModeChangedListener autoPanModeChangedListener)
        Registers the given AutoPanModeChangedListener to be called when the setAutoPanMode(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. Use this method to set a listener if you want to re-set the AutoPanMode if it is reset to OFF in this way.

        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:
        java.lang.IllegalArgumentException - if the autoPanModeChangedListener is null
        Since:
        100.0.0
        See Also:
        removeAutoPanModeChangedListener(AutoPanModeChangedListener)

      • removeAutoPanModeChangedListener

        public boolean removeAutoPanModeChangedListener​(LocationDisplay.AutoPanModeChangedListener autoPanModeChangedListener)
        Unregisters the given AutoPanModeChangedListener that was previously added using addAutoPanModeChangedListener(AutoPanModeChangedListener).
        Parameters:
        autoPanModeChangedListener - the listener to unregister
        Returns:
        true if the listener was successfully removed; false otherwise
        Throws:
        java.lang.IllegalArgumentException - if the autoPanModeChangedListener is null
        Since:
        100.0.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:
        java.lang.IllegalArgumentException - if the dataSourceStatusChangeListener is null
        Since:
        100.0.0
        See Also:
        removeDataSourceStatusChangedListener(DataSourceStatusChangedListener)

      • 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:
        java.lang.IllegalArgumentException - if the dataSourceStatusChangedListener is null
        Since:
        100.0.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(). If no LocationDataSource is set, an AndroidLocationDataSource will be created and set onto this LocationDisplay, and then started.

        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; use this workflow if the LocationDisplay has previously failed to start because the user had not granted app permissions for location services.

        Since:
        100.0.0
        See Also:
        stop()

      • 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. This is a convenience method that calls LocationDataSource.stopAsync().
        Since:
        100.0.0
        See Also:
        startAsync()