Best practices
Map and Scene view options
ArcGIS Maps SDK for Qt offers the three patterns listed below for creating and displaying a map in a map view, or scene in a scene view. For convenience, templates are included with the SDK to aid in creating new projects. In Qt Creator, choose the ArcGIS template based on your resources, platform, experience, and need for speed.
ArcGIS Template | Uses this API | Map view type | Scene view type | Runs on Windows, Linux or macOS | Runs on iOS or Android |
---|---|---|---|---|---|
Qt Quick Cpp app | C++ | Map | Scene | Yes | Yes |
Qt Quick QML app | QML | Map | Scene | Yes | Yes |
Qt Widgets Cpp app | C++ | Map | Scene | Yes | No |
Qt Quick
ArcGIS Maps SDK for Qt supports writing Qt Quick apps in a combination of C++ and QML code, or in pure QML. This is accomplished by using the C++ API or its QML API, respectively.
Create a Qt Quick Cpp app
The Map
class is part of the C++ API. Map
is an implementation of Map
accessible from QML, and harnesses the speed of the C++ API in the business logic. With this approach, you leverage QML's extensive set of UI functionality, flexibility, and visual appeal while providing ArcGIS capabilities through the C++ API. Often recommended by Qt experts, this app pattern works on the platforms listed above. Note that with this template/pattern, you cannot use components of the C++ and QML APIs together in the same app.
To use this pattern, when creating your new project in Qt Creator, select Qt Quick C++ app (for the ArcGIS Maps SDK version installed) and then finish creating the project. The selected ArcGIS Maps SDK template registers Map
type as Map
in main.cpp
.
In the C++ header file, the template creates a read/write Q_
for the Map
.
Additionally, in the C++ header file, the template includes the MapQuickView for the meta object compiler (MOC), since the type has been forward declared.
The template creates the Map
component in the <appname\>
file.
In the your app's C++ code (<appname>.cpp), the template creates the following code. The constructor initializes QObject
, and m_
using the Basemap
you selected when creating the project.
Below, the template creates the set
function. This function is what is executed when the MapView is created and set in QML code.
Create a Qt Quick QML app
If you're familiar with the QML API from The Qt Group, you already know how quickly you can produce a powerful app with QML. QML offers a declarative, highly-readable syntax for designing and building responsive and fluid user interfaces for native desktop and mobile applications. ArcGIS Maps SDK for Qt extends QML with QML types that provide ArcGIS functionality. Objects are declared hierarchically and have bindable properties to provide automatically dynamic behavior. JavaScript functions are used to provide procedural code when needed. This is a powerful feature for developers who are familiar with web development and want to develop native apps. QML has been part of the API since version 10.2.5 and works on all supported platforms.
To use this pattern, when creating your new project in Qt Creator, select Qt Quick QML app (for the ArcGIS Maps SDK version installed) and then finish creating the project. The template creates the following code in main.qml
. The template creates an Application
containing a Map
. Within the Map
, the code declares a Map
. Basemap
is set from your selection when creating the project.
Create a Qt Widgets Cpp app
C++ is all about performance. With the C++ API, you can build an app with a powerful computing back-end, and develop your UI in C++ using the Qt Widgets module. Qt Widgets has a rich suite of tools and components used for building powerful desktop applications. C++ is supported for applications running on Linux, macOS, and Windows. For pure C++ apps like these, the map view is implemented as a Map
.
To use this pattern, when creating your new project in Qt Creator, select Qt Widgets app (for the ArcGIS Maps SDK version installed) and then finish creating the project. The template creates the following code in the <appname>.cpp file. Basemap
is set from your selection when creating the project.
Integrate the SDK into an existing app
The ArcGIS Maps SDK for Qt can be integrated into an existing Qt app with a couple of steps. The steps vary slightly depending on if the application was created using Qt Quick or Qt Widgets.
Qt Quick C++ API integration
Integration with qmake
Include the arcgis_
pri
file into your project file. You can get this pri
file from the SDK installation, under the folder sdk/ideintegration
folder. For example, the following syntax includes the ArcGIS Maps SDK C++ API into your Qt Quick application:
Qt Quick QML API integration
Integration with qmake
To use the QML API, include the arcgis_
pri
file into your project file. You can get this pri
file from the SDK installation, under the folder sdk/ideintegration
folder. For example, the following syntax includes the ArcGIS Maps SDK QML API into your Qt QML Quick application:
Include the QML plugin in your app
After setting up your build system to find ArcGIS Maps SDK, you will need to add the paths of the QML plugins you plan on using into the QML Import Path. Because it contains all of the ArcGIS Maps SDK functionality for this API, add the path to the ArcGIS Maps SDK QML Plugin. Add QML plugins to the QML Import Path by using the QQml
method in C++ code. For example, you can add the ArcGIS Maps SDK QML plugin to the plugin path with the following syntax:
As an alternative, you could instead add an environment variable called QML2_
with the paths to the various plugins you wish to use.
After the pri
file is included and the import paths are added, import the QML plugin in a QML file by using the import
syntax. For example:
Qt Widgets C++ API integration
Integration with qmake
Include the esri_
project include file (pri
) into your project file. You can get this pri
file from the SDK installation, under the sdk/ideintegration
folder. For example, the following syntax includes ArcGIS Maps SDK into your Qt Widgets application:
Additional information
The following Qt resources provide additional information about how to include project files with qmake and how to add QML plugins into your applications.
Debugging your app
ArcGIS Maps SDK for Qt is built on top of the Qt Framework, which means you get access to all of the same debugging utilities used with Qt. Here are some helpful tips and tricks for debugging your Qt apps.
Using a web proxy
When debugging ArcGIS Maps SDK for Qt apps, a web debugging utility is often useful to capture and analyze the HTTP requests sent and responses returned. Fiddler and Charles are two examples of web debugging utilities used to perform this task. These tools can be used to debug an app by adding the following C++ code in your app: QNetwork
. This code can be set at runtime, and can either be in your main.cpp, or in some other C++ class. Beyond using a proxy for debugging, QNetwork
can also be used to specify your organization's proxy server. To do this, specify the URL and port of your organization's proxy server. Find more information in Qt's QNetworkProxy documentation.