Best practices

Map and Scene view options

ArcGIS Runtime API 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.

Qt Quick

ArcGIS Runtime supports writing Qt Quick apps in a combination of C++ and QML code, or in pure QML. This is accomplished by using ArcGIS Runtime's C++ API or its QML API, respectively.

Create a Qt Quick Cpp 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 Runtime 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 Runtime version installed) and then finish creating the project. The selected ArcGIS Runtime template registers MapQuickView type as MapView in main.cpp.

1
2
    // Register the map view for QML
    qmlRegisterType<MapQuickView>("Esri.Display_map_quick_Cpp", 1, 0, "MapView");

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

1
    Q_PROPERTY(Esri::ArcGISRuntime::MapQuickView* mapView READ mapView WRITE setMapView NOTIFY mapViewChanged)

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
 Item {

    // Create MapView (MapQuickView) here. Then create its Map (type) etc., in C++ code.

    MapView {
        id: view
        anchors.fill: parent
        // set focus to enable keyboard navigation
        focus: true
    }

    // Declare the C++ instance which creates the map etc., and supply the view
    Display_a_map {
        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.

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
// 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);

    emit mapViewChanged();
}

Create a Qt Quick QML app

If you're familiar with the QML API from The Qt Company, 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 Runtime API for Qt extends QML with QML types that provide ArcGIS Runtime 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 Runtime version installed) and then finish creating the project. The template creates the following code in main.qml. The template creates an ApplicationWindow containing a MapView. Within the MapView, the code declares a Map. BasemapStyle is set from your selection when creating the project.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
ApplicationWindow {
    id: appWindow
    width: 800
    height: 600
    title: "Display_a_map"

    // add a mapView component
    MapView {
        anchors.fill: parent
        // set focus to enable keyboard navigation
        focus: true

        // add a map to the mapview
        Map {
            // Add the ArcGISTopographic BasemapStyle to the map
            initBasemapStyle: Enums.BasemapStyleArcGISTopographic
        }
    }
}

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

To use this pattern, when creating your new project in Qt Creator, select Qt Widgets app (for the ArcGIS Runtime 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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
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 Runtime 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

To use the C++ API, 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 Runtime C++ API into your Qt Quick application:

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

Qt Quick QML API integration

To use the QML API, include the arcgis_runtime_qml 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 Runtime QML API into your Qt QML Quick application:

1
include(/pathToSDK/sdk/ideintegration/arcgis_runtime_qml.pri)

After the pri file has been included in your project file, 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 Runtime functionality for this API, add the path to the ArcGIS Runtime QML Plugin. Optionally, you may want to add the import paths to the ArcGIS Extras plugin or the Toolkit. Adding QML plugins to the QML Import Path can be accomplished by using the QQmlEngine::addImportPath(pathToPlugin); method in C++ code. For example, you can add the ArcGIS Runtime QML plugin to the plugin path with the following syntax:

1
view.engine()->addImportPath("pathToSDK/sdk/macOS/x64/qml");

As an alternative, you could instead add an environment variable called QML2_IMPORT_PATH 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, version 100.13 of ArcGIS Runtime could be imported with the following:

1
import Esri.ArcGISRuntime 100.13

Qt Widgets C++ API integration

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 Runtime into your Qt Widgets application:

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

• qmake project files
• qmake include function
• QML import statements

Debugging your app

ArcGIS Runtime 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 Runtime API for Qt apps, a web debugging utility is often useful to capture and analyze the HTTP requests that are sent and responses that are 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. Further information can be found in Qt's QNetworkProxy documentation.

OpenGL or ANGLE rendering on Windows

Qt has two different rendering engines for the Windows platform: OpenGL and DirectX via ANGLE. By default, Qt will try to render using OpenGL. If the proper drivers are not available, it will fall back to using ANGLE for rendering. Previous releases of ArcGIS Runtime supported only ANGLE. Starting with ArcGIS Runtime 100.3.0, your apps can fully support both OpenGL and ANGLE so that you can utilize either rendering engine and Qt's fallback mechanism when OpenGL cannot be used on a given system. For more information, see Qt's documentation.

To override the default behavior to set ANGLE rendering, add the following code before the Qt application object is constructed.

1
2
3
4
#ifdef Q_OS_WIN32
    // Force usage of OpenGL ES through ANGLE on Windows
    QCoreApplication::setAttribute(Qt::AA_UseOpenGLES);
#endif

Please note that support for ANGLE is deprecated and will be removed with a future version of the software.