From cee1591ffce5ba923375144108075fffd3ea70a7 Mon Sep 17 00:00:00 2001 From: Alex Blasche Date: Wed, 22 Apr 2015 13:13:10 +0200 Subject: Shift generic docs away from planespotter example MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit They are more general and are linked to from other pages too. Change-Id: I828008e3692a593bf9343346508b9c0ad8183108 Task-number: QTBUG-45415 Reviewed-by: Topi Reiniö Reviewed-by: Venugopal Shivashankar --- src/location/doc/src/examples/planespotter.qdoc | 42 +++++------------------ src/positioning/doc/qtpositioning.qdocconf | 2 +- src/positioning/doc/src/cpp-qml-positioning.qdoc | 43 ++++++++++++++++++++++++ src/positioning/qgeocircle.cpp | 3 +- src/positioning/qgeocoordinate.cpp | 3 +- src/positioning/qgeorectangle.cpp | 3 +- src/positioning/qgeoshape.cpp | 3 +- 7 files changed, 60 insertions(+), 39 deletions(-) diff --git a/src/location/doc/src/examples/planespotter.qdoc b/src/location/doc/src/examples/planespotter.qdoc index 991e83c4..a07eb96a 100644 --- a/src/location/doc/src/examples/planespotter.qdoc +++ b/src/location/doc/src/examples/planespotter.qdoc @@ -48,40 +48,14 @@ \include examples-run.qdocinc - \section1 Integrating C++ Data Structures - - 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 QtQml. - The macro converts classes into a light-weight - version of a QObject without the required \l QObject inheritance but retains - the reflection capabilities of \l QMetaObject. As a result they can be directly - exposed to QML and do not require any further wrapper classes. - - To make use of this new development a significant number of Position and Location - related data types were converted to Q_GADGETs. They retain their API and value - type character but have become introspectable via \l QMetaObject. This conversion - was done to the following classes: - - \list - \li \l QGeoCircle - \li \l QGeoCoordinate - \li \l QGeoRectangle - \li \l QGeoShape - \endlist - - Using \l QGeoCoordinate as an example, the C++ types are directly exposed to the - QML environment via its meta type: - - \code - qRegisterMetaType(); - QMetaType::registerEqualsComparator(); - \endcode - - The above registration of \l QGeoCoordinate is automatically done once by the - QtPositioning QML plugin. - - This example makes use of the feature as part of its position controller - implementation. The main purpose of the class is to track the current + \section1 Overview + + + This example makes use of the \l Q_GADGET feature as part of its position controller + implementation. It permits \l {Cpp_value_integration_positioning}{direct integration} + of non-QObject based C++ value types into QML. + + The main purpose of the \c PlaneController class is to track the current coordinates of the plane at a given time. It exposes the position via its position property. diff --git a/src/positioning/doc/qtpositioning.qdocconf b/src/positioning/doc/qtpositioning.qdocconf index ae258bb4..608b30a1 100644 --- a/src/positioning/doc/qtpositioning.qdocconf +++ b/src/positioning/doc/qtpositioning.qdocconf @@ -32,7 +32,7 @@ qhp.QtPositioning.subprojects.examples.selectors = fake:example tagfile = ../../../doc/qtpositioning/qtpositioning.tags -depends += qtcore qtdoc qtquick qtqml qtnetwork +depends += qtcore qtdoc qtquick qtqml qtnetwork qtlocation headerdirs += .. \ ../../imports/positioning diff --git a/src/positioning/doc/src/cpp-qml-positioning.qdoc b/src/positioning/doc/src/cpp-qml-positioning.qdoc index 77ada78a..9245c171 100644 --- a/src/positioning/doc/src/cpp-qml-positioning.qdoc +++ b/src/positioning/doc/src/cpp-qml-positioning.qdoc @@ -31,6 +31,49 @@ \brief Some of the providing QtPositioning QML types providing interfaces to access and modify properties in C++. +\section1 Overview + +Depending on the type of C++ class QtPositioning 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 QtQml. +The macro converts classes into a light-weight +version of a 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 and do not require any further wrapper classes. + +A significant number of Position and Location +related data types were converted to Q_GADGETs. They retain their API and value +type character but have become introspectable via \l QMetaObject. This conversion +was done to the following classes: + +\list +\li \l QGeoCircle +\li \l QGeoCoordinate +\li \l QGeoRectangle +\li \l QGeoShape +\endlist + +Using \l QGeoCoordinate as an example, the C++ types are directly exposed to the +QML environment via its meta type: + +\code + qRegisterMetaType(); + QMetaType::registerEqualsComparator(); +\endcode + +The above registration of \l QGeoCoordinate is automatically done once by the +QtPositioning QML plugin. The \l{Plane Spotter (QML)}{Plane Spotter} example demonstrates +this feature. + +\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 a Address object must be obtained from C++, then use the \l {QObject::property()}{property()} and diff --git a/src/positioning/qgeocircle.cpp b/src/positioning/qgeocircle.cpp index 7201b46b..6b5b24fd 100644 --- a/src/positioning/qgeocircle.cpp +++ b/src/positioning/qgeocircle.cpp @@ -56,7 +56,8 @@ QT_BEGIN_NAMESPACE The circle is considered invalid if the center coordinate is invalid or if the radius is less than zero. - This class is a \l Q_GADGET since Qt 5.5. + This class is a \l Q_GADGET since Qt 5.5. It can be + \l{Cpp_value_integration_positioning}{directly used from C++ and QML}. */ /*! diff --git a/src/positioning/qgeocoordinate.cpp b/src/positioning/qgeocoordinate.cpp index ee50182f..d061562b 100644 --- a/src/positioning/qgeocoordinate.cpp +++ b/src/positioning/qgeocoordinate.cpp @@ -99,7 +99,8 @@ QGeoCoordinatePrivate::~QGeoCoordinatePrivate() Azimuth in this context is equivalent to a compass bearing based on true north. - This class is a \l Q_GADGET since Qt 5.5. + This class is a \l Q_GADGET since Qt 5.5. It can be + \l{Cpp_value_integration_positioning}{directly used from C++ and QML}. */ /*! diff --git a/src/positioning/qgeorectangle.cpp b/src/positioning/qgeorectangle.cpp index aaa1e612..2e615494 100644 --- a/src/positioning/qgeorectangle.cpp +++ b/src/positioning/qgeorectangle.cpp @@ -66,7 +66,8 @@ QT_BEGIN_NAMESPACE touches but does not cross the pole and that the center coordinate is still in the center of the geo rectangle. - This class is a \l Q_GADGET since Qt 5.5. + This class is a \l Q_GADGET since Qt 5.5. It can be + \l{Cpp_value_integration_positioning}{directly used from C++ and QML}. */ /*! diff --git a/src/positioning/qgeoshape.cpp b/src/positioning/qgeoshape.cpp index 2861eb8f..732045f9 100644 --- a/src/positioning/qgeoshape.cpp +++ b/src/positioning/qgeoshape.cpp @@ -75,7 +75,8 @@ bool QGeoShapePrivate::operator==(const QGeoShapePrivate &other) const details of the associated areas in terms of QGeoCoordinate instances and distances in meters. - This class is a \l Q_GADGET since Qt 5.5. + This class is a \l Q_GADGET since Qt 5.5. It can be + \l{Cpp_value_integration_positioning}{directly used from C++ and QML}. */ /*! -- cgit v1.2.1