Display an offline map (on demand)

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 Maps SDK for Qt, version 200.8.0 or later is installed.

4. The Qt 6.8.2 software development framework or later is installed.

Option 1: Develop the code

Open a Qt Creator project

1. Open the project you created by completing the Display a map tutorial.

2. Continue with the following instructions to display an offline map.

Update the header file

You can display a web map A web map is a map stored as a JSON object that defines properties such as the basemap layer, data layers, layer styles, and pop-up styles. Its JSON structure is defined by the web map specification. Learn more using the web map’s item ID An item ID is a unique identifier representing a single item stored, managed, and accessed in a portal, such as a web map, hosted layer, or file. Learn more . Create a map A map is a collection of layers that are displayed in 2D. It is typically composed of a basemap layer and data layers. Learn more from the web map portal item An item, also known as a content item, is a resource stored in a portal such as a web map, hosted layer, style, script tool, file, or notebook. Learn more , and display it in your app.

1. In Projects, double-click Headers > Display_a_map.h to open the file. Add the following classes to the header file.

   Display_a_map.h

   namespace Esri::ArcGISRuntime {
   
   class Map;
   
   class MapQuickView;
   
   class PortalItem;
   class OfflineMapTask;

2. Remove the unnecessary declaration for the setViewpoint() function.

   Display_a_map.h

   private:
       Esri::ArcGISRuntime::MapQuickView* mapView() const;
       void setMapView(Esri::ArcGISRuntime::MapQuickView* mapView);
   
       void setupViewpoint();
   
       Esri::ArcGISRuntime::Map* m_map = nullptr;
   
       Esri::ArcGISRuntime::MapQuickView* m_mapView = nullptr;
   
   };

3. Add the generateMapByExtent() function declaration and member variables m_portalItem and m_offlineMapTask. Then save the file.

   Display_a_map.h

   private:
       Esri::ArcGISRuntime::MapQuickView* mapView() const;
       void setMapView(Esri::ArcGISRuntime::MapQuickView* mapView);
   
       void generateMapByExtent();
   
       Esri::ArcGISRuntime::Map* m_map = nullptr;
   
       Esri::ArcGISRuntime::MapQuickView* m_mapView = nullptr;
   
       Esri::ArcGISRuntime::PortalItem* m_portalItem = nullptr;
       Esri::ArcGISRuntime::OfflineMapTask* m_offlineMapTask = nullptr;

Update include statements

1. In the Projects window, open the Sources folder and then open the Display_a_map.cpp file. Remove the following unneeded include statements.

   Display_a_map.cpp

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

2. Add the following new include statements.

   Display_a_map.cpp

   #include "Display_a_map.h"
   #include "Map.h"
   
   #include "MapQuickView.h"
   
   #include "SpatialReference.h"
   #include <QFuture>
   
   #include "Envelope.h"
   #include "EnvelopeBuilder.h"
   #include "Error.h"
   #include "GenerateOfflineMapParameters.h"
   #include "GenerateOfflineMapJob.h"
   #include "GenerateOfflineMapResult.h"
   #include "Graphic.h"
   #include "GraphicListModel.h"
   #include "GraphicsOverlay.h"
   #include "GraphicsOverlayListModel.h"
   #include "OfflineMapTask.h"
   #include "Portal.h"
   #include "PortalItem.h"
   #include "SimpleFillSymbol.h"
   #include "SimpleLineSymbol.h"
   #include "SymbolTypes.h"
   #include "TaskTypes.h"
   #include <QDir>
   #include <QUuid>

Remove remaining unneeded code

At this point we will remove the additional unnecessary code before we add the logic for the rest of the app.

1. Continuing on the Display_a_map.cpp file, remove the setupViewpoint() method.

   Display_a_map.cpp

   void Display_a_map::setupViewpoint()
   {
   
       const Point center(-118.80543, 34.02700, SpatialReference::wgs84());
       const Viewpoint viewpoint(center, 100000.0);
       m_mapView->setViewpointAsync(viewpoint);
   
   }

2. Remove the call to the setupViewpoint() method from within the setMapView(MapQuickView* mapView) function.

   Display_a_map.cpp

   // 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();
   
       emit mapViewChanged();
   }

Update the constructor

At this point you will update the constructor in the app.

