Migrate from 100.x to 200.x

ArcGIS Runtime SDK version 100.15 is a long-term support release focused exclusively on bug fixes and minor updates. ArcGIS Maps SDKs for Native Apps version 200.x builds on the proven architecture of 100.15, and is designed to leverage the latest developer framework innovations. This topic outlines areas of the API that have undergone changes and provides guidance for re-factoring 100.x code for a 200.x app.

Support for Qt 6

ArcGIS Maps SDK for Qt version 200.0 is the first release to support Qt 6. This major release of ArcGIS Maps SDK for Qt modernizes the SDK and paves the path toward supporting newer compilers, language features, rendering engines, and more.

This move from Qt 5 to Qt 6 support has breaking changes that must be addressed to compile your app. The Qt Group has created a porting guide to aid in porting your apps. The first two steps in that guide are critically important:

1. Upgrade your app to the latest version of Qt 5.15.
2. Remove and replace deprecated APIs in your apps.

Where possible, Qt has tried to deprecate APIs that are removed at Qt 6, which gives developers an opportunity to remove their usage from apps before moving to Qt 6. To make this migration as seamless as possible, Esri has followed The Qt Group’s plan and has deprecated several classes, properties, and methods present in version 100.15 and prior versions. These deprecations have been removed from version 200.0.

In lockstep with The Qt Group, Esri recommends that you first upgrade your apps to the latest version of Qt 5.15 and ArcGIS Runtime SDK version 100.15. After upgrading, remove deprecated API usage in your apps and adopt the newer patterns. This will greatly decrease the number of compilation errors you will see when upgrading to Qt 6 and ArcGIS Maps SDK 200.x. For details on removing deprecated APIs from your apps, see the following blog:

• How to remove deprecated API usage from your Qt C++ apps

Installation and setup

Qt 6 installers now have more fine-grained control than earlier installers over which Qt modules are installed. When installing Qt 6 on your system, ensure that you have the following “Additional Libraries” selected, because they are required dependencies of ArcGIS Maps SDK for Qt:

• Qt Multimedia
• Qt Positioning
• Qt Sensors
• Qt WebEngine
• Qt WebView
• Qt Connectivity (iOS and Android only)
• Qt WebSockets

See System Requirements for specific versions of software needed for each supported platform.

API Breaking Changes

In addition to removing deprecated APIs from your apps, version 200.0 has a targeted set of changes that may result in additional breaking changes in your applications. These changes were necessary due to underlying Qt changes or due to API patterns that were inconsistent, incorrect, error prone, or going against best practices. In general, these changes could not be deprecated in an earlier release due to their nature.

• C++ API headers are now standardized to use forward declarations throughout the API, to improve build times and follow C++ best practices. This change will require developers to update apps to include the types they are using in their apps. In prior releases, API headers over-included other headers, resulting in client apps needing fewer includes, but at the cost of a build times. With this change, our testing showed build time reductions ranging from 16 to 33 percent for projects of different breadth and depth. Times may vary depending on a variety of factors, such as how extensive your usage of ArcGIS Maps SDK is (how many headers you have included). See this Toolkit pull request for the types of changes needed.

• All enums are now registered using Q_DECLARE_METATYPE, which makes enum usage easier throughout Qt. If you previously added these declarations in your app code, the duplicate registration needs to be removed.
• Base-class copy constructors are now marked as explicit. This primarily affects geometry types. See this Sample pull request for example migration. Previously, the following code was allowed: Point p = Geometry::fromJson("{\"x\":0,\"y\":0}");. The downside is that this allowed invalid workflows, such as creating an Envelope from Point JSON. For example: Envelope e = Geometry::fromJson("{\"x\":0,\"y\":0}");.
• TravelMode is no longer a QObject. It is a value object and was previously inadvertently marked as a QObject.
• Single argument value object constructors are now marked as explicit. For example, SpatialReference(int wkid) is now explicit, which means passing an int into a function that requires a SpatialReference object will no longer implicitly convert.
• Signal arguments have been standardized to be const-ref throughout.
• BookmarkListModel::bookmarkRemoved is removed. Use BookmarkListModel::itemRemoved instead.
• ClassBreakListModel::classBreakRemoved is removed. Use ClassBreakListModel::itemRemoved instead.
• PreplannedMapArea::contentItemsCompleted is removed. Access items in PreplannedMapArea::packageItems instead.
• Job::cancel is removed. Use Job::cancelAsync instead.
• The following classes are no longer inadvertently declared as metatypes: FeatureEditResult, FeatureTableEditResult, GenerateOfflineMapParameterOverrides, GeoElement, Graphic, IdentifyGraphicsOverlayResult, IdentifyLayerResult, RelatedFeatureQueryResult. These can be registered in client code instead using qRegisterMetaType.

ArcGIS Extras API

• System.isOnline is removed and System.reachability is added. isOnline supplied a simple boolean, while reachability supplies more fine-grained information about a device's connection status. This is following Qt's change with QNetworkInformation reachability.
• QExifImageHeader no longer supports JIS X208-1990 codec due to a change in Qt.

Qt 6 changes that affect common ArcGIS Maps SDK use cases

• QML import versions are now completely optional. For simplicity, we recommend removing version numbers from your QML import statements. For example, change import Esri.ArcGISRuntime 100.15 to import Esri.ArcGISRuntime.

• Some Qt Modules have not been ported to Qt 6 yet, such as Graphical Effects. The core5compat library can be used to aid in migration for some missing modules (see Porting from Qt 5 to Qt 6 using Qt5Compat library). Other missing modules, such as QTextToSpeech, are planned for upcoming Qt releases.

• QMouseEvent APIs, which are used in GeoView onMouseClicked signals, have changed. For example, use mouse.pos().x() instead of mouse.x().

• Use Q_MOC_INCLUDE to tell the Meta Object Compiler (MOC) to add an include when you’ve forward declared types used in properties, signals, and slots. For example, you must add Q_MOC_INCLUDE(“MapQuickView.h”) to your header if exposing MapQuickView as a Q_PROPERTY.

• QML signals must name parameters used in the handler. For example, onMouseClicked: { … } will become onMouseClicked: (mouse)=>{ … }. For more details, see the Qt documentation Signal parameters.

• The Toolkit pull request and the Sample pull request presented for porting from Qt 5 to Qt 6 can be used as a reference for the most common changes required for migrating your ArcGIS Maps SDK for Qt app from Qt 5 to Qt 6.