Display device location

Learn how to display the current device location on a map or scene.

display device location

You can display the device location on a map or scene. This is important for workflows that require the user's current location, such as finding nearby businesses, navigating from the current location, or identifying and collecting geospatial information.

By default, location display uses the device's location provider. Your app can also process input from other location providers, such as an external GPS receiver or a provider that returns a simulated location. For more information, see the Show device location topic.

Prerequisites

The following are required for this tutorial:

  1. An ArcGIS account to access API keys. If you don't have an account, sign up for free.
  2. Your system meets the system requirements.
  3. The ArcGIS Runtime API for Qt is installed.

Steps

Create a new ArcGIS Runtime Qt Creator Project

  1. Launch Qt Creator and create a new project. Under Choose a Template, select Qt Quick C++ app project for the latest version of ArcGIS Runtime installed.

  2. Name your project display_device_location.

  3. Accept all defaults. At the Define Project Details window, leave the ArcGIS Online Basemap selection as is. Complete the project creation.

Set your API key

An API key is required to enable access to services, web maps, and web scenes hosted in ArcGIS Online.

If you haven't already, go to your developer dashboard to get your API key. For these tutorials, use your default API key. It is scoped to include all of the services demonstrated in the tutorials.

  1. In the Projects window, in the Sources folder, open the main.cpp file. Modify the code to set the API key. Paste the API key, acquired from your dashboard, between the quotes. Then save and close the file.

    main.cpp
    Use dark colors for code blocks
    39 39 39 39 39 39 39 39 39 39 39 39 39 39 39 39 39 39 39 39 39 39 39 39 39 39 39 39 39 39 39 39 39 39 39 39 39 39 39 40 41 42 43 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44
    Add line.Add line.Add line.Add line.Add line.
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    //   Copyright 2020 Esri
    //   Licensed under the Apache License, Version 2.0 (the "License");
    //   you may not use this file except in compliance with the License.
    //   You may obtain a copy of the License at
    //
    //   https://www.apache.org/licenses/LICENSE-2.0
    //
    //   Unless required by applicable law or agreed to in writing, software
    //   distributed under the License is distributed on an "AS IS" BASIS,
    //   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    //   See the License for the specific language governing permissions and
    //   limitations under the License.
    //
    
    #include "Display_a_map.h"
    
    #include "ArcGISRuntimeEnvironment.h"
    #include "MapQuickView.h"
    
    #include <QDir>
    #include <QGuiApplication>
    #include <QQmlApplicationEngine>
    
    //------------------------------------------------------------------------------
    
    using namespace Esri::ArcGISRuntime;
    
    int main(int argc, char *argv[])
    {
        QGuiApplication::setAttribute(Qt::AA_EnableHighDpiScaling);
        QGuiApplication app(argc, argv);
    
        // Use of Esri location services, including basemaps and geocoding, requires
        // either an ArcGIS identity or an API key. For more information see
        // https://links.esri.com/arcgis-runtime-security-auth.
    
        // 1. ArcGIS identity: An ArcGIS named user account that is a member of an
        // organization in ArcGIS Online or ArcGIS Enterprise.
    
        // 2. API key: A permanent key that gives your application access to Esri
        // location services. Create a new API key or access existing API keys from
        // your ArcGIS for Developers dashboard (https://links.esri.com/arcgis-api-keys).
    
        const QString apiKey = QString("");
    
        if (apiKey.isEmpty())
        {
            qWarning() << "Use of Esri location services, including basemaps, requires "
                          "you to authenticate with an ArcGIS identity or set the API Key property.";
        }
        else
        {
            ArcGISRuntimeEnvironment::setApiKey(apiKey);
        }
    
        // Production deployment of applications built with ArcGIS Runtime requires you to
        // license ArcGIS Runtime functionality. For more information see
        // https://links.esri.com/arcgis-runtime-license-and-deploy.
    
        // ArcGISRuntimeEnvironment::setLicense("Place license string in here");
    
        // Register the map view for QML
        qmlRegisterType<MapQuickView>("Esri.display_a_map", 1, 0, "MapView");
    
        // Register the Display_a_map (QQuickItem) for QML
        qmlRegisterType<Display_a_map>("Esri.display_a_map", 1, 0, "Display_a_map");
    
        // Initialize application view
        QQmlApplicationEngine engine;
    
        // Add the import Path
        engine.addImportPath(QDir(QCoreApplication::applicationDirPath()).filePath("qml"));
    
        // Set the source
        engine.load(QUrl("qrc:/qml/main.qml"));
    
        return app.exec();
    }
    
    //------------------------------------------------------------------------------

