cpp-qml-positioning.qdoc

Go to the documentation of this file.

// Copyright (C) 2021 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
/*!
\page positioning-cpp-qml.html
\title Interfaces between C++ and QML Code in Qt Positioning
 
\brief Describes the methods used to exchange position data between C++ and QML
code.
 
\section1 Overview
 
Qt Positioning utilizes two methods to simplify exchange of position data
between C++ and QML code.
 
\target Cpp_value_integration_positioning
\section1 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 \l Q_GADGET support to \l QtQml.
The macro converts classes into a light-weight version of a \l QObject without
the required \l QObject inheritance. At the same time, it retains the reflection
capabilities of \l QMetaObject. As a result, they can be directly exposed to
QML.
 
A significant number of Position related data types were converted to
\l {Q_GADGET}s. They retain their API and value type character but have become
introspectable via \l QMetaObject.
 
The \l QML_ANONYMOUS macro is used to expose these types to the QML environment.
See the \l 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 \l QtQml. So a helper class is created for
each of them, and the \l QML_FOREIGN macro is used:
 
\code
struct QGeoCoordinateForeign
{
    Q_GADGET
    QML_FOREIGN(QGeoCoordinate)
    QML_ANONYMOUS
    QML_ADDED_IN_VERSION(5, 0)
};
\endcode
 
The above registration of Positioning types is automatically done once by the
QtPositioning QML plugin.
 
\section1 QVariant Based integration
 
This section provides information on how to integrate QGeoAddress and
QGeoLocation.
 
\section2 Address - QGeoAddress
 
The \l {QtPositioning::Address::address} {Address.address} property is used to
provide an interface between C++ and QML code.  First a pointer to an
\l {QtPositioning::}{Address} object must be obtained from C++, then the
\l {QObject::}{property()} and \l {QObject::}{setProperty()} functions must be
used to get and set the \c address property.
 
The following piece of code gets the \l QGeoAddress object from C++:
 
\snippet cpp/cppqml.cpp Address get
 
The following piece of code sets the address property of the QML object based
on a \l QGeoAddress object from C++:
 
\snippet cpp/cppqml.cpp Address set
 
 
\section2 Location - QGeoLocation
The \l {Location::location} {Location.location} property is used to provide an
interface between C++ and QML code.  First a pointer to a \l Location object
must be obtained from C++, then the \l {QObject::}{property()} and
\l {QObject::}{setProperty()} functions must be used to get and set the
\c location property.
 
The following piece of code gets the \l QGeoLocation object from C++:
 
\snippet cpp/cppqml.cpp Location get
 
The following piece of code sets the location property of the QML object based
on a \l QGeoLocation object from C++:
 
\snippet cpp/cppqml.cpp Location set
 
*/