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.7.0 or later is installed.

4. The Qt 6.8.2 software development framework is installed.

Option 1: Develop the code

Get the web map item ID

You can use ArcGIS tools to create and view web maps. Use the Map Viewer to identify the web map item ID. This item ID will be used later in the tutorial.

1. Go to the Naperville water network in the Map Viewer in ArcGIS Online. This web map displays stormwater network within Naperville, IL, USA .
2. Make a note of the item ID at the end of the browser's URL. The item ID should be:

   acc027394bc84c2fb04d1ed317aac674

   .

Create a new ArcGIS Maps Qt Creator Project

1. Start Qt Creator.

2. In the top menu bar, click File > New Project.

3. In the New Project dialog, in the left frame, under Projects, select ArcGIS. Then select the ArcGIS Maps 200.7.0 Qt Quick C++ app project template (or a later version) and click Choose. This will launch the template wizard.

4. In the Project Location template, name your project Display_an_offline_map. You can specify your own "create in" location for where the project will be created or leave the default. Click Next.

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

6. 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, leave the default. 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.

7. In the Kit Selection template, check on the kit you previously set up when you installed Qt (Desktop Qt 6.8.2 MSVC2022 64bit or higher required). Click Next.

8. 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.

Display the web map

You can display a web map using the web map's item ID. Create a map from the web map portal item, and display it in your app.

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

   Display_an_offline_map.h

   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
   namespace Esri::ArcGISRuntime {
   class Map;
   class MapQuickView;
   
   class PortalItem;
   class OfflineMapTask;
   

2. Add the generateMapByExtent() function declaration and member variables m_portalItem and m_offlineMapTask. Save and close the file.

   Display_an_offline_map.h

   Expand

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

   Expand

3. In Projects, double-click Sources > Display_an_offline_map.cpp to open the file. Remove the #include statement for MapTypes.h; the map is provided by the offline map.

   Display_an_offline_map.cpp

   Use dark colors for code blocks

   1
   2
   3
   4
   5
   6
   7
   8
   
   #include "Display_an_offline_map.h"
   
   #include "Map.h"
   
   #include "MapTypes.h"
   
   #include "MapQuickView.h"

4. Add the following #include statements. These classes are needed for this application.

   Display_an_offline_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
   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
   124
   125
   126
   127
   128
   129
   130
   131
   #include "Display_an_offline_map.h"
   #include "Map.h"
   #include "MapQuickView.h"
   
   #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 "SpatialReference.h"
   #include "SymbolTypes.h"
   #include "TaskTypes.h"
   #include <QFuture>
   #include <QDir>
   #include <QUuid>
   

5. Delete the comma after QObject(parent) and remove the Map from the constructor.

   Display_an_offline_map.cpp

   Use dark colors for code blocks

   1
   2
   3
   4
   5
   
   Display_an_offline_map::Display_an_offline_map(QObject* parent /* = nullptr */):
       QObject(parent),
   
       m_map(new Map(BasemapStyle::ArcGISStreets, this))

6. 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_an_offline_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
   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
   124
   125
   126
   127
   128
   129
   130
   131
   Display_an_offline_map::Display_an_offline_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);
   

7. Press Ctrl + R to run the app.

   You should see a map of the stormwater network within Naperville, IL, USA. Use the mouse to drag, scroll, and double-click the map view to explore the map.

Specify the area of the web map to take offline

1. Add the call to generateMapByExtent. (The next step implements this function.)

   Display_an_offline_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
   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
   124
   125
   126
   127
   128
   129
   130
   131
   // Set the view (created in QML)
   void Display_an_offline_map::setMapView(MapQuickView* mapView)
   {
       if (!mapView || mapView == m_mapView)
       {
           return;
       }
   
       m_mapView = mapView;
       m_mapView->setMap(m_map);
   
       generateMapByExtent();
   

2. Begin to implement the generateMapByExtent() function. Use EnvelopeBuilder to set four parameters and then call toEnvelope() to create the envelope.

   Display_an_offline_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
   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
   124
   125
   126
   127
   128
   129
   130
   131
   // Set the view (created in QML)
   void Display_an_offline_map::setMapView(MapQuickView* mapView)
   {
       if (!mapView || mapView == m_mapView)
       {
           return;
       }
   
       m_mapView = mapView;
       m_mapView->setMap(m_map);
   
       generateMapByExtent();
   
       emit mapViewChanged();
   }
   
   void Display_an_offline_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_an_offline_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
   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
   124
   125
   126
   127
   128
   129
   130
   131
   void Display_an_offline_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);
   
   }

4. Press Ctrl + R to run the app.

   You should see a red outline on the stormwater network within Naperville, IL, USA. This indicates the area of the web map that you are going to take offline.

Download and display the offline map

1. Add the following createDefaultGenerateOfflineMapParametersAsync method that creates a GenerateOfflineMapParameters object. These offline map parameters will serves as the input to create a GenerateOfflineMapJob. Store the resulting offline mobile map package (MMPK) in a location on your development machine (you need to ensure the folder location exists and that it matches the code for the OutputPath variable). Don't add a closing brace yet.

   Display_an_offline_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
   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
   124
   125
   126
   127
   128
   129
   130
   131
       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_an_offline_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
   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
   124
   125
   126
   127
   128
   129
   130
   131
       // 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. Add another connect (optional) that displays progress of the GenerateOfflineMapJob as the job executes. Add the final code generateJob->start() and the final closing code (required) to complete the first connect function.

   Display_an_offline_map.cpp

   Expand

   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
   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
   124
   125
   126
   127
   128
   129
   130
   131
           // 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();
       });
   

   Expand

4. 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 project in Qt Creator.

3. Open the file Display_an_offline_map.cpp, look for the line of code that reads:

   Use dark colors for code blocksCopy

   1
   const QString outputPath = "ENTER_PATH_TO_MMPK_FILE/offlinemap.mmpk"; // Ex: "C:/mmpk_folder/offlinemap.mmpk"

   and change the outputPath variable to store the resulting offline mobile map package (MMPK) in a location on your development machine (you need to ensure the folder location exists and that it matches the code).

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.

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.