Declare the new method in the header file

  1. In the Projects window, open the Headers folder. Double-click the file display_device_location.h to open it. Add the new method declaration under private:. Then save and close the file.

    Display_device_location.h
    Use dark colors for code blocks
    39 39 39 39 39 39 39 39 39 39 39 39 39 39 39 39 39 39 39 39 39 39 39 39 39 39 39 39 39 39 39 39 39 39 39 39 39 39 39 40 41 42 43 44 44 44 44 44 44 44
    Add line.
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    // Copyright 2021 ESRI
    //
    // All rights reserved under the copyright laws of the United States
    // and applicable international laws, treaties, and conventions.
    //
    // You may freely redistribute and use this sample code, with or
    // without modification, provided you include the original copyright
    // notice and use restrictions.
    //
    // See the Sample code usage restrictions document for further information.
    //
    
    #ifndef DISPLAY_DEVICE_LOCATION_H
    #define DISPLAY_DEVICE_LOCATION_H
    
    namespace Esri
    {
    namespace ArcGISRuntime
    {
    class Map;
    class MapQuickView;
    }
    }
    
    #include <QObject>
    
    class Display_device_location : public QObject
    {
        Q_OBJECT
        Q_PROPERTY(Esri::ArcGISRuntime::MapQuickView* mapView READ mapView WRITE setMapView NOTIFY mapViewChanged)
    public:
        explicit Display_device_location(QObject* parent = nullptr);
        ~Display_device_location() override;
    
    signals:
        void mapViewChanged();
    
    private:
        Esri::ArcGISRuntime::MapQuickView* mapView() const;
        void setMapView(Esri::ArcGISRuntime::MapQuickView* mapView);
    
        void startLocation();
    
        Esri::ArcGISRuntime::Map* m_map = nullptr;
        Esri::ArcGISRuntime::MapQuickView* m_mapView = nullptr;
    };
    
    #endif // DISPLAY_DEVICE_LOCATION_H

Show the current location

