Package com.esri.arcgisruntime.mapping.view

Class LocationDisplay

  • public final class LocationDisplay
extends 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.

    You do not instantiate LocationDisplay directly; instead, retrieve it from MapView.getLocationDisplay(). To start receiving location updates, and display the current location from a location data source, 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.

    Location information is retrieved and updated via the LocationDataSource.

    Instances of LocationDisplay and LocationDataSource are not shared by multiple MapViews, and therefore each location display can be started and stopped independently on multiple MapViews without affecting each other.

    Since:
    100.9.0

    • Method Detail

      • setLocationDataSource

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

      • getLocationDataSource

        public LocationDataSource getLocationDataSource()
        Returns the LocationDataSource for this LocationDisplay.
        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 (the direction the device is pointing) in degrees relative to north.
        Returns:
        the heading angle, in degrees clockwise, relative from north
        Since:
        100.9.0

      • setDefaultSymbol

        public void setDefaultSymbol​(Symbol defaultSymbol)
        Sets the default symbol used to display current location.

        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 default symbol used to display current location.
        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.
        Returns:
        the symbol animated to indicate location updates
        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 indicate an approximate area of location horizontal accuracy. To turn this symbol off or on, use setShowAccuracy(boolean).
        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 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.9.0

      • setAcquiringSymbol

        public void setAcquiringSymbol​(Symbol acquiringSymbol)
        Sets the symbol used to display the last known location, while location is being acquired.
        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 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 symbol used when location is being acquired
        Since:
        100.9.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 behavior, 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 call this method to set the mode, and then call the startAsync() method.

        Parameters:
        autoPanMode - the new AutoPanMode
        Throws:
        IllegalArgumentException - if autoPanMode is null
        Since:
        100.9.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(LocationDisplay.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:
        IllegalArgumentException - if initialZoomScale is less than 0
        Since:
        100.9.0
        See Also:
        setAutoPanMode(LocationDisplay.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.9.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 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 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:
        IllegalArgumentException - if wanderExtentFactor is less than 0.0 or greater than 1.0
        Since:
        100.9.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.9.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.

        If set to false, or the location updates indicate the device is stationary, then the default symbol 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.9.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.

        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.9.0

      • setCourseSymbol

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

        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 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).

        If course information is not available (for example if device is not moving), getDefaultSymbol() will be used instead.

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

      • setHeadingSymbol

        public void setHeadingSymbol​(Symbol headingSymbol)
        Sets the symbol used to display current location, rotated to indicate the getHeading() (direction of device orientation).

        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 to display current location, rotated to indicate the getHeading() (direction of device orientation).

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

        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(), isShowAccuracy(), isShowPingAnimation()

      • 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. 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:
        IllegalArgumentException - if the autoPanModeChangedListener is null
        Since:
        100.9.0
        See Also:
        removeAutoPanModeChangedListener(LocationDisplay.AutoPanModeChangedListener)

      • 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:
        IllegalArgumentException - if the locationChangedListener is null
        Since:
        100.9.0
        See Also:
        removeLocationChangedListener(LocationChangedListener)

      • 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(DataSourceStatusChangedListener)

      • 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()

      • 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:
        startAsync()