Display a map

Learn how to create and display a map with a basemap layer.

display a map

A map contains layers of geographic data. A map contains a basemap layer and, optionally, one or more data layers. You can display a specific area of a map by using a map view and setting the location and zoom level.

In this tutorial, you create and display a map of the Santa Monica Mountains in California using the topographic basemap layer.

The map and code will be used as the starting point for other 2D tutorials.

Prerequisites

Before starting this tutorial:

  1. You need an ArcGIS Location Platform or ArcGIS Online account.

  2. Your system meets the system requirements.

  3. The ArcGIS Runtime API for Qt is installed.

Choose your API

You can do this tutorial in C++ or QML. Make your selection below:

Steps for C++

Create a new ArcGIS Runtime Qt Creator Project

Use Qt Creator to create an app that displays a Map centered on the Santa Monica Mountains.

  1. Start Qt Creator.

  2. Click File > New File or Project. Under Projects, select ArcGIS.

  3. Select the ArcGIS Runtime 100.15 Qt Quick C++ app project template (or a later version) and click Choose.

  4. In the Project Location dialog, name your project display_a_map. Click Next.

  5. In the Define Build System dialog, select qmake for your build system. Click Next.

  6. In the Define Project Details dialog, give this app a description or leave as is. Leave the rest of this dialog as is.

  7. Leave the 3D project box unchecked. At the ArcGIS Online Basemap dropdown menu, select Topographic. Then click Next.

  8. On the Kit Selection dialog, check the kit(s) you previously set up when you installed the API. You should select a Desktop kit to run this tutorial. Then click Next.

  9. At the Project Management dialog, the option to Add as a subproject to root project is only available if you have already created a root project. Ignore this dialog for this tutorial. Click Next.

Get an access token

You need an access token to use the location services used in this tutorial.

  1. Go to the Create an API key tutorial to obtain an access token.

  2. Ensure that the following privilege is enabled: Location services > Basemaps > Basemap styles service.

  3. Copy the access token as it will be used in the next step.

To learn more about other ways to get an access token, go to Types of authentication.

Set your API key

  1. In the Projects window, in the Sources folder, open the main.cpp file. Modify the code to set the API key to the access token. Save and close the file.

    main.cpp
    Expand
    Use dark colors for code blocks
    43 44 45 46 47
    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
    81
    82
    83
        // 2. API key authentication: Get a long-lived access token that gives your application access to
        // ArcGIS location services. Go to the tutorial at https://links.esri.com/create-an-api-key.
        // Copy the API Key access token.
    
        const QString accessToken = QString("");
    
    Expand

Add a map

Use the map view to display a map centered on the Santa Monica Mountains in California. The map will contain a layer built from the ArcGISTopographic BasemapStyle.

  1. In the Projects window, open the Headers folder. Double-click the file display_a_map.h to open it.

  2. Add the declaration void setupViewpoint(); under private:. Then save and close the file.

    Display_a_map.h
    Expand
    Use dark colors for code blocks
    44 45 46 47 48
    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
    private:
        Esri::ArcGISRuntime::MapQuickView* mapView() const;
        void setMapView(Esri::ArcGISRuntime::MapQuickView* mapView);
    
        void setupViewpoint();
    
    Expand
  3. In the Projects window, open the Sources folder. Open the display_a_map.cpp file.

  4. Add the following #include statement.

    Display_a_map.cpp
    Expand
    Use dark colors for code blocks
    15 16 17 18 19 20 21 22
    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
    #include "Display_a_map.h"
    
    #include "ArcGISRuntimeEnvironment.h"
    
    #include "Basemap.h"
    #include "Map.h"
    
    #include "MapQuickView.h"
    
    Expand
  5. Add code to implement the setupViewpoint method. This method creates a center Point based on a SpatialReference along with longitude and latitude. It also creates a Viewpoint based on center and sets scale. Lastly, it sets the initial Map viewpoint.

    Display_a_map.cpp
    Expand
    Use dark colors for code blocks
    43 44 45 46 47 48 49 50 51 52 53 54 55 56
    Add line.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
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    MapQuickView* Display_a_map::mapView() const
    {
        return m_mapView;
    }
    
    void Display_a_map::setupViewpoint()
    {
    
      const Point center(-118.80543, 34.02700, SpatialReference::wgs84());
      const Viewpoint viewpoint(center, 100000.0);
      m_mapView->setViewpoint(viewpoint);
    
    }
    
    
    Expand
  6. Add the following code to call setupViewpoint.

    Display_a_map.cpp
    Expand
    Use dark colors for code blocks
    58 59 60 61 62 63 64 65 66 67 68 69 70
    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
    // 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);
    
        setupViewpoint();
    
    Expand
  7. Press Ctrl + R to run the app.

