Interfaces between C++ and QML Code in Qt Positioning

Overview

Qt Positioning utilizes two methods to simplify exchange of position data between C++ and QML code.

Direct C++ Value Integration in QtPositioning

Starting with Qt 5.5, it has become much easier to integrate non-QObject based data types into QML. This is achieved by adding Q_GADGET support to QtQml. The macro converts classes into a light-weight version of a QObject without the required QObject inheritance. At the same time, it retains the reflection capabilities of QMetaObject. As a result, they can be directly exposed to QML.

A significant number of Position related data types were converted to Q_GADGETs. They retain their API and value type character but have become introspectable via QMetaObject.

The QML_ANONYMOUS macro is used to expose these types to the QML environment. See the QQmlEngine documentation for more details and the full list of available macros.

The classes, however, are not directly extended with this macro, because we do not want Qt Positioning to depend on QtQml. So a helper class is created for each of them, and the QML_FOREIGN macro is used:

struct QGeoCoordinateForeign
{
    Q_GADGET
    QML_FOREIGN(QGeoCoordinate)
    QML_ANONYMOUS
    QML_ADDED_IN_VERSION(5, 0)
};

The above registration of Positioning types is automatically done once by the QtPositioning QML plugin.

QVariant Based integration

This section provides information on how to integrate QGeoAddress and QGeoLocation.

Address - QGeoAddress

The Address.address property is used to provide an interface between C++ and QML code. First a pointer to an Address object must be obtained from C++, then the property() and setProperty() functions must be used to get and set the address property.

The following piece of code gets the QGeoAddress object from C++:

 QGeoAddress geoAddress = qmlObject->property("address").value<QGeoAddress>();

The following piece of code sets the address property of the QML object based on a QGeoAddress object from C++:

qmlObject->setProperty("address", QVariant::fromValue(geoAddress));

Location - QGeoLocation

The Location.location property is used to provide an interface between C++ and QML code. First a pointer to a Location object must be obtained from C++, then the property() and setProperty() functions must be used to get and set the location property.

The following piece of code gets the QGeoLocation object from C++:

QGeoLocation geoLocation = qmlObject->property("location").value<QGeoLocation>();

The following piece of code sets the location property of the QML object based on a QGeoLocation object from C++:

qmlObject->setProperty("location", QVariant::fromValue(geoLocation));