Display a map

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

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:

You need an ArcGIS Location Platform or ArcGIS Online account.
Your system meets the system requirements.
The ArcGIS Maps SDK for Qt, version 200.6.0 or later is installed.
The Qt 6.5.6 software development framework is installed.

Set up authentication

To access the secure ArcGIS location services used in this tutorial, you must implement API key authentication using an ArcGIS Location Platform or an ArcGIS Online account.

Create a new API key access token with privileges to access the secure resources used in this tutorial.

Complete the Create an API key tutorial and create an API key with the following privilege(s):
- Privileges
  - Location services > Basemaps
Copy and paste the API key access token into a safe location. It will be used in a later step.

Develop or Download

You have two options for completing this tutorial:

Option 1: Develop the code or
Option 2: Download the completed solution

Option 1: Develop the code

Create a new ArcGIS Maps Qt Creator Project

Start Qt Creator.
In the top menu bar, click File > New Project.
In the New Project dialog, in the left frame, under Projects, select ArcGIS. Then select the ArcGIS Maps 200.6.0 Qt Quick C++ app project template (or a later version) and click Choose. This will launch the template wizard.
In the Project Location template, name your project Display_a_map. You can specify your own "create in" location for where the project will be created or leave the default. Click Next.
In the Define Build System template, select qmake for your build system. Click Next.
In the Define Project Details template, give this app a description or leave as is. Leave the 3D project box unchecked. At the ArcGIS Online Basemap dropdown menu, select Topographic. There is no need to supply an API Key (also called an access token) at this time, you can leave it blank. We will discuss this more in the next section. Click Next.
In the Kit Selection template, check on the kit you previously set up when you installed Qt (Desktop Qt 6.5.6 MSVC2019 64bit or higher required). Click Next.
In the Project Management template, the option to Add as a subproject to root project is only available if you have already created a root project. If you have a version control system set up, you can select it in the dropdown but it is not needed to complete this tutorial. Click Finish to complete the template wizard.

Set developer credentials

To allow your app users to access ArcGIS location services, use the developer credentials that you created in the Set up authentication step to authenticate requests for resources.

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

Modify the code to set the accessToken using your API key access token.

main.cpp
Expand
Use dark colors for code blocks
    // 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

Save and close the main.cpp file.

Best Practice: The access token is stored directly in the code as a convenience for this tutorial. Do not store credentials directly in source code in a production environment.

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.

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

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

Display_a_map.h
Expand
Use dark colors for code blocks
private:
    Esri::ArcGISRuntime::MapQuickView* mapView() const;
    void setMapView(Esri::ArcGISRuntime::MapQuickView* mapView);

    void setupViewpoint();
Expand

In the Projects window, open the Sources folder. Open the display_a_map.cpp file.

Add the following #include statements.

Display_a_map.cpp
Use dark colors for code blocks
#include "Display_a_map.h"
#include "Map.h"

#include "MapTypes.h"

#include "MapQuickView.h"

#include "Point.h"
#include "Viewpoint.h"
#include "SpatialReference.h"
#include <QFuture>

Create the view point

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 asynchronously sets the initial Map viewpoint.

The center Point and scale value keep the initial Viewpoint centered and focused on the Santa Monica Mountains. The scale value sets the level of detail to focus on the area of interest.

The spatial reference created above is set to use World Geodetic System 1984 (WGS84), the spatial reference commonly used for GPS, and it has the well known id 4326. To learn more, see Spatial References in the ArcGIS Maps SDK for Qt Guide.
Display_a_map.cpp
Use dark colors for code blocks
```
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
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->setViewpointAsync(viewpoint);

}
```
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. You should not modify it.

Add the following line of code to call setupViewpoint.

Display_a_map.cpp
Expand
Use dark colors for code blocks
// 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

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.

Alternatively, you can download the tutorial solution, as follows.

Option 2: Download the solution

Click the Download solution link under Solution and unzip the file to a location on your machine.
Open the project in Qt Creator.

Since the downloaded solution does not contain authentication credentials, you must add the developer credentials that you created in the set up authentication section.

Set developer credentials in the solution

To allow your app users to access ArcGIS location services, use the developer credentials that you created in the Set up authentication step to authenticate requests for resources.

In the Projects window, go to the Sources folder
Open the main.cpp file.

Modify the code to set the accessToken using your API key access token.

main.cpp
Use dark colors for code blocks
    // 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("");

Save and close the file.

Best Practice: The access token is stored directly in the code as a convenience for this tutorial. Do not store credentials directly in source code in a production environment.

Run the app

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: