Changes to Qt Positioning

Qt 6 is a result of the conscious effort to make the framework more efficient and easy to use.

We try to maintain binary and source compatibility for all the public APIs in each release. But some changes were inevitable in an effort to make Qt a better framework.

In this topic we summarize those changes in Qt Positioning, and provide guidance to handle them.

Breaking public API changes

This section contains information about API changes that break source compatibility.

Rename QGeoPolygon::path()

The QGeoPolygon::path() and QGeoPolygon::setPath() methods are renamed to QGeoPolygon::perimeter() and QGeoPolygon::setPerimeter() respectively. On the QML side the QGeoPolygon::perimeter property can be used without any changes.

Use QGeoShape for QGeoLocation bounding area

The QGeoLocation class and its Location QML counterpart are updated to use QGeoShape instead of QGeoRectangle for a bounding area.

C++

The QGeoLocation::boundingBox() and QGeoLocation::setBoundingBox() are replaced by QGeoLocation::boundingShape() and QGeoLocation::setBoundingShape() respectively. A QGeoShape object is now used as an underlying data storage.

QML

The QGeoLocation::boundingBox property is replaced by QGeoLocation::boundingShape. This property is available since QtPositioning 6.2, so make sure to update the import version in the QML files.

 import QtPositioning 6.2

Remove QGeoShape::extendShape()

The QGeoShape::extendShape() method was deprecated in Qt 5.9 and finally removed in Qt 6. Use QGeoRectangle::extendRectangle() and QGeoCircle::extendCircle() if you need this functionality for these classes.

Rename signal error to errorOccurred

In Qt 5 multiple Qt Positioning classes had the error() signal, which was clashing with the error() method. In Qt 6 we renamed these signals to errorOccurred(). Specifically:

QGeoAreaMonitorSource::error() is renamed to QGeoAreaMonitorSource::errorOccurred().
QGeoPositionInfoSource::error() is renamed to QGeoPositionInfoSource::errorOccurred().
QGeoSatelliteInfoSource::error() is renamed to QGeoSatelliteInfoSource::errorOccurred().

Remove update timeout signals

In Qt 5 QGeoPositionInfoSource::updateTimeout() and QGeoSatelliteInfoSource::requestTimeout() signals were used to notify about the cases when the current position or satellite information could not be retrieved within specified timeout. These signals were removed in Qt 6. The errorOccurred() signals with the new error types are used instead. Specifically:

QGeoPositionInfoSource uses an errorOccurred() signal with a new QGeoPositionInfoSource::UpdateTimeoutError error code.
QGeoSatelliteInfoSource uses an errorOccurred() signal with a new QGeoSatelliteInfoSource::UpdateTimeoutError error code.

Same changes apply to PositionSource QML object. The PositionSource::updateTimeout() signal is removed. PositionSource::sourceError property with a PositionSource.UpdateTimeoutError is used instead.

Redesign NMEA support

In Qt 5 we had a serialnmea positioning plugin and a nmeaSource property in PositionSource object.

The plugin provided access to NMEA streams via serial port, while the QML object was responsible for reading NMEA stream from TCP socket or local file.

In Qt 6 we joined all these features in the plugin, which is now renamed to nmea. It is now capable of working with all three NMEA data sources: serial port, TCP socket and local file. See plugin description for more details.

The nmeaSource property of PositionSource object is now removed.

Other API changes

This section contains API improvements that do not break source compatibility. However they might have an impact on the application logic, so it is still useful to know about them.

Reset errors properly

In Qt 5 the errors for QGeoAreaMonitorSource, QGeoPositionInfoSource and QGeoSatelliteInfoSource classes were never reset. This behavior is not logical, as calling startUpdates(), startMonitoring() or requestUpdates() on one of these classes or their subclasses effectively means starting a new work sessions, which means that we should not care about previous errors. Since Qt 6 we reset the error to NoError once one of the aforementioned methods is called.

Add QGeoAddress::streetNumber

The QGeoAddress class is extended with streetNumber property, which holds the information about street number, building name, or anything else that might be used to distinguish one address from another. Use streetNumber() and setStreetNumber() to access this property from C++ code.

The QGeoAddress::street now holds only the street name.

Same applies to Address QML counterpart. The Address::street property is now used only for street name, while the Address::streetNumber property is used for other important address details.

Add timeout argument to PositionSource::update()

The timeout is specified in milliseconds. If the timeout is zero (the default value), it defaults to a reasonable timeout period as appropriate for the source.

Refactor QGeoSatelliteInfo, QGeoPositionInfo and QGeoAreaMonitorInfo classes

These classes now use QExplicitlySharedDataPointer in their implementation. It means that the classes implement copy-on-write. It makes them cheap to copy, so that they can be passed by value.

Another improvement is the addition of support for the efficient move operations.

Changes in Qt Positioning plugin implementation

This section provides information about the changes in plugin interface.

In Qt 5 for we had two versions of plugin interface:

QGeoPositionInfoSourceFactory which provided the basic features.
QGeoPositionInfoSourceFactoryV2 which extended the base class with the possibility to provide custom parameters for the created objects.

In Qt 6 we merged these two implementations into one, leaving only the QGeoPositionInfoSourceFactory class. Its methods now allow to pass custom parameters.

Note: The interface identifier is updated to reflect the major version update. Use "org.qt-project.qt.position.sourcefactory/6.0" in your Qt Positioning plugins.

Here is an example of plugin class declaration:

 class MyPlugin : public QObject, public QGeoPositionInfoSourceFactory
 {
     Q_OBJECT
     Q_PLUGIN_METADATA(IID "org.qt-project.qt.position.sourcefactory/6.0"
                       FILE "plugin.json")
     Q_INTERFACES(QGeoPositionInfoSourceFactory)

 public:
     QGeoPositionInfoSource *positionInfoSource(QObject *parent, const QVariantMap &parameters) override;
     QGeoSatelliteInfoSource *satelliteInfoSource(QObject *parent, const QVariantMap &parameters) override;
     QGeoAreaMonitorSource *areaMonitor(QObject *parent, const QVariantMap &parameters) override;
 };

Contents