1. Still editing the Display_a_map.cpp file, remove the comma after QObject(parent) and then modify the constructor to remove initialization with BasemapStyle and the Map.

   Display_a_map.cpp

   Display_a_map::Display_a_map(QObject* parent /* = nullptr */):
   
       QObject(parent),
   
       m_map(new Map(BasemapStyle::ArcGISTopographic, this))

2. Inside the body of the constructor, add code to Instantiate a Portal and from that, a PortalItem using the web map item ID for the Naperville water network. Use that to create a new Map. Then create a new OfflineMapTask referencing that portal item.

   Display_a_map.cpp

   Display_a_map::Display_a_map(QObject* parent /* = nullptr */):
   
       QObject(parent)
   
   {
   
       Portal* portal = new Portal(false, this);
       m_portalItem = new PortalItem(portal, "acc027394bc84c2fb04d1ed317aac674", this);
       m_map = new Map(m_portalItem, this);
       m_offlineMapTask = new OfflineMapTask(m_portalItem, this);

Specify the area of the web map to take offline

1. Continuing on the Display_a_map.cpp file, add the call to generateMapByExtent() method within the setMapView(MapQuickView* mapView) function. The next step implements this method.

   Display_a_map.cpp

   // 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);
   
       generateMapByExtent();
   
       emit mapViewChanged();
   }

2. Begin to implement the generateMapByExtent() function. Use EnvelopeBuilder to set four parameters and then call toEnvelope() to create the envelope. Add this new function near the bottom of the file.

   Display_a_map.cpp

   void Display_a_map::generateMapByExtent()
   {
       // Create envelope to define area of interest
       EnvelopeBuilder* envelopeBuilder = new EnvelopeBuilder(SpatialReference::wgs84(), this);
   
       envelopeBuilder->setXMin(-88.1526);
       envelopeBuilder->setXMax(-88.1490);
       envelopeBuilder->setYMin(41.7694);
       envelopeBuilder->setYMax(41.7714);
   
       Envelope offlineArea = envelopeBuilder->toEnvelope();
   
   }

3. Add a graphic to generateMapByExtent() to show the area you will take offline.

   Create a Graphic using the envelope, SimpleFillSymbol and SimpleLineSymbol. From this create a GraphicsOverlay and add it to the mapView.

   Display_a_map.cpp

   void Display_a_map::generateMapByExtent()
   {
       // Create envelope to define area of interest
       EnvelopeBuilder* envelopeBuilder = new EnvelopeBuilder(SpatialReference::wgs84(), this);
   
       envelopeBuilder->setXMin(-88.1526);
       envelopeBuilder->setXMax(-88.1490);
       envelopeBuilder->setYMin(41.7694);
       envelopeBuilder->setYMax(41.7714);
   
       Envelope offlineArea = envelopeBuilder->toEnvelope();
   
       Graphic* box = new Graphic(offlineArea, new SimpleFillSymbol(SimpleFillSymbolStyle::Solid, Qt::transparent, new SimpleLineSymbol(SimpleLineSymbolStyle::Solid, Qt::red, 3, this), this), this);
       GraphicsOverlay* boxOverlay = new GraphicsOverlay(this);
       boxOverlay->graphics()->append(box);
   
       // add graphics overlay to the map view
       m_mapView->graphicsOverlays()->append(boxOverlay);
   
   }

Download and display the offline map

