Display a map

Set the API Key

1. In the project Sources folder of Qt Creator, open the main.cpp file.

2. Modify the code to set the accessToken using your API key access token (highlighted in yellow).

   main.cpp

       // The following methods grant an access token:
   
       // 1. User authentication: Grants a temporary access token associated with a user's ArcGIS account.
       // To generate a token, a user logs in to the app with an ArcGIS account that is part of an
       // organization in ArcGIS Online or ArcGIS Enterprise.
   
       // 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("");
   
       if (accessToken.isEmpty())
       {
           qWarning() << "Use of ArcGIS location services, such as the basemap styles service, requires" <<
                         "you to authenticate with an ArcGIS account or set the API Key property.";
       }
       else
       {
           ArcGISRuntimeEnvironment::setApiKey(accessToken);
       }

3. Save 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.

Download the ArcGIS Maps SDK for Qt Toolkit

The open-source ArcGIS Maps SDK for Qt Toolkit API Reference contains UI components and utilities to help simplify your Qt app development. The Qt toolkit provides the Authenticator class, which has a dialog that automatically displays the proper authentication for any of the supported authentication types (OAuth, Token, HTTP Basic, HTTP Digest, SAML, PKI, IWA, etc).

To configure the ArcGIS Maps SDK for Qt Toolkit, copy the ArcGIS Maps SDK for Qt Toolkit repository in GitHub onto your development machine.

