QtPositioning: improve satelliteinfo example

Register model for QML using QML_ELEMENT.
Improve the example documentation.

Task-number: QTBUG-89855
Change-Id: I88abccecbba446332501ddb787cf4bbb8d0d8058
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>
Reviewed-by: Alex Blasche <alexander.blasche@qt.io>

7 files changed, 95 insertions, 12 deletions

diff --git a/examples/positioning/satelliteinfo/CMakeLists.txt b/examples/positioning/satelliteinfo/CMakeLists.txt
index 9e0bdebf..092bf290 100644
--- a/examples/positioning/satelliteinfo/CMakeLists.txt
+++ b/examples/positioning/satelliteinfo/CMakeLists.txt
@@ -53,3 +53,9 @@ install(TARGETS satelliteinfo
     BUNDLE DESTINATION "${INSTALL_EXAMPLEDIR}"
     LIBRARY DESTINATION "${INSTALL_EXAMPLEDIR}"
 )
+
+set_target_properties(satelliteinfo PROPERTIES
+    QT_QML_MODULE_VERSION 1.0
+    QT_QML_MODULE_URI Local
+)
+qt6_qml_type_registration(satelliteinfo)
diff --git a/examples/positioning/satelliteinfo/doc/src/satelliteinfo.qdoc b/examples/positioning/satelliteinfo/doc/src/satelliteinfo.qdoc
index 54c30201..2136c440 100644
--- a/examples/positioning/satelliteinfo/doc/src/satelliteinfo.qdoc
+++ b/examples/positioning/satelliteinfo/doc/src/satelliteinfo.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2017 The Qt Company Ltd.
+** Copyright (C) 2021 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the documentation of the Qt Toolkit.
@@ -29,7 +29,7 @@
     \example satelliteinfo
     \title SatelliteInfo (C++/QML)
 
-    \brief The SatelliteInfo example shows how the available satellites
+    \brief The SatelliteInfo example shows the available satellites
     at the user's current position and marks the satellites
     currently contributing to the GPS fix as pink.
 
@@ -44,9 +44,10 @@
 
     \image ../images/example-satelliteinfo.png
 
-    The example displays the signal strength of all satellites in view. Any satellite
-    that is currently used to calculate the GPS fix has been marked pink. The number at
-    the bottom of each signal bar is the individual satellite identifier.
+    The example displays the signal strength of all satellites in view. Any
+    satellite that is currently used to calculate the GPS fix is marked pink.
+    The number at the bottom of each signal bar is the individual satellite
+    identifier.
 
     The application operates in three different modes:
 
@@ -67,9 +68,69 @@
                 remains empty until the request was answered by the system.
     \endtable
 
-    If the platform does not provide satellite information the application automatically
-    switches into a demo mode whereby it continuously switches between predefined
-    sets of satellite data.
+    If the platform does not provide satellite information, the application
+    automatically switches into a demo mode, whereby it continuously switches
+    between predefined sets of satellite data.
 
     \include examples-run.qdocinc
+
+    \section1 Satellite Info Model
+
+    The key part of this example is the \c SatelliteModel data model. It
+    represents the information about the satellites.
+    It uses the \l Q_PROPERTY and \l QML_ELEMENT macros, so that it can be
+    available from QML.
+
+    \snippet satelliteinfo/satellitemodel.h 0
+    \snippet satelliteinfo/satellitemodel.h 1
+    \snippet satelliteinfo/satellitemodel.h 2
+
+    The \c SatelliteModel object creates an instance of
+    \l QGeoSatelliteInfoSource using the \l {QGeoSatelliteInfoSource::}
+    {createDefaultSource()} method. Once the source is created, the
+    \l {QGeoSatelliteInfoSource::}{satellitesInViewUpdated()} and
+    \l {QGeoSatelliteInfoSource::}{satellitesInUseUpdated()} signals are used
+    to notify about the changes in satellite information.
+
+    \snippet satelliteinfo/satellitemodel.cpp 0
+
+    The aforementioned signals provide the lists of \l QGeoSatelliteInfo
+    objects that represent satellites in view and satellites in use,
+    respectively. This data is used to update the model.
+
+    \snippet satelliteinfo/satellitemodel.cpp 1
+
+    If the satellite info source is not available, demo data is used to simulate
+    satellite information updates.
+
+    \snippet satelliteinfo/satellitemodel.cpp 2
+
+    The model is later used in QML to visualize the data.
+
+    \section1 Exposing the Model to QML
+
+    To expose \c SatelliteModel to QML, we use the \l QML_ELEMENT macro.
+    See the \l QQmlEngine class documentation for more details on it.
+
+    To make the type available in QML, we need to update our build accordingly.
+
+    \section2 CMake Build
+
+    For a CMake-based build, we need to add the following to the
+    \c {CMakeLists.txt}:
+
+    \quotefromfile satelliteinfo/CMakeLists.txt
+    \skipto set_target_properties
+    \printuntil PROPERTIES
+    \skipto QT_QML_MODULE_VERSION 1.0
+    \printuntil qt6_qml_type_registration(satelliteinfo)
+
+    \section2 qmake Build
+
+    For a qmake build, we need to modify the \c {satelliteinfo.pro} file in the
+    following way:
+
+    \quotefromfile satelliteinfo/satelliteinfo.pro
+    \skipto CONFIG
+    \printuntil QML_IMPORT_MAJOR_VERSION
 */
