1// Copyright (C) 2021 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
5 \page qtpositioning-changes-qt6.html
6 \title Changes to Qt Positioning
7 \ingroup changes-qt-5-to-6
8 \brief Migrate Qt Positioning to Qt 6.
10 Qt 6 is a result of the conscious effort to make the framework more
11 efficient and easy to use.
13 We try to maintain binary and source compatibility for all the public
14 APIs in each release. But some changes were inevitable in an effort to
15 make Qt a better framework.
17 In this topic we summarize those changes in Qt Positioning, and provide
18 guidance to handle them.
20 \section1 Breaking public API changes
22 This section contains information about API changes that break source
25 \section2 Rename QGeoPolygon::path()
27 The \c QGeoPolygon::path() and \c QGeoPolygon::setPath() methods are renamed
28 to \l QGeoPolygon::perimeter() and \l QGeoPolygon::setPerimeter()
29 respectively. On the QML side the \l QGeoPolygon::perimeter property can be
30 used without any changes.
32 \section2 Use \l QGeoShape for \l QGeoLocation bounding area
34 The \l QGeoLocation class and its \l [QML] Location QML counterpart are
35 updated to use \l QGeoShape instead of \l QGeoRectangle for a bounding area.
39 The \c QGeoLocation::boundingBox() and \c QGeoLocation::setBoundingBox()
40 are replaced by \l QGeoLocation::boundingShape() and
41 \l QGeoLocation::setBoundingShape() respectively. A \l QGeoShape object
42 is now used as an underlying data storage.
46 The \c QGeoLocation::boundingBox property is replaced by
47 \l QGeoLocation::boundingShape. This property is available since
48 QtPositioning 6.2, so make sure to update the import version in the QML
52 import QtPositioning 6.2
55 \section2 Remove QGeoShape::extendShape()
57 The \c QGeoShape::extendShape() method was deprecated in Qt 5.9 and finally
58 removed in Qt 6. Use \l QGeoRectangle::extendRectangle() and
59 \l QGeoCircle::extendCircle() if you need this functionality for these
62 \section2 Rename signal error to errorOccurred
64 In Qt 5 multiple Qt Positioning classes had the \c error() signal, which was
65 clashing with the \c error() method. In Qt 6 we renamed these signals to
66 \c errorOccurred(). Specifically:
70 \li \c QGeoAreaMonitorSource::error() is renamed to
71 \l QGeoAreaMonitorSource::errorOccurred().
73 \li \c QGeoPositionInfoSource::error() is renamed to
74 \l QGeoPositionInfoSource::errorOccurred().
76 \li \c QGeoSatelliteInfoSource::error() is renamed to
77 \l QGeoSatelliteInfoSource::errorOccurred().
81 \section2 Remove update timeout signals
83 In Qt 5 \c {QGeoPositionInfoSource::updateTimeout()} and
84 \c {QGeoSatelliteInfoSource::requestTimeout()} signals were used to notify
85 about the cases when the current position or satellite information could
86 not be retrieved within specified timeout. These signals were removed in
87 Qt 6. The \c {errorOccurred()} signals with the new error types are
88 used instead. Specifically:
92 \li \l QGeoPositionInfoSource uses an \l {QGeoPositionInfoSource::}
93 {errorOccurred()} signal with a new
94 \l QGeoPositionInfoSource::UpdateTimeoutError error code.
96 \li \l QGeoSatelliteInfoSource uses an \l {QGeoSatelliteInfoSource::}
97 {errorOccurred()} signal with a new
98 \l QGeoSatelliteInfoSource::UpdateTimeoutError error code.
102 Same changes apply to \l [QML] PositionSource QML object. The
103 \c {PositionSource::updateTimeout()} signal is removed.
104 \l [QML] {PositionSource::sourceError} property with a
105 \c {PositionSource.UpdateTimeoutError} is used instead.
107 \section2 Redesign NMEA support
109 In Qt 5 we had a \b serialnmea positioning plugin and a \c nmeaSource
110 property in \l [QML] {PositionSource} object.
112 The plugin provided access to NMEA streams via serial port, while the QML
113 object was responsible for reading NMEA stream from TCP socket or local
116 In Qt 6 we joined all these features in the plugin, which is now renamed to
117 \b nmea. It is now capable of working with all three NMEA data sources:
118 serial port, TCP socket and local file. See \l {Qt Positioning NMEA plugin}
119 {plugin description} for more details.
121 The \c nmeaSource property of \l [QML] {PositionSource} object is now
124 \section1 Other API changes
126 This section contains API improvements that do not break source
127 compatibility. However they might have an impact on the application logic,
128 so it is still useful to know about them.
130 \section2 Reset errors properly
132 In Qt 5 the errors for \l QGeoAreaMonitorSource, \l QGeoPositionInfoSource
133 and \l QGeoSatelliteInfoSource classes were never reset. This behavior is
134 not logical, as calling \c {startUpdates()}, \c {startMonitoring()} or
135 \c {requestUpdates()} on one of these classes or their subclasses
136 effectively means starting a new work sessions, which means that we should
137 not care about previous errors. Since Qt 6 we reset the error to \c NoError
138 once one of the aforementioned methods is called.
140 \section2 Add \l QGeoAddress::streetNumber
142 The \l QGeoAddress class is extended with \l {QGeoAddress::}{streetNumber}
143 property, which holds the information about street number, building name, or
144 anything else that might be used to distinguish one address from another.
145 Use \l {QGeoAddress::}{streetNumber()} and \l {QGeoAddress::}
146 {setStreetNumber()} to access this property from C++ code.
148 The \l QGeoAddress::street now holds only the street name.
150 Same applies to \l [QML] {Address} QML counterpart. The \l [QML]
151 {Address::street} property is now used only for street name, while the
152 \l [QML] {Address::streetNumber} property is used for other important
155 \section2 Add timeout argument to \l [QML] {PositionSource::update()}
157 The \c timeout is specified in milliseconds. If the \c timeout is zero
158 (the default value), it defaults to a reasonable timeout period as
159 appropriate for the source.
161 \section2 Refactor \l QGeoSatelliteInfo, \l QGeoPositionInfo and \l QGeoAreaMonitorInfo classes
163 These classes now use \l QExplicitlySharedDataPointer in their
164 implementation. It means that the classes implement copy-on-write. It makes
165 them cheap to copy, so that they can be passed by value.
167 Another improvement is the addition of support for the efficient move
170 \section1 Changes in Qt Positioning plugin implementation
172 This section provides information about the changes in plugin interface.
174 In Qt 5 for we had two versions of plugin interface:
178 \li \c QGeoPositionInfoSourceFactory which provided the basic features.
179 \li \c QGeoPositionInfoSourceFactoryV2 which extended the base class with
180 the possibility to provide custom parameters for the created objects.
184 In Qt 6 we merged these two implementations into one, leaving only the
185 \l QGeoPositionInfoSourceFactory class. Its methods now allow to pass
188 \note The interface \e identifier is updated to reflect the major version
189 update. Use \c {"org.qt-project.qt.position.sourcefactory/6.0"} in your
190 Qt Positioning plugins.
192 Here is an example of plugin class declaration:
195 class MyPlugin : public QObject, public QGeoPositionInfoSourceFactory
198 Q_PLUGIN_METADATA(IID "org.qt-project.qt.position.sourcefactory/6.0"
200 Q_INTERFACES(QGeoPositionInfoSourceFactory)
203 QGeoPositionInfoSource *positionInfoSource(QObject *parent, const QVariantMap ¶meters) override;
204 QGeoSatelliteInfoSource *satelliteInfoSource(QObject *parent, const QVariantMap ¶meters) override;
205 QGeoAreaMonitorSource *areaMonitor(QObject *parent, const QVariantMap ¶meters) override;