Do this by cloning the ArcGIS Maps SDK for Qt Toolkit repo (using the the URL: https://github.com/Esri/arcgis-maps-sdk-toolkit-qt/tree/lts.next) or downloading the .zip version of the repo and unzipping it to your preferred location on your development machine.

IMPORTANT: Make a particular note for the path to the toolkitcpp.pri file that is in the directory structure of the toolkit on your development machine. You will need to reference the path to this file later in the tutorial (for example: C:/arcgis-maps-sdk-toolkit-qt/uitools/toolkitcpp/toolkitcpp.pri).

Configure the .pro file

The Qt Creator .pro files contain information required by qmake to build an application, a library, or a plugin.

To utilize Authenticator, you will need to set the path to where the toolkitcpp.pri file is located on your development system. You will also add the code for the Qt WebEngine Quick module to your project. The Qt WebEngine is used to display an OAuth sign in webpage in your app. Then save the Display_a_map.pro file.

See the Install and setup for details on installing the Qt WebEngine on your system.

1. In the Projects window of Qt Creator, open Display_a_map.pro file. Add the following code and set the correct path for the PATH_TO_TOOLKIT variable or the OAuth dialog will not appear to enter your user credentials. Then save the file.

ARCGIS_RUNTIME_VERSION = 200.8.2
include($$PWD/arcgisruntime.pri)

# TODO: You need to replace the <path_to_toolkit_repo> with a valid location where the Qt Toolkit
# resides on your system, example: C:/arcgis-maps-sdk-toolkit-qt/uitools/toolkitcpp/toolkitcpp.pri
# This block determines whether you've cloned your toolkit
PATH_TO_TOOLKIT = "<path_to_toolkit_repo>/uitools/toolkitcpp/toolkitcpp.pri"

exists($${PATH_TO_TOOLKIT}) {
  message("Toolkit found")
  DEFINES += TOOLKIT_FOUND

  # include the toolkitcpp.pri, which contains all the toolkit resources
  include($${PATH_TO_TOOLKIT})

  qtHaveModule(webenginequick) {
    QT += webenginequick
  }
} else {
  message("Toolkit not found in provided path. Either set PATH_TO_TOOLKIT or use an API Key")
}

Add the user authentication code

The OAuth sign in web page is implemented using the Authenticator class and the Qt WebEngine, which is part of the ArcGIS Maps SDK for Qt Toolkit.

In the project Sources folder of Qt Creator, open main.cpp file. Add code for the #include statements for the QtWebEngineQuick, QQmlCOntext, and register.h for the ArcGIS Maps SDK for Qt Toolkit.

#include "Display_a_map.h"
#include "ArcGISRuntimeEnvironment.h"
#include "MapQuickView.h"

#ifdef TOOLKIT_FOUND
  #include <QtWebEngineQuick/QtWebEngineQuick>
  #include "Esri/ArcGISRuntime/Toolkit/register.h"
#endif // TOOLKIT_FOUND

Add the code to initialize the QtWebEngineQuick.

using namespace Esri::ArcGISRuntime;

int main(int argc, char *argv[])
{

    #ifdef TOOLKIT_FOUND
        // Initialize the QtWebEngineQuick to use the web based login dialog.
        QtWebEngineQuick::initialize();
    #endif //TOOLKIT_FOUND


    QGuiApplication app(argc, argv);

    ArcGISRuntimeEnvironment::setUseLegacyAuthentication(false);

Finally in the main.cpp file, add the code to register the ArcGIS Maps SDK for Qt Toolkit. Then save the file.

    // 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;

    #ifdef TOOLKIT_FOUND
        // Register the toolkit
        Esri::ArcGISRuntime::Toolkit::registerComponents(engine);
    #endif //TOOLKIT_FOUND

At this point you need to add the visual component of the ArcGIS Maps SDK for Qt Toolkit control to the QML file of the Qt Creator project. The Authenticator component simplifies the authentication workflow to automatically display the correct login user interface for each security method (OAuth, Token, HTTP Basic, HTTP Digest, SAML, PKI, IWA, etc).

In Qt Creator, navigate to Resources > qml\qml.qrc > qml and open the Display_a_mapForm.qml file. Add code to create the Authenticator component. Then save the file.

    // Declare the C++ instance which creates the map etc. and supply the view
    Display_a_map {

        id: model

        mapView: view

    }

    // Create an Authenticator as a Component, so it can be created dynamically.
    QtObject {
        id: authenticator
        property Component component: null

        function applyComponentStatus() {
            if (!component)
                return;

            if (component.status === Component.Ready) {
                loader.sourceComponent = component;
            } else if (component.status === Component.Error) {
                console.log("Toolkit not found in provided path. Either set PATH_TO_TOOLKIT in the .pro or use an API Key.");
            }
        }

        Component.onCompleted: {
            component = Qt.createComponent("Esri.ArcGISRuntime.Toolkit", "Authenticator", Component.Asynchronous, authenticator);
            component.statusChanged.connect(applyComponentStatus);
            applyComponentStatus();
        }
    }

    // loader to load the Authenticator component
    Loader {
        id: loader
        anchors.centerIn: parent
    }

Add the user authentication header files and namespace

Several additional classes and a namespace are required to support the functionality your app needs. Code need to be added for managing OAuth authentication, creating an image layer, and accessing the secured traffic layer portal item.

1. In the project Sources folder of Qt Creator, open the Display_a_map.cpp file. Add #include statements for the required header files and another namespace as shown. Then save the file.

#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>

#ifdef TOOLKIT_FOUND
  #include "OAuthUserConfigurationManager.h"

  #include "Authentication/OAuthUserConfiguration.h"

  using namespace Esri::ArcGISRuntime::Authentication;
#endif //TOOLKIT_FOUND

Add the code for OAuth

You will create a new OAuthUserConfiguration object. This object is used as the input for the ArcGIS Maps SDK for Qt Toolkit OAuthUserConfigurationManager to make use of the Qt WebEngine based login dialog.

1. In the Display_a_map constructor, add the following code to create a OAuthUserConfiguration object. Then save the file.

IMPORTANT You must set the values for the REDIRECT_URL and the CLIENT_ID strings or the OAuth dialog will not appear to enter your user credentials.

Display_a_map::Display_a_map(QObject* parent /* = nullptr */):

    QObject(parent),

    m_map(new Map(BasemapStyle::ArcGISTopographic, this))

{

#ifdef TOOLKIT_FOUND

    // Define the Redirect URL string obtained when creating the OAuth credentials.
    // TODO: You need to replace the "REDIRECT_URL" with your own valid string,
    // ex: "urn:ietf:wg:oauth:2.0:oob"
    const auto qStringRedirectUrl = QString{"REDIRECT_URL"};

    // Define the URL of the portal to authenticate with.
    const QUrl qUrlPortal = QUrl{"https://www.arcgis.com/"};

    // Define a unique identifier associated with an application registered with the
    // portal that assists with client/server OAuth authentication.
    // TODO: You need to replace the "CLIENT_ID" with your own valid string.
    const QString qStringClientId = QString{"CLIENT_ID"};

    // Create a new OAuth user configuration using: the Url to mapping web service, the Client ID
    // string, and the Redirect Url string.
    auto* oAuthUserConfiguration = new OAuthUserConfiguration(qUrlPortal, qStringClientId,
                                                              qStringRedirectUrl, this);

    // Call the Toolkit's OAuthUserConfigurationManager static `addConfiguration`
    // method to use the OAuth dialog. This will tell the Authenticator to use OAuth for the provided configuration.
    Toolkit::OAuthUserConfigurationManager::addConfiguration(oAuthUserConfiguration);
#endif // TOOLKIT_FOUND

}

Set the API Key

To allow your app users to access ArcGIS location services ArcGIS Location Services, also referred to as Location Services, are services hosted by Esri that provide geospatial functionality for developing mapping applications. They include the ArcGIS Basemap Styles service, ArcGIS Static Basemap Tiles service, ArcGIS Places service, ArcGIS Geocoding service, ArcGIS Routing service, ArcGIS GeoEnrichment service, and ArcGIS Elevation service. An ArcGIS Location Platform or ArcGIS Online account is required to use the services. Learn more , use your API key access token that you created in the Set up authentication section to authenticate requests for resources.

1. In the project Sources folder of Qt Creator, open the main.cpp file.

2. Modify the code to set the accessToken using your API key access token (highlighted in yellow).

   main.cpp

       // The following methods grant an access token:
   
       // 1. User authentication: Grants a temporary access token associated with a user's ArcGIS account.
       // To generate a token, a user logs in to the app with an ArcGIS account that is part of an
       // organization in ArcGIS Online or ArcGIS Enterprise.
   
       // 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("");
   
       if (accessToken.isEmpty())
       {
           qWarning() << "Use of ArcGIS location services, such as the basemap styles service, requires" <<
                         "you to authenticate with an ArcGIS account or set the API Key property.";
       }
       else
       {
           ArcGISRuntimeEnvironment::setApiKey(accessToken);
       }

3. Save 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.

Set path to the Qt Toolkit in the project

Ensure you have completed the prerequisites listed at the beginning of this tutorial. In particular, ensure you have done the step Download the ArcGIS Maps SDK for Qt Toolkit (using the the URL: https://github.com/Esri/arcgis-maps-sdk-toolkit-qt/tree/lts.next) and have noted the path to the toolkitcpp.pri file that is in the directory structure of the Qt Toolkit on your development machine.

To utilize Authenticator, you will need to set the path to where the toolkitcpp.pri file is located on your development system. You will also add the code for the Qt WebEngine Quick module to your project. The Qt WebEngine is used to display an OAuth sign in webpage in your app. Then save the Display_a_map.pro file.

See the Install and setup for details on installing the Qt WebEngine on your system.

In the project Sources folder of Qt Creator, open the Display_a_map.pro file and locate the following lines and update PATH_TO_TOOLKIT variable with the path of the toolkitcpp.pri file (highlighted in yellow) or the OAuth dialog will not appear to enter your user credentials. Then save the file.

ARCGIS_RUNTIME_VERSION = 200.8.2
include($$PWD/arcgisruntime.pri)

# TODO: You need to replace the <path_to_toolkit_repo> with a valid location where the Qt Toolkit
# resides on your system, example: C:/arcgis-maps-sdk-toolkit-qt/uitools/toolkitcpp/toolkitcpp.pri
# This block determines whether you've cloned your toolkit
PATH_TO_TOOLKIT = "<path_to_toolkit_repo>/uitools/toolkitcpp/toolkitcpp.pri"

exists($${PATH_TO_TOOLKIT}) {
  message("Toolkit found")
  DEFINES += TOOLKIT_FOUND

  # include the toolkitcpp.pri, which contains all the toolkit resources
  include($${PATH_TO_TOOLKIT})

  qtHaveModule(webenginequick) {
    QT += webenginequick
  }
} else {
  message("Toolkit not found in provided path. Either set PATH_TO_TOOLKIT or use an API Key")
}

Set developer credentials in the solution

To allow your app users to access ArcGIS location services ArcGIS Location Services, also referred to as Location Services, are services hosted by Esri that provide geospatial functionality for developing mapping applications. They include the ArcGIS Basemap Styles service, ArcGIS Static Basemap Tiles service, ArcGIS Places service, ArcGIS Geocoding service, ArcGIS Routing service, ArcGIS GeoEnrichment service, and ArcGIS Elevation service. An ArcGIS Location Platform or ArcGIS Online account is required to use the services. Learn more , use the developer credentials that you created in the Set up authentication section to authenticate requests for resources.

1. In the project Sources folder of Qt Creator, open the Display_a_map.cpp file.

2. Set your values for the REDIRECT_URL and the CLIENT_ID strings (highlighted in yellow). Then save the file.

{

#ifdef TOOLKIT_FOUND

    // Define the Redirect URL string obtained when creating the OAuth credentials.
    // TODO: You need to replace the "REDIRECT_URL" with your own valid string,
    // ex: "urn:ietf:wg:oauth:2.0:oob"
    const auto qStringRedirectUrl = QString{"REDIRECT_URL"};

    // Define the URL of the portal to authenticate with.
    const QUrl qUrlPortal = QUrl{"https://www.arcgis.com/"};

    // Define a unique identifier associated with an application registered with the
    // portal that assists with client/server OAuth authentication.
    // TODO: You need to replace the "CLIENT_ID" with your own valid string.
    const QString qStringClientId = QString{"CLIENT_ID"};

    // Create a new OAuth user configuration using: the Url to mapping web service, the Client ID
    // string, and the Redirect Url string.
    auto* oAuthUserConfiguration = new OAuthUserConfiguration(qUrlPortal, qStringClientId,
                                                              qStringRedirectUrl, this);

    // Call the Toolkit's OAuthUserConfigurationManager static `addConfiguration`
    // method to use the OAuth dialog. This will tell the Authenticator to use OAuth for the provided configuration.
    Toolkit::OAuthUserConfigurationManager::addConfiguration(oAuthUserConfiguration);
#endif // TOOLKIT_FOUND