Each map view has its own instance of a LocationDisplay for showing the current location (point) of the device. The location is displayed as an overlay in the map view.

  1. In the Projects window, open the Sources folder. Open the display_device_location.cpp file and add the new method shown. This code enables LocationDisplay for the map view and assigns a LocationDisplayAutoPanMode that centers the map at the device location.

    Display_device_location.cpp
    Use dark colors for code blocks
    32 32 32 32 32 32 32 32 32 32 32 32 32 32 32 32 32 32 32 32 32 32 32 32 32 32 32 32 32 32 32 32 33 34 35 36 37 38 39 40 41 42 43 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44
    Add line.Add line.Add line.Add line.Add line.Add line.Add line.
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    //   Copyright 2020 Esri
    //   Licensed under the Apache License, Version 2.0 (the "License");
    //   you may not use this file except in compliance with the License.
    //   You may obtain a copy of the License at
    //
    //   https://www.apache.org/licenses/LICENSE-2.0
    //
    //   Unless required by applicable law or agreed to in writing, software
    //   distributed under the License is distributed on an "AS IS" BASIS,
    //   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    //   See the License for the specific language governing permissions and
    //   limitations under the License.
    //
    
    #include "Display_device_location.h"
    
    #include "Map.h"
    #include "MapQuickView.h"
    
    using namespace Esri::ArcGISRuntime;
    
    Display_device_location::Display_device_location(QObject* parent /* = nullptr */):
        QObject(parent),
    
        m_map(new Map(BasemapStyle::ArcGISTopographic, this))
    {
    }
    
    Display_device_location::~Display_device_location()
    {
    }
    
    MapQuickView* Display_device_location::mapView() const
    {
        return m_mapView;
    }
    
    void Display_device_location::startLocation()
    {
        // start location display
        m_mapView->locationDisplay()->start();
        // center the location display around the device location
        m_mapView->locationDisplay()->setAutoPanMode(LocationDisplayAutoPanMode::Recenter);
    }
    
    // Set the view (created in QML)
    void Display_device_location::setMapView(MapQuickView* mapView)
    {
        if (!mapView || mapView == m_mapView)
        {
            return;
        }
    
        m_mapView = mapView;
        m_mapView->setMap(m_map);
    
        startLocation();
    
        emit mapViewChanged();
    }
    

    The setMapView method appearing later in this file gets a handle to the MapView object that was declared in QML code and sets the Map on the MapView for display. This code is installed by the templates that ArcGIS provides when creating a new project in Qt.

  2. Within the setMapView method, add the call to the new method.

    Display_device_location.cpp
    Use dark colors for code blocks
    45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 45 46 47 48 49 50 51 52 53 54 55 56 57 57 57 57
    Add line.
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    //   Copyright 2020 Esri
    //   Licensed under the Apache License, Version 2.0 (the "License");
    //   you may not use this file except in compliance with the License.
    //   You may obtain a copy of the License at
    //
    //   https://www.apache.org/licenses/LICENSE-2.0
    //
    //   Unless required by applicable law or agreed to in writing, software
    //   distributed under the License is distributed on an "AS IS" BASIS,
    //   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    //   See the License for the specific language governing permissions and
    //   limitations under the License.
    //
    
    #include "Display_device_location.h"
    
    #include "Map.h"
    #include "MapQuickView.h"
    
    using namespace Esri::ArcGISRuntime;
    
    Display_device_location::Display_device_location(QObject* parent /* = nullptr */):
        QObject(parent),
    
        m_map(new Map(BasemapStyle::ArcGISTopographic, this))
    {
    }
    
    Display_device_location::~Display_device_location()
    {
    }
    
    MapQuickView* Display_device_location::mapView() const
    {
        return m_mapView;
    }
    
    void Display_device_location::startLocation()
    {
        // start location display
        m_mapView->locationDisplay()->start();
        // center the location display around the device location
        m_mapView->locationDisplay()->setAutoPanMode(LocationDisplayAutoPanMode::Recenter);
    }
    
    // Set the view (created in QML)
    void Display_device_location::setMapView(MapQuickView* mapView)
    {
        if (!mapView || mapView == m_mapView)
        {
            return;
        }
    
        m_mapView = mapView;
        m_mapView->setMap(m_map);
    
        startLocation();
    
        emit mapViewChanged();
    }
    
  3. Remove the following include statements; these classes are not used.

    Display_device_location.cpp
    Use dark colors for code blocks
    17 17 17 17 17 17 17 17 17 17 17 17 17 17 17 17 17 18 19 20 21 22 22 22 22 22 22 22 22 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23 23
    Remove lineRemove line
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    87
    88
    89
    90
    91
    92
    93
    94
    95
    96
    97
    98
    99
    100
    101
    102
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
    119
    120
    121
    122
    123
    //   Copyright 2020 Esri
    //   Licensed under the Apache License, Version 2.0 (the "License");
    //   you may not use this file except in compliance with the License.
    //   You may obtain a copy of the License at
    //
    //   https://www.apache.org/licenses/LICENSE-2.0
    //
    //   Unless required by applicable law or agreed to in writing, software
    //   distributed under the License is distributed on an "AS IS" BASIS,
    //   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    //   See the License for the specific language governing permissions and
    //   limitations under the License.
    //
    
    #include "Display_a_map.h"
    #include "ArcGISRuntimeEnvironment.h"
    
    #include "Basemap.h"
    
    #include "Map.h"
    #include "MapQuickView.h"
    
    #include "GraphicsOverlay.h"
    #include "PolylineBuilder.h"
    #include "PolygonBuilder.h"
    #include "SimpleMarkerSymbol.h"
    #include "SimpleFillSymbol.h"
    #include "SimpleFillSymbol.h"
    
    #include <QUrl>
    
    using namespace Esri::ArcGISRuntime;
    
    Display_a_map::Display_a_map(QObject* parent /* = nullptr */):
        QObject(parent),
        m_map(new Map(BasemapStyle::ArcGISTopographic, this))
    {
    }
    
    Display_a_map::~Display_a_map()
    {
    }
    
    MapQuickView* Display_a_map::mapView() const
    {
        return m_mapView;
    }
    
    // Set the view (created in QML)
    
    void Display_a_map::setMapView(MapQuickView* mapView)
    {
      if (!mapView || mapView == m_mapView)
      {
        return;
      }
    
      m_mapView = mapView;
      m_mapView->setMap(m_map);
      setupMap();
    
      GraphicsOverlay* overlay = new GraphicsOverlay(this);
      createGraphics(overlay);
      m_mapView->graphicsOverlays()->append(overlay);
    
      emit mapViewChanged();
    }
    
    void Display_a_map::setupMap()
    {
      const Point center(-118.80543, 34.02700, SpatialReference::wgs84());
      const Viewpoint viewpoint(center, 100000.0);
      m_mapView->setViewpoint(viewpoint);
    }
    
    void Display_a_map::createGraphics(GraphicsOverlay *overlay)
    {
    
      // Create a point
      const Point dume_beach(-118.80657463861, 34.0005930608889, SpatialReference::wgs84());
      // Create symbols for the point
      SimpleLineSymbol* point_outline = new SimpleLineSymbol(SimpleLineSymbolStyle::Solid, QColor(Qt::blue), 3, this);
      SimpleMarkerSymbol* point_symbol = new SimpleMarkerSymbol(SimpleMarkerSymbolStyle::Circle, QColor(Qt::red), 10, this);
      point_symbol->setOutline(point_outline);
    
      // Create a graphic to display the point with its symbology
      Graphic* point_graphic = new Graphic(dume_beach, point_symbol, this);
      // Add point graphic to the graphics overlay
      overlay->graphics()->append(point_graphic);
    
      // Create a line
      PolylineBuilder* polyline_builder = new PolylineBuilder(SpatialReference::wgs84(), this);
      polyline_builder->addPoint(-118.8215, 34.0140);
      polyline_builder->addPoint(-118.8149, 34.0081);
      polyline_builder->addPoint(-118.8089, 34.0017);
      // Create a symbol for the line
      SimpleLineSymbol* line_symbol = new SimpleLineSymbol(SimpleLineSymbolStyle::Solid, QColor(Qt::blue), 3, this);
    
      // Create a graphic to display the line with its symbology
      Graphic* polyline_graphic = new Graphic(polyline_builder->toGeometry(), line_symbol, this);
      // Add line graphic to the graphics overlay
      overlay->graphics()->append(polyline_graphic);
    
      // Create a list of points to make up the polygon
      const QList<Point> points = {
        Point(-118.8190, 34.0138),
        Point(-118.8068, 34.0216),
        Point(-118.7914, 34.0164),
        Point(-118.7960, 34.0086),
        Point(-118.8086, 34.0035),
      };
      // Create a polygon using the list of points above
      PolygonBuilder* polygon_builder = new PolygonBuilder(SpatialReference::wgs84(), this);
      polygon_builder->addPoints(points);
      // Create symbols for the polygon
      SimpleLineSymbol* polygon_line_symbol = new SimpleLineSymbol(SimpleLineSymbolStyle::Solid, QColor(Qt::blue), 3, this);
      SimpleFillSymbol* fill_symbol = new SimpleFillSymbol(SimpleFillSymbolStyle::Solid, QColor(Qt::yellow), polygon_line_symbol, this);
      // Create a graphic to display the polygon with its symbology
      Graphic* polygon_graphic = new Graphic(polygon_builder->toGeometry(), fill_symbol, this);
      // Add polygon graphic to the graphics overlay
      overlay->graphics()->append(polygon_graphic);
    
    }
    
  4. Press <Ctrl+R> to run the app.

You should see your current location displayed on the map. Different location symbols are used depending on the auto pan mode and whether a location is acquired. See LocationDisplayAutoPanMode for details.

By default, a round blue symbol is used to display the device's location. The location data source tries to get the most accurate location available but depending upon signal strength, satellite positions, and other factors, the location reported could be an approximation. A semi-transparent circle around the location symbol indicates the range of accuracy. As the device moves and location updates are received, the location symbol will be repositioned on the map.

Learn how to use additional API features, ArcGIS platform services, and ArcGIS tools in these tutorials:

Not all tutorials listed have instructions for QML.

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