LocationDisplay Class

  • LocationDisplay
  • class Esri::ArcGISRuntime::LocationDisplay

    Manages the display of a device's location in a MapView. More...

    Header: #include <LocationDisplay.h>
    Since: Esri::ArcGISRuntime 100.0
    Inherits: Esri::ArcGISRuntime::Object

    Public Functions

    virtual ~LocationDisplay() override
    Esri::ArcGISRuntime::Symbol *accuracySymbol() const
    Esri::ArcGISRuntime::Symbol *acquiringSymbol() const
    int acquiringTimeout() const
    Esri::ArcGISRuntime::LocationDisplayAutoPanMode autoPanMode() const
    Esri::ArcGISRuntime::Symbol *courseSymbol() const
    Esri::ArcGISRuntime::AbstractLocationDataSource *dataSource() const
    Esri::ArcGISRuntime::Symbol *defaultSymbol() const
    double heading() const
    Esri::ArcGISRuntime::Symbol *headingSymbol() const
    double initialZoomScale() const
    bool isShowAccuracy() const
    bool isShowLocation() const
    bool isShowPingAnimationSymbol() const
    bool isStarted() const
    bool isUseCourseSymbolOnMovement() const
    Esri::ArcGISRuntime::Location location() const
    Esri::ArcGISRuntime::Point mapLocation() const
    float navigationPointHeightFactor() const
    float opacity() const
    Esri::ArcGISRuntime::Symbol *pingAnimationSymbol() const
    void setAccuracySymbol(Esri::ArcGISRuntime::Symbol *accuracySymbol)
    void setAcquiringSymbol(Esri::ArcGISRuntime::Symbol *acquiringSymbol)
    void setAcquiringTimeout(int timeoutMilliseconds)
    void setAutoPanMode(Esri::ArcGISRuntime::LocationDisplayAutoPanMode autoPanMode)
    void setCourseSymbol(Esri::ArcGISRuntime::Symbol *courseSymbol)
    void setDataSource(Esri::ArcGISRuntime::AbstractLocationDataSource *dataSource)
    void setDefaultSymbol(Esri::ArcGISRuntime::Symbol *defaultSymbol)
    void setHeadingSymbol(Esri::ArcGISRuntime::Symbol *headingSymbol)
    void setInitialZoomScale(double initialScale)
    void setNavigationPointHeightFactor(float pointHeightFactor)
    void setOpacity(float opacity)
    void setPingAnimationSymbol(Esri::ArcGISRuntime::Symbol *pingSymbol)
    void setShowAccuracy(bool enable)
    void setShowLocation(bool enable)
    void setShowPingAnimationSymbol(bool enable)
    void setUseCourseSymbolOnMovement(bool enable)
    void setWanderExtentFactor(float wanderFactor)
    void start()
    void stop()
    float wanderExtentFactor() const

    Signals

    void autoPanModeChanged(Esri::ArcGISRuntime::LocationDisplayAutoPanMode autoPanMode)
    void headingChanged()
    void locationChanged(const Esri::ArcGISRuntime::Location &location)
    void statusChanged(bool started)

    Detailed Description

    Location display can retrieve the device's current location from a AbstractLocationDataSource and display it on top of a Map. 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 AbstractLocationDataSource. 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, an indoor positioning system (IPS), 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 (accuracySymbol) around the location symbol indicates the estimated range of accuracy for the current location. As locations are read from the configured AbstractLocationDataSource, 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.

    Example:

    Show your current location on a map with the location display:

    // turn on the location display
    m_mapView->locationDisplay()->start();

    See also MapView::locationDisplay, Location, QGeoPositionInfoSource, and QCompass.

    Member Function Documentation

    [override virtual] LocationDisplay::~LocationDisplay()

    Destructor.

    Esri::ArcGISRuntime::Symbol *LocationDisplay::accuracySymbol() const

    Returns a 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 AbstractLocationDataSource, increases or decreases.

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

    See also setAccuracySymbol().

    Esri::ArcGISRuntime::Symbol *LocationDisplay::acquiringSymbol() const

    Returns 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 defaultSymbol, courseSymbol, or headingSymbol is used, depending on the current settings of the LocationDisplay. The default symbol is a grey circle.

    See also setAcquiringSymbol().

    int LocationDisplay::acquiringTimeout() const

    The time in milliseconds between the last valid position update and displaying the acquiring symbol.

    See also setAcquiringTimeout().

    Esri::ArcGISRuntime::LocationDisplayAutoPanMode LocationDisplay::autoPanMode() const

    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 wanderExtentFactor.
    • 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 AbstractLocationDataSource.

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

    The default auto-pan mode is LocationDisplayAutoPanMode::Off.

    See also setAutoPanMode() and LocationDisplayAutoPanMode.

    [signal] void LocationDisplay::autoPanModeChanged(Esri::ArcGISRuntime::LocationDisplayAutoPanMode autoPanMode)

    Emitted when the auto pan mode changes.

    • autoPanMode - The auto pan mode.

    Esri::ArcGISRuntime::Symbol *LocationDisplay::courseSymbol() const

    Returns 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 defaultSymbol is used.

    See also setCourseSymbol().

    [since Esri::ArcGISRuntime 100.8] Esri::ArcGISRuntime::AbstractLocationDataSource *LocationDisplay::dataSource() const

    Returns 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:

    This function was introduced in Esri::ArcGISRuntime 100.8.

    See also setDataSource().

    Esri::ArcGISRuntime::Symbol *LocationDisplay::defaultSymbol() const

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

    See also setDefaultSymbol().

    double LocationDisplay::heading() const

    Returns the heading angle of the current location in degrees relative to north.

    This is only applicable when the auto-pan mode is LocationDisplayAutoPanMode::CompassNavigation. 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.

    [signal] void LocationDisplay::headingChanged()

    Emitted when the heading changes.

    Esri::ArcGISRuntime::Symbol *LocationDisplay::headingSymbol() const

    Returns the symbol used for the location when the auto-pan mode is LocationDisplayAutoPanMode::CompassNavigation.

    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 defaultSymbol is used.

    See also setHeadingSymbol().

    double LocationDisplay::initialZoomScale() const

    Returns 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 LocationDisplayAutoPanMode::Off to any other value. The default value is 10,000.

    See also setInitialZoomScale().

    bool LocationDisplay::isShowAccuracy() const

    Returns true if the accuracySymbol is shown, false otherwise.

    bool LocationDisplay::isShowLocation() const

    Returns true if location symbols are shown, false otherwise.

    bool LocationDisplay::isShowPingAnimationSymbol() const

    Returns true if the pingAnimationSymbol is shown, false otherwise.

    bool LocationDisplay::isStarted() const

    Returns true if the location display is currently active (the AbstractLocationDataSource has been started), false otherwise.

    bool LocationDisplay::isUseCourseSymbolOnMovement() const

    Returns true if the courseSymbol is used to display current location, when the location updates indicate the device is moving, false otherwise.

    If no course information is available, the default symbol will be used instead. The courseSymbol 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).

    Esri::ArcGISRuntime::Location LocationDisplay::location() const

    Returns the most recent location reported by the location data source.

    The Location provides data for the single location, including position, course, velocity, and accuracy.

    [signal] void LocationDisplay::locationChanged(const Esri::ArcGISRuntime::Location &location)

    Emitted when the location changes.

    • location - The most recent Location update.

    Esri::ArcGISRuntime::Point LocationDisplay::mapLocation() const

    Returns the map position of the most recent location reported by the location data source in the projection of the current map view.

    Returns the navigation point height factor. The factor will decide the location symbol position vertically from the bottom of the map when the auto-pan mode is LocationDisplayAutoPanMode::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.

    See also setNavigationPointHeightFactor().

    float LocationDisplay::opacity() const

    Returns the opacity value of all symbols displayed by the LocationDisplay. The value should be between 0 and 1.

    See also setOpacity().

    Esri::ArcGISRuntime::Symbol *LocationDisplay::pingAnimationSymbol() const

    Returns the symbol that will be animated around the location symbol, to indicate when location updates are received.

    Location update animations are only shown when isShowPingAnimationSymbol is true.

    See also setPingAnimationSymbol().

    void LocationDisplay::setAccuracySymbol(Esri::ArcGISRuntime::Symbol *accuracySymbol)

    Sets the accuracySymbol to accuracySymbol.

    See also accuracySymbol.

    void LocationDisplay::setAcquiringSymbol(Esri::ArcGISRuntime::Symbol *acquiringSymbol)

    Sets the acquiringSymbol to acquiringSymbol.

    See also acquiringSymbol.

    void LocationDisplay::setAcquiringTimeout(int timeoutMilliseconds)

    Sets the acquiring symbol timeout to timeoutMilliseconds.

    The default timeout is 5 seconds. If the acquiringTimeout is passed, the location symbol will change to display the location acquiring symbol (which is gray in color).

    See also acquiringTimeout().

    void LocationDisplay::setAutoPanMode(Esri::ArcGISRuntime::LocationDisplayAutoPanMode autoPanMode)

    Sets the autoPanMode to autoPanMode.

    See also autoPanMode.

    void LocationDisplay::setCourseSymbol(Esri::ArcGISRuntime::Symbol *courseSymbol)

    Sets the courseSymbol to courseSymbol.

    See also courseSymbol.

    [since Esri::ArcGISRuntime 100.8] void LocationDisplay::setDataSource(Esri::ArcGISRuntime::AbstractLocationDataSource *dataSource)

    Sets the dataSource to dataSource.

    This function was introduced in Esri::ArcGISRuntime 100.8.

    See also dataSource.

    void LocationDisplay::setDefaultSymbol(Esri::ArcGISRuntime::Symbol *defaultSymbol)

    Sets the defaultSymbol to defaultSymbol.

    See also defaultSymbol.

    void LocationDisplay::setHeadingSymbol(Esri::ArcGISRuntime::Symbol *headingSymbol)

    Sets the headingSymbol to headingSymbol.

    See also headingSymbol.

    void LocationDisplay::setInitialZoomScale(double initialScale)

    Sets the initialZoomScale to initialScale.

    See also initialZoomScale.

    void LocationDisplay::setNavigationPointHeightFactor(float pointHeightFactor)

    Sets the navigationPointHeightFactor to pointHeightFactor.

    See also navigationPointHeightFactor.

    void LocationDisplay::setOpacity(float opacity)

    Sets the opacity to opacity.

    See also opacity.

    void LocationDisplay::setPingAnimationSymbol(Esri::ArcGISRuntime::Symbol *pingSymbol)

    Sets the pingAnimationSymbol to pingSymbol.

    See also pingAnimationSymbol.

    void LocationDisplay::setShowAccuracy(bool enable)

    Sets the showAccuracy to enable.

    See also isShowAccuracy.

    void LocationDisplay::setShowLocation(bool enable)

    Sets the showLocation to enable.

    See also isShowLocation.

    void LocationDisplay::setShowPingAnimationSymbol(bool enable)

    Sets the showPingAnimationSymbol to enable.

    See also isShowPingAnimationSymbol.

    void LocationDisplay::setUseCourseSymbolOnMovement(bool enable)

    Sets the useCourseSymbolOnMovement to enable.

    See also isUseCourseSymbolOnMovement.

    void LocationDisplay::setWanderExtentFactor(float wanderFactor)

    Sets the wanderExtentFactor to wanderFactor.

    See also wanderExtentFactor.

    void LocationDisplay::start()

    Starts the LocationDisplay on the MapView.

    If a location data source is not explicitly set, a DefaultLocationDataSource will be assigned and started. If you attempt to start location display on a instance that is already started, it will complete without attempting to start it again. There is no need to check if it is started before calling start. If a user had previously denied the app access to location services, calling start again will again attempt to start.

    [signal] void LocationDisplay::statusChanged(bool started)

    Emitted when the status changes.

    void LocationDisplay::stop()

    Stops the LocationDisplay on the MapView.

    Calling stop on the LocationDisplay will automatically attempt to stop its location data source.

    float LocationDisplay::wanderExtentFactor() const

    Returns the wander extent factor controls the re-centering behavior of the MapView when the location changes.

    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 LocationDisplayAutoPanMode::Recenter. Lower values within this range will cause the map to re-center more often, leading to higher CPU and battery consumption.

    See also setWanderExtentFactor().

    Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.