QML API Breaking Changes with 5.15

[LucasDanzinger]

The TL;DR Version:

If you are using any static method from the Runtime QML API (e.g., ArcGISRuntimeEnvironment.createObject(), SpatialReference.createWgs84(), GeometryEngine.project(), etc.), with version 100.8 or older, those methods will not work with Qt 5.15. The most reliable solution in this case is to use an older version of Qt, such as 5.12, 5.13, or 5.14. For upcoming releases of the software (version 100.9 and beyond), the majority of cases will begin to work again with no code changes, and a handful of cases will require a minor code change (see below). This issue does not affect the C++ API.

Background:

The Runtime QML API is written in C++ code. C++ objects become QML objects by declaring properties and methods in the C++ class and then by registering the class as a QML type. When you register the class, you must choose between making it a creatable type (one that you can declare in code, such as a FeatureLayer), an uncreatable type (one that the API can create and return to you, but you cannot instantiate in QML code, such as a GeocodeResult), or a singleton type (one that has exactly one instance in the app, such as ArcGISRuntimeEnvironment). Singleton types are Qt’s way of supporting static methods in QML. Static methods are used in the Runtime API for a few different patterns, including quick, stateless synchronous methods, such as those on the GeometryEngine, as well a factory methods used to create new objects.

The Problem:

Qt 5.15 introduced some changes to the underlying type registration where certain singleton registration workflows will no longer work. In particular, there are a handful of classes that are registered both as creatable and singleton types. For example SpatialReference can be declared or can be created using the static helper factory methods createWgs84() and createWebMercator():

// declared
SpatialReference {
   wkid: 4326
}

// created in JS with static factory method
const sr = SpatialReference.createWgs84();‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Registering a type as both creatable and as a singleton is no longer supported with Qt 5.15, and therefore we had to introduce some new API and re-architect our internals to better handle the new patterns.

The Solution

For 100.8 and previous releases, the only reliable solution is to continue to use Qt 5.12, 5.13, or 5.14.

For the upcoming 100.9 release and beyond, the majority of static functions will begin to work again automatically, with no code changes. The following are the exceptions that will not begin to work automatically and will require code changes. The new pattern is to add "Factory." in front of each of the following static functions:

SpatialReference.createWgs84 -> Factory.SpatialReference.createWgs84
SpatialReference.createWebMercator -> Factory.SpatialReference.createWebMercator
LineSegment.createLineAtAngleFromStartPoint -> Factory.LineSegment.createLineAtAngleFromStartPoint
KmlViewpoint.createCameraViewpoint -> Factory.KmlViewpoint.createCameraViewpoint
KmlViewpoint.createLookAtViewpoint -> Factory.KmlViewpoint.createLookAtViewpoint
KmlViewpoint.createWithViewpoint -> Factory.KmlViewpoint.createWithViewpoint
TransformationMatrix.createIdentityMatrix -> Factory.TransformationMatrix.createIdentityMatrix
TransformationMatrix.createWithQuaternionAndTranslation -> Factory.TransformationMatrix.createWithQuaternionAndTranslation
DictionarySymbolStyle.createFromFile -> Factory.DictionarySymbolStyle.createFromFile‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Here you can see the pull request we recently made to update our 100.9 samples to adopt the new pattern.

If you have any questions, please reach out to us on GeoNet and we can guide you through the transition.

- The ArcGIS Runtime SDK for Qt Development team