Best practices

Map and Scene view options

ArcGIS Maps SDK for Qt offers the two 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	Map view type	Scene view type	Runs on Windows, Linux or macOS	Runs on iOS or Android
Qt Quick C++ app	`MapQuickView`	`SceneQuickView`	Yes	Yes
Qt Widgets C++ app	`MapGraphicsView`	`SceneGraphicsView`	Yes	No

Qt Quick

ArcGIS Maps SDK for Qt supports writing Qt Quick apps in a combination of C++ and QML.

Create a Qt Quick C++ app

The MapQuickView class is part of the C++ API. MapQuickView is an implementation of MapView 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 MapQuickView type as MapView in main.cpp.

Use dark colors for code blocksCopy
    // Register the map view for QML
    qmlRegisterType<MapQuickView>("Esri.Samples", 1, 0, "MapView");

In the C++ header file, the template creates a read/write Q_PROPERTY for the MapView.

Use dark colors for code blocksCopy
    Q_PROPERTY(Esri::ArcGISRuntime::MapQuickView* mapView READ mapView WRITE setMapView NOTIFY mapViewChanged)

Additionally, in the C++ header file, the template includes the MapQuickView for the meta object compiler (MOC), since the type has been forward declared.

Use dark colors for code blocksCopy
Q_MOC_INCLUDE("MapQuickView.h");

The template creates the MapView component in the <appname\>Form.qml file.

Use dark colors for code blocksCopy
Item {

    // Create MapView (MapQuickView) here. Then create its Map (type) etc., in C++ code.
    MapView {
        id: view
        anchors.fill: parent

        Component.onCompleted: {
            // Set and keep the focus on MapView to enable keyboard navigation
            forceActiveFocus();
        }
    }

    // Declare the C++ instance which creates the map etc. and supply the view
    ProgrammingPatternsSample {
        id: model
        mapView: view
    }
}

In the your app's C++ code (<appname>.cpp), the template creates the following code. The constructor initializes QObject, and m_map using the BasemapStyle you selected when creating the project.

Use dark colors for code blocksCopy
ProgrammingPatterns::ProgrammingPatterns(QObject* parent /* = nullptr */):
    QObject(parent),
    m_map(new Map(BasemapStyle::ArcGISTopographic, this))
{
}

Below, the template creates the setMapView function. This function is what is executed when the MapView is created and set in QML code.

Use dark colors for code blocksCopy
// Set the view (created in QML)
void ProgrammingPatterns::setMapView(MapQuickView* mapView)
{
    if (!mapView || mapView == m_mapView)
        return;

    m_mapView = mapView;
    m_mapView->setMap(m_map);

    emit mapViewChanged();
}

Create a Qt Widgets C++ 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 MapGraphicsView.

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. BasemapStyle is set from your selection when creating the project.

Use dark colors for code blocksCopy
Display_a_map::Display_a_map(QWidget* parent /*=nullptr*/):
    QMainWindow(parent)
{
    // Create a map using the ArcGISStreets BasemapStyle.
    m_map = new Map(BasemapStyle::ArcGISStreets, this);

    // Create the Widget view.
    m_mapView = new MapGraphicsView(this);

    // Set map to map view.
    m_mapView->setMap(m_map);

    // Set the mapView as the central widget.
    setCentralWidget(m_mapView);
}

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_runtime_qml_cpp 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:

Use dark colors for code blocksCopy

include(/pathToSDK/sdk/ideintegration/arcgis_runtime_qml_cpp.pri)

Qt Widgets C++ API integration

Integration with qmake

Include the esri_runtime_qt 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:

Use dark colors for code blocksCopy
include(/pathToSDK/sdk/ideintegration/esri_runtime_qt.pri)

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: QNetworkProxy::setApplicationProxy(QNetworkProxy(QNetworkProxy::HttpProxy, "127.0.0.1", 8888));. 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, QNetworkProxy::setApplicationProxy() 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.