diff --git a/examples/positioning/satelliteinfo/main.cpp b/examples/positioning/satelliteinfo/main.cpp
index feeb12ad..4a96c4c9 100644
--- a/examples/positioning/satelliteinfo/main.cpp
+++ b/examples/positioning/satelliteinfo/main.cpp
@@ -57,7 +57,6 @@
 int main(int argc, char *argv[])
 {
     QGuiApplication app(argc, argv);
-    qmlRegisterType<SatelliteModel>("Local", 1, 0, "SatelliteModel");
 
     QQuickView view;
     view.setSource(QStringLiteral("qrc:///satelliteinfo.qml"));
diff --git a/examples/positioning/satelliteinfo/satelliteinfo.pro b/examples/positioning/satelliteinfo/satelliteinfo.pro
index 4aef9d0e..ebee0945 100644
--- a/examples/positioning/satelliteinfo/satelliteinfo.pro
+++ b/examples/positioning/satelliteinfo/satelliteinfo.pro
@@ -3,6 +3,10 @@ TARGET = satelliteinfo
 
 QT += quick positioning
 
+CONFIG += qmltypes
+QML_IMPORT_NAME = Local
+QML_IMPORT_MAJOR_VERSION = 1
+
 SOURCES += main.cpp \
     satellitemodel.cpp
 
diff --git a/examples/positioning/satelliteinfo/satelliteinfo.qml b/examples/positioning/satelliteinfo/satelliteinfo.qml
index a0269e22..ef0c965e 100644
--- a/examples/positioning/satelliteinfo/satelliteinfo.qml
+++ b/examples/positioning/satelliteinfo/satelliteinfo.qml
@@ -59,7 +59,9 @@ Rectangle {
     SatelliteModel {
         id: satelliteModel
         running: true
-        onErrorFound: errorLabel.text = qsTr("Last Error: %1", "%1=error number").arg(code)
+        onErrorFound: function(code) {
+            errorLabel.text = qsTr("Last Error: %1", "%1=error number").arg(code)
+        }
     }
 
     Item {
diff --git a/examples/positioning/satelliteinfo/satellitemodel.cpp b/examples/positioning/satelliteinfo/satellitemodel.cpp
index 373cd604..77c89035 100644
--- a/examples/positioning/satelliteinfo/satellitemodel.cpp
+++ b/examples/positioning/satelliteinfo/satellitemodel.cpp
@@ -52,6 +52,7 @@
 #include <QTimer>
 #include <QDebug>
 
+//! [0]
 SatelliteModel::SatelliteModel(QObject *parent) :
     QAbstractListModel(parent), source(0), m_componentCompleted(false), m_running(false),
     m_runningRequested(false), demo(false), isSingle(false), singleRequestServed(false)
@@ -77,6 +78,7 @@ SatelliteModel::SatelliteModel(QObject *parent) :
         timer->start(3000);
     }
 }
+//! [0]
 
 int SatelliteModel::rowCount(const QModelIndex &parent) const
 {
@@ -221,6 +223,7 @@ void SatelliteModel::clearModel()
     endResetModel();
 }
 
+//! [2]
 void SatelliteModel::updateDemoData()
 {
     static bool flag = true;
@@ -254,6 +257,7 @@ void SatelliteModel::updateDemoData()
         setRunning(false);
     }
 }
+//! [2]
 
 void SatelliteModel::error(QGeoSatelliteInfoSource::Error error)
 {
@@ -267,6 +271,7 @@ inline bool operator<(const QGeoSatelliteInfo& a, const QGeoSatelliteInfo& b)
 }
 QT_END_NAMESPACE
 
+//! [1]
 void SatelliteModel::satellitesInViewUpdated(const QList<QGeoSatelliteInfo> &infos)
 {
     if (!running())
@@ -316,4 +321,4 @@ void SatelliteModel::satellitesInUseUpdated(const QList<QGeoSatelliteInfo> &info
 
     endResetModel();
 }
-
+//! [1]
diff --git a/examples/positioning/satelliteinfo/satellitemodel.h b/examples/positioning/satelliteinfo/satellitemodel.h
index 0b6cf6b1..18d94a59 100644
--- a/examples/positioning/satelliteinfo/satellitemodel.h
+++ b/examples/positioning/satelliteinfo/satellitemodel.h
@@ -60,6 +60,7 @@
 QT_FORWARD_DECLARE_CLASS(QTimer)
 QT_FORWARD_DECLARE_CLASS(QGeoSatelliteInfoSource)
 
+//! [0]
 class SatelliteModel : public QAbstractListModel, public QQmlParserStatus
 {
     Q_OBJECT
@@ -68,6 +69,7 @@ class SatelliteModel : public QAbstractListModel, public QQmlParserStatus
     Q_PROPERTY(int entryCount READ entryCount NOTIFY entryCountChanged)
     Q_PROPERTY(bool singleRequestMode READ isSingleRequest WRITE setSingleRequest NOTIFY singleRequestChanged)
     Q_INTERFACES(QQmlParserStatus)
+    QML_ELEMENT
 public:
     explicit SatelliteModel(QObject *parent = 0);
 
@@ -87,6 +89,7 @@ public:
     //From QQmlParserStatus
     void classBegin() override {}
     void componentComplete() override;
+//! [0]
 
     bool running() const;
     void setRunning(bool isActive);
@@ -98,6 +101,7 @@ public:
 
     bool canProvideSatelliteInfo() const;
 
+//! [1]
 signals:
     void runningChanged();
     void entryCountChanged();
@@ -108,6 +112,7 @@ signals:
 public slots:
     void clearModel();
     void updateDemoData();
+//! [1]
 
 private slots:
     void error(QGeoSatelliteInfoSource::Error);
@@ -126,8 +131,9 @@ private:
     QTimer *timer;
     bool isSingle;
     bool singleRequestServed;
-
+//! [2]
 };
+//! [2]
 
 QML_DECLARE_TYPE(SatelliteModel)