1. Add the following createDefaultGenerateOfflineMapParametersAsync method that creates a GenerateOfflineMapParameters object. These offline map parameters will serve as the input to create a GenerateOfflineMapJob. Store the resulting offline mobile map package (MMPK) in a location on your development machine. It is important that you specify the folder location that exists on the device and that it matches the code for the outputPath variable.

   Display_a_map.cpp

   void Display_a_map::generateMapByExtent()
   {
       // Create envelope to define area of interest
       EnvelopeBuilder* envelopeBuilder = new EnvelopeBuilder(SpatialReference::wgs84(), this);
   
       envelopeBuilder->setXMin(-88.1526);
       envelopeBuilder->setXMax(-88.1490);
       envelopeBuilder->setYMin(41.7694);
       envelopeBuilder->setYMax(41.7714);
   
       Envelope offlineArea = envelopeBuilder->toEnvelope();
   
       Graphic* box = new Graphic(offlineArea, new SimpleFillSymbol(SimpleFillSymbolStyle::Solid, Qt::transparent, new SimpleLineSymbol(SimpleLineSymbolStyle::Solid, Qt::red, 3, this), this), this);
       GraphicsOverlay* boxOverlay = new GraphicsOverlay(this);
       boxOverlay->graphics()->append(box);
   
       // add graphics overlay to the map view
       m_mapView->graphicsOverlays()->append(boxOverlay);
   
       // generate the offline map parameters
       m_offlineMapTask->createDefaultGenerateOfflineMapParametersAsync(offlineArea).then(this,[this](const GenerateOfflineMapParameters& params)
       {
   
           // Generate the offline map. Store the .mmpk in the desired location.
           const QString outputPath = "ENTER_PATH_TO_MMPK_FILE/offlinemap.mmpk"; // Ex: "C:/mmpk_folder/offlinemap.mmpk"
   
           GenerateOfflineMapJob* generateJob = m_offlineMapTask->generateOfflineMap(params, outputPath);
           if (!generateJob)
               return;
   
   }

2. Add a connect that monitors the status of the GenerateOfflineMapJob and returns changes to status.

   Display_a_map.cpp

   void Display_a_map::generateMapByExtent()
   {
       // Create envelope to define area of interest
       EnvelopeBuilder* envelopeBuilder = new EnvelopeBuilder(SpatialReference::wgs84(), this);
   
       envelopeBuilder->setXMin(-88.1526);
       envelopeBuilder->setXMax(-88.1490);
       envelopeBuilder->setYMin(41.7694);
       envelopeBuilder->setYMax(41.7714);
   
       Envelope offlineArea = envelopeBuilder->toEnvelope();
   
       Graphic* box = new Graphic(offlineArea, new SimpleFillSymbol(SimpleFillSymbolStyle::Solid, Qt::transparent, new SimpleLineSymbol(SimpleLineSymbolStyle::Solid, Qt::red, 3, this), this), this);
       GraphicsOverlay* boxOverlay = new GraphicsOverlay(this);
       boxOverlay->graphics()->append(box);
   
       // add graphics overlay to the map view
       m_mapView->graphicsOverlays()->append(boxOverlay);
   
       // generate the offline map parameters
       m_offlineMapTask->createDefaultGenerateOfflineMapParametersAsync(offlineArea).then(this,[this](const GenerateOfflineMapParameters& params)
       {
   
           // Generate the offline map. Store the .mmpk in the desired location.
           const QString outputPath = "ENTER_PATH_TO_MMPK_FILE/offlinemap.mmpk"; // Ex: "C:/mmpk_folder/offlinemap.mmpk"
   
           GenerateOfflineMapJob* generateJob = m_offlineMapTask->generateOfflineMap(params, outputPath);
           if (!generateJob)
               return;
   
           // use connect to monitor job status for changes and return job status
           connect(generateJob, &GenerateOfflineMapJob::statusChanged, this, [this, generateJob]()
                   {
                       if (generateJob->jobStatus() == JobStatus::Succeeded)
                       {
                           qDebug() << "generating offline map";
                           m_mapView->setMap(generateJob->result()->offlineMap(this));
   
                           qDebug() << (generateJob->error().isEmpty() ? "No errors" : (generateJob->error().message() + generateJob->error().additionalMessage()));
                       }
   
                       else if (generateJob->jobStatus() == JobStatus::Failed)
                       {
                           qWarning() << generateJob->error().message() << generateJob->error().additionalMessage();
                       }
                   });
   
   }

3. Finally, add another connect that displays progress of the GenerateOfflineMapJob as the job executes. Then add code for the generateJob->start().

   Display_a_map.cpp

   void Display_a_map::generateMapByExtent()
   {
       // Create envelope to define area of interest
       EnvelopeBuilder* envelopeBuilder = new EnvelopeBuilder(SpatialReference::wgs84(), this);
   
       envelopeBuilder->setXMin(-88.1526);
       envelopeBuilder->setXMax(-88.1490);
       envelopeBuilder->setYMin(41.7694);
       envelopeBuilder->setYMax(41.7714);
   
       Envelope offlineArea = envelopeBuilder->toEnvelope();
   
       Graphic* box = new Graphic(offlineArea, new SimpleFillSymbol(SimpleFillSymbolStyle::Solid, Qt::transparent, new SimpleLineSymbol(SimpleLineSymbolStyle::Solid, Qt::red, 3, this), this), this);
       GraphicsOverlay* boxOverlay = new GraphicsOverlay(this);
       boxOverlay->graphics()->append(box);
   
       // add graphics overlay to the map view
       m_mapView->graphicsOverlays()->append(boxOverlay);
   
       // generate the offline map parameters
       m_offlineMapTask->createDefaultGenerateOfflineMapParametersAsync(offlineArea).then(this,[this](const GenerateOfflineMapParameters& params)
       {
   
           // Generate the offline map. Store the .mmpk in the desired location.
           const QString outputPath = "ENTER_PATH_TO_MMPK_FILE/offlinemap.mmpk"; // Ex: "C:/mmpk_folder/offlinemap.mmpk"
   
           GenerateOfflineMapJob* generateJob = m_offlineMapTask->generateOfflineMap(params, outputPath);
           if (!generateJob)
               return;
   
           // use connect to monitor job status for changes and return job status
           connect(generateJob, &GenerateOfflineMapJob::statusChanged, this, [this, generateJob]()
                   {
                       if (generateJob->jobStatus() == JobStatus::Succeeded)
                       {
                           qDebug() << "generating offline map";
                           m_mapView->setMap(generateJob->result()->offlineMap(this));
   
                           qDebug() << (generateJob->error().isEmpty() ? "No errors" : (generateJob->error().message() + generateJob->error().additionalMessage()));
                       }
   
                       else if (generateJob->jobStatus() == JobStatus::Failed)
                       {
                           qWarning() << generateJob->error().message() << generateJob->error().additionalMessage();
                       }
                   });
   
           // use connect to monitor job progress changes and return progress return job progress
           connect(generateJob, &GenerateOfflineMapJob::progressChanged, this, [generateJob]()
                   {
                       qDebug() << "Job status:" << generateJob->progress() << "%";
                   });
   
           generateJob->start();
       });
   
   }

Set developer credentials

For the final steps of this tutorial, click the tab below that corresponds to the authentication type (API key authentication or User authentication) that you chose when you completed the Display a map tutorial.

Be sure to also provide the same authentication (API key or user authentication Client ID/Redirect URL) that you used for the Display a map tutorial.

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")
}

{

#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

Press Ctrl + R to run the app.

Initially, you should see the map of the stormwater network for Naperville, IL, USA, with a red outline as before. At the Application Output tab in Creator, the Job status percentage should increment up to 100%, and then you should see the offline map for the specified area of the stormwater network for Naperville, IL, USA. You should also be able to see the downloaded .mmpk file on the device hard drive for the outputPath variable you specified in the code. Remove your network connection and you will still be able to use the mouse to drag, scroll, and double-click the map view to explore this offline map.

Option 2: Download the solution

1. Click the Download solution link under Solution and unzip the file to a location on your machine.

2. Open the .pro project file in Qt Creator.

Since the downloaded solution does not contain authentication credentials, you must set up authentication to create the developer credentials and add them to the project.

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

You will need to store the resulting offline mobile map package (MMPK) in a location on your development machine. It is important that you specify the folder location that exists on the device and that it matches the code for the outputPath variable. The code line you need to modify is found in the generateMapByExtent() method and is highlighted in yellow.

    // generate the offline map parameters
    m_offlineMapTask->createDefaultGenerateOfflineMapParametersAsync(offlineArea).then(this,[this](const GenerateOfflineMapParameters& params)
    {

        // Generate the offline map. Store the .mmpk in the desired location.
        const QString outputPath = "ENTER_PATH_TO_MMPK_FILE/offlinemap.mmpk"; // Ex: "C:/mmpk_folder/offlinemap.mmpk"

        GenerateOfflineMapJob* generateJob = m_offlineMapTask->generateOfflineMap(params, outputPath);
        if (!generateJob)
            return;

For the final steps of this tutorial, click the tab below that corresponds to the authentication type (API key authentication or User authentication) that you chose when you completed the Display a map tutorial.

Be sure to also provide the same authentication (API key or user authentication Client ID/Redirect URL) that you used for the Display a map tutorial.

Set developer credentials in the solution

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")
}

{

#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

Run the app

Press Ctrl + R to run the app.

Initially, you should see the map of the stormwater network for Naperville, IL, USA, with a red outline as before. At the Application Output tab in Creator, the Job status percentage should increment up to 100%, and then you should see the offline map for the specified area of the stormwater network for Naperville, IL, USA. You should also be able to see the downloaded .mmpk file on the device hard drive for the outputPath variable you specified in the code. Remove your network connection and you will still be able to use the mouse to drag, scroll, and double-click the map view to explore this offline map.