You should see a map with the topographic basemap layer centered on the Santa Monica Mountains in California. Zoom in and out, and drag the map view to explore the map.

To explore other tutorials, see What's next.

Steps for QML

Create a new ArcGIS Runtime Qt Creator Project

Use Qt Creator to create an app that displays a Map centered on the Santa Monica Mountains.

  1. Start Qt Creator.

  2. Click File > New File or Project. In the left-most window, under Projects, select ArcGIS.

  3. Select the ArcGIS Runtime 100.15 Qt Quick QML app project template (or a later version) and click Choose.

  4. In the Project Location dialog, name your project Display_a_map.

  5. At the Create in field, browse to where you want to place this project. Click Next.

  6. In the Define Build System dialog, select qmake for your build system. Click Next.

  7. In the Define Project Details dialog, give this app a description or leave as is.

  8. At the ArcGIS Online Basemap drop-down menu, select Topographic. Click Next.

  9. On the Kit Selection dialog, check the kit(s) you previously set up when you installed the API. Select a Desktop kit to run this tutorial. Click Next.

  10. Verify your selections and click Finish.

Get an access token

You need an access token to use the location services used in this tutorial.

  1. Go to the Create an API key tutorial to obtain an access token.

  2. Ensure that the following privilege is enabled: Location services > Basemaps > Basemap styles service.

  3. Copy the access token as it will be used in the next step.

To learn more about other ways to get an access token, go to Types of authentication.

Set your API key

  1. In the Projects window, in the Sources folder, open the main.cpp file.

  2. Modify the code to set the API key to the access token.

    main.cpp
    Expand
    Use dark colors for code blocks
    38 39 40 41 42
    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
    81
    82
        // 2. API key authentication: Get a long-lived access token that gives your application access to
        // ArcGIS location services. Go to the tutorial at https://links.esri.com/create-an-api-key.
        // Copy the API Key access token.
    
        const QString accessToken = QStringLiteral("");
    
    Expand

Update the map

This application will use the map view to display a map centered on the Santa Monica Mountains in California. The map will contain a layer built from the ArcGISTopographic BasemapStyle.

  1. If the main.qml file is not already open, in the Projects window, navigate to Resources > qml\qml.qrc > /qml and open the main.qml file.

  2. Within the Map object, set the property initialViewpoint toviewpoint (you will create this object in the next step).

    main.qml
    Expand
    Use dark colors for code blocks
    31 32 33 34 35 36 37
    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
            // add a map to the mapview
            Map {
    
                // add the ArcGISTopographic basemap to the map
                initBasemapStyle: Enums.BasemapStyleArcGISTopographic
    
                initialViewpoint: viewpoint
    
    Expand

Define the viewpoint

"A ViewpointCenter defines a map area using a location (point) and a map scale. You can create a new ViewpointCenter to define the initial viewpoint to display when the map loads."

  1. After the closing brace of Map, create an instance of ViewpointCenter with an id of viewpoint. You will initially see an Expected token }' error, however you will add the closing brace when you are done defining the ViewpointCenter.

    main.qml
    Expand
    Use dark colors for code blocks
    31 32 33 34 35 36 37 38 39 40 41 42
    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
            // add a map to the mapview
            Map {
    
                // add the ArcGISTopographic basemap to the map
                initBasemapStyle: Enums.BasemapStyleArcGISTopographic
    
                initialViewpoint: viewpoint
    
            }
    
            ViewpointCenter {
                id: viewpoint
    
    Expand
  2. Set the ViewpointCenter center property to a Point, with x (longitude), y (latitude), and SpatialReference properties set as shown. Be sure to add the closing brace for Point.

    main.qml
    Expand
    Use dark colors for code blocks
    41 42 43 44 45 46 47 48 49
    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
            ViewpointCenter {
                id: viewpoint
    
                // Specify the center Point
                center: Point {
                    x: -118.80543
                    y: 34.02700
                    spatialReference: SpatialReference {wkid: 4326}
                }
    
    Expand
  3. Set the targetScale property of viewpoint as shown. Add the following code, including the closing brace. This will remove the Expected token }' error.

    main.qml
    Expand
    Use dark colors for code blocks
    44 45 46 47 48 49 50 51 52 53
    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
                // Specify the center Point
                center: Point {
                    x: -118.80543
                    y: 34.02700
                    spatialReference: SpatialReference {wkid: 4326}
                }
    
            // Specify the scale
            targetScale: 100000.0
            }
    
    Expand
  4. Press Ctrl + R to run the app.

You should see a map with the topographic basemap layer centered on the Santa Monica Mountains in California. Zoom in and out, and drag the map view to explore the map.

What's next?

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

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