Doc: Update Grue Sensor example

Fix a number of issues with the example:
    - Add \omit to generated doc sections, we don't want
      qdoc to process these (not part of Qt docs)
    - Combine the 5 separate examples into a single \example
      and discuss each subproject in a subsection
    - Add example image to doc
    - Fix deployment/build target directories and import paths
    - Define a 'reading' property for the sensor to make it work
      on QtSensors 5.1
    - Fix the Grue QML application to avoid flicker from frequent
      updates.

Task-number: QTBUG-32881
Change-Id: I2785faead1baaf5b1ae9d05df3398e018e945418
Reviewed-by: Jerome Pasion <jerome.pasion@digia.com>
Reviewed-by: Lorn Potter <lorn.potter@jollamobile.com>

11 files changed, 124 insertions, 73 deletions

diff --git a/examples/sensors/grue/console_app/console_app.pro b/examples/sensors/grue/console_app/console_app.pro
index 786d2b1..f2b627e 100644
--- a/examples/sensors/grue/console_app/console_app.pro
+++ b/examples/sensors/grue/console_app/console_app.pro
@@ -1,8 +1,11 @@
-TEMPLATE=app
-TARGET=detect_grue
+TEMPLATE = app
+TARGET = detect_grue
 CONFIG += console
-QT=core sensors
-SOURCES=main.cpp
+QT = core sensors
 
-target.path = $$[QT_INSTALL_EXAMPLES]/qtsensors/grue
+DESTDIR = $$OUT_PWD/..
+
+SOURCES = main.cpp
+
+target.path = $$[QT_INSTALL_EXAMPLES]/sensors/grue
 INSTALLS += target
diff --git a/examples/sensors/grue/doc/images/qtsensors-examples-grue.png b/examples/sensors/grue/doc/images/qtsensors-examples-grue.png
new file mode 100644
index 0000000..81b3725
--- /dev/null
+++ b/examples/sensors/grue/doc/images/qtsensors-examples-grue.png
diff --git a/examples/sensors/grue/doc/src/grue.qdoc b/examples/sensors/grue/doc/src/grue.qdoc
index 9a0d447..32cfb7f 100644
--- a/examples/sensors/grue/doc/src/grue.qdoc
+++ b/examples/sensors/grue/doc/src/grue.qdoc
@@ -26,11 +26,13 @@
 ****************************************************************************/
 
 /*!
-    \page gruesensorexample.html
+    \example grue
     \title Qt Sensors - Grue Sensor Example
     \brief The Qt Sensors - Grue sensor example demonstrates all the steps from creating a new sensor to using it.
     \ingroup qtsensors-examples
 
+    \image qtsensors-examples-grue.png
+
     The Qt Sensors - Grue sensor example demonstrates all the steps from creating a new sensor to using it.
 
     The sensor definition is placed in a library where client apps can access it. The actual implementation
@@ -54,12 +56,11 @@
     \li \l{Grue Sensor QML Import}
     \li \l{Grue Sensor QML Application}
     \endlist
-*/
 
-/*!
-    \example grue/lib
-    \title Grue Sensor Definition
-    \brief The Grue sensor is defined in a library so that applications can use it.
+    \section1 Grue Sensor Definition
+
+    The Grue sensor is defined in a library so that applications can use it.
+    The source code is available in the \c{grue/lib} subdirectory.
 
     First up is the sensor type. This is the interface for sensors that report
     on your likelihood of being eaten by a Grue. Such sensors are very important
@@ -74,13 +75,10 @@
     src/sensors. As such, it contains some generated code that defines the convenience
     classes GrueFilter and GrueSensor.
 
-    \sa {Qt Sensors - Grue Sensor Example}
-*/
+    \section1 Grue Sensor Implementation
 
-/*!
-    \example grue/plugin
-    \title Grue Sensor Implementation
-    \brief The Grue sensor implementation lives in a plugin that is loaded by the Qt Sensors library.
+    The Grue sensor implementation lives in a plugin that is loaded by the Qt Sensors
+    library. The source code is available in the \c{grue/plugin} subdirectory.
 
     The Grue sensor needs a backend before it can be used. The backend provided
     is rather basic and it relies on some kind of light sensor to work but it
@@ -119,44 +117,37 @@
     The Grue sensor backend is delivered as a plugin. The plugin has a factory object
     that registers the types available and does the actual instantiation of the backend.
 
-    \sa {Qt Sensors - Grue Sensor Example}
-*/
+    \section1 Grue Sensor Console Application
 
-/*!
-    \example grue/console_app
-    \title Grue Sensor Console Application
-    \brief The Grue sensor console application demonstrates use of the Grue sensor.
+    The Grue sensor console application demonstrates use of the Grue sensor.
+    The source code is available in the \c{grue/console_app} subdirectory.
 
     This is a simple commandline application. It demonstrates how to use the generic
     access feature of Qt Sensors to avoid a link-time dependency on the Grue Sensor
     library.
 
-    \sa {Qt Sensors - Grue Sensor Example}
-*/
+    \section1 Grue Sensor QML Import
 
-/*!
-    \example grue/import
-    \title Grue Sensor QML Import
-    \brief The Grue sensor QML import exports the GrueSensor class as a QML type.
+    The Grue sensor QML import exports the GrueSensor class as a QML type.
+    The source code is available in the \c{grue/import} subdirectory.
 
-    This example creates the \e {Grue 1.0} import.
+    This creates the \e {Grue 1.0} import.
 
-    \sa {Qt Sensors - Grue Sensor Example}
-*/
+    \section1 Grue Sensor QML Application
 
-/*!
-    \example grue
-    \title Grue Sensor QML Application
-    \brief The Grue sensor QML application demonstrates use of the GrueSensor QML type.
+    The Grue sensor QML application demonstrates the use of GrueSensor QML type.
 
-    This is a pure QML application that can be run from Qt Creator or directly using the
-    \c qmlscene binary. You should install the other projects before trying to run
+    The application consists of a single QML file and an image. It is built as an
+    exucutable with C++ code that runs the QML, but it can also be launched directly
+    using the \c qmlscene tool.
+
+    You should build the top-level 'grue' project before trying to run
     this example or it will not be able to find its dependencies.
 
     \code
-    qmlscene grue.qml
+    qmlscene -I . grue.qml
     \endcode
 
-    \sa {Qt Sensors - Grue Sensor Example}
+    Above, the \c{-I .} parameter adds the current directory as a module import
+    path to locate the Grue QML module.
 */
-
diff --git a/examples/sensors/grue/grue.qml b/examples/sensors/grue/grue.qml
index 6598016..acafdb6 100644
--- a/examples/sensors/grue/grue.qml
+++ b/examples/sensors/grue/grue.qml
@@ -43,33 +43,56 @@ import QtSensors 5.0
 import Grue 1.0
 
 Rectangle {
+    id: root
     width: 320
     height: 480
     color: "black"
 
+    property int percent: 0
+    property string text: ""
+    property real grueOpacity: 0.0
+
+    function updateStatus(newPercent, newOpacity, newText) {
+        if (root.percent === newPercent)
+            return;
+
+        // Delay updating the visual status to prevent flicker
+        timer.interval = (newPercent < root.percent) ? 500 : 0;
+
+        root.percent = newPercent;
+        root.text = newText;
+        root.grueOpacity = newOpacity;
+
+        timer.start()
+    }
+
+    Timer {
+        id: timer
+        running: false
+        repeat: false
+        onTriggered: {
+            text.text = root.text
+            grueimg.opacity = root.grueOpacity
+        }
+    }
+
     GrueSensor {
         id: sensor
         active: true
         onReadingChanged: {
             var percent = reading.chanceOfBeingEaten;
-            var thetext = "";
-            var theopacity = 0;
             if (percent === 0) {
-                thetext = "It is light. You are safe from Grues.";
+                updateStatus(percent, 0.0, "It is light.<br>You are safe from Grues.");
             }
             else if (percent === 100) {
-                thetext = "You have been eaten by a Grue!";
+                updateStatus(percent, 1.0, "You have been eaten by a Grue!");
                 sensor.active = false;
-                theopacity = 1;
             }
             else if (percent > 0) {
-                thetext = "It is dark. You are likely to be eaten by a Grue. "
-                        + "Your chance of being eaten by a Grue: "+percent+" percent.";
-                theopacity = 0.05 + (percent * 0.001);
+                updateStatus(percent, 0.05 + (percent * 0.001),
+                             "It is dark.<br>You are " + percent +" % " +
+                             "likely to be eaten by a Grue.");
             }
-            text.font.pixelSize = 30;
-            text.text = "<p>" + thetext + "</p>";
-            grueimg.opacity = theopacity;
         }
     }
 
@@ -79,10 +102,10 @@ Rectangle {
         anchors.topMargin: 0
         anchors.left: parent.left
         anchors.right: parent.right
-        text: "I can't tell if you're going to be eaten by a Grue or not. You're on your own!"
         wrapMode: Text.WordWrap
-        font.pixelSize: 50
-        color: "white"
+        text: "I can't tell if you're going to be eaten by a Grue or not. You're on your own!"
+        font.pixelSize: 30
+        color: "lightgray"
     }
 
     Image {
@@ -90,6 +113,7 @@ Rectangle {
         anchors.bottom: parent.bottom
         anchors.horizontalCenter: parent.horizontalCenter
         source: "grue.png"
-        opacity: 0
+        opacity: 0.0
+        Behavior on opacity { PropertyAnimation { duration: 250 } }
     }
 }
diff --git a/examples/sensors/grue/import/import.pro b/examples/sensors/grue/import/import.pro
index 71e2249..56623da 100644
--- a/examples/sensors/grue/import/import.pro
+++ b/examples/sensors/grue/import/import.pro
@@ -2,12 +2,12 @@ TEMPLATE = lib
 CONFIG += plugin
 
 TARGET = $$qtLibraryTarget(declarative_grue)
-TARGETPATH = Grue
+DESTDIR = ../Grue
 
 QT = core gui qml sensors
 
 INCLUDEPATH += $$PWD/../lib
-LIBS += -L$$OUT_PWD/../lib -lgruesensor
+LIBS += -L$$OUT_PWD/.. -lgruesensor
 
 # Shared gruesensor library will be installed in parent directory.
 # Define rpath so that this plugin will know where to look for it.
@@ -15,15 +15,26 @@ unix:!mac: QMAKE_LFLAGS += -Wl,-rpath,\\\$\$ORIGIN/..
 
 SOURCES = main.cpp
 
-DESTPATH=$$[QT_INSTALL_EXAMPLES]/qtsensors/grue/Grue
+DESTPATH=$$[QT_INSTALL_EXAMPLES]/sensors/grue/Grue
 
 target.path=$$DESTPATH
 INSTALLS += target
 
 qmldir.files=$$PWD/qmldir
-qmldir.path=$$DESTPATH
+qmldir.path=$$DESTDIR
 INSTALLS += qmldir
 
 OTHER_FILES += \
     plugin.json qmldir
 
+copyfile = $$PWD/qmldir
+copydest = $$DESTDIR
+
+# On Windows, use backslashes as directory separators
+win32: {
+    copyfile ~= s,/,\\,g
+    copydest ~= s,/,\\,g
+}
+
+# Copy the qmldir file to the same folder as the plugin binary
+QMAKE_POST_LINK += $$QMAKE_COPY $$quote($$copyfile) $$quote($$copydest) $$escape_expand(\\n\\t)
diff --git a/examples/sensors/grue/import/main.cpp b/examples/sensors/grue/import/main.cpp
index 5f6c925..4191d62 100644
--- a/examples/sensors/grue/import/main.cpp
+++ b/examples/sensors/grue/import/main.cpp
@@ -66,6 +66,7 @@ public:
         // Register the 1.0 interfaces
         major = 1;
         minor = 0;
+        // @uri Grue
         qmlRegisterType           <GrueSensor       >(package, major, minor, "GrueSensor");
         qmlRegisterUncreatableType<GrueSensorReading>(package, major, minor, "GrueSensorReading", QLatin1String("Cannot create GrueSensorReading"));
     }
@@ -109,6 +110,7 @@ QT_END_NAMESPACE
 #include "main.moc"
 
 /*
+    \omit
     \qmltype GrueSensor
     \instantiates GrueSensor
     \inherits Sensor
@@ -119,9 +121,11 @@ QT_END_NAMESPACE
 
     This type wraps the GrueSensor class. Please see the documentation for
     GrueSensor for details.
+    \endomit
 */
 
 /*
+    \omit
     \qmltype GrueSensorReading
     \instantiates GrueSensorReading
     \inherits SensorReading
@@ -134,9 +138,12 @@ QT_END_NAMESPACE
     GrueSensorReading for details.
 
     This type cannot be directly created.
+    \endomit
 */
 
 /*
+    \omit
     \qmlproperty qreal Grue1::GrueSensorReading::chanceOfBeingEaten
     Please see GrueSensorReading::chanceOfBeingEaten for information about this property.
+    \endomit
 */
diff --git a/examples/sensors/grue/lib/gruesensor.cpp b/examples/sensors/grue/lib/gruesensor.cpp
index c1e98e7..9787dc5 100644
--- a/examples/sensors/grue/lib/gruesensor.cpp
+++ b/examples/sensors/grue/lib/gruesensor.cpp
@@ -44,6 +44,7 @@
 IMPLEMENT_READING(GrueSensorReading)
 
 /*
+    \omit
     \class GrueSensorReading
 
     \brief The GrueSensorReading class holds readings from the Grue sensor.
@@ -64,6 +65,7 @@ IMPLEMENT_READING(GrueSensorReading)
     it is, the more likely you are to be eaten by a Grue. The longer you
     stay in a dark area, the more likely you are to be eaten by a Grue.
     If you are in a lit room, the probability will be 0 as Grues fear light.
+    \endomit
 */
 
 int GrueSensorReading::chanceOfBeingEaten() const
@@ -81,25 +83,30 @@ void GrueSensorReading::setChanceOfBeingEaten(int chanceOfBeingEaten)
 // begin generated code
 
 /*
+    \omit
     \class GrueFilter
 
     \brief The GrueFilter class is a convenience wrapper around QSensorFilter.
 
     The only difference is that the filter() method features a pointer to GrueSensorReading
     instead of QSensorReading.
+    \endomit
 */
 
 /*
+    \omit
     \fn GrueFilter::filter(GrueSensorReading *reading)
 
     Called when \a reading changes. Returns false to prevent the reading from propagating.
 
     \sa QSensorFilter::filter()
+    \endomit
 */
 
 char const * const GrueSensor::type("GrueSensor");
 
 /*
+    \omit
     \class GrueSensor
 
     \brief The GrueSensor class is a convenience wrapper around QSensor.
@@ -111,12 +118,15 @@ char const * const GrueSensor::type("GrueSensor");
     For details about how the sensor works, see \l GrueSensorReading.
 
     \sa GrueSensorReading
+    \endomit
 */
 
 /*
+    \omit
     \fn GrueSensor::GrueSensor(QObject *parent)
 
     Construct the sensor as a child of \a parent.
+    \endomit
 */
 
 /*
@@ -126,11 +136,13 @@ char const * const GrueSensor::type("GrueSensor");
 */
 
 /*
+    \omit
     \fn GrueSensor::reading() const
 
     Returns the reading class for this sensor.
 
     \sa QSensor::reading()
+    \endomit
 */
 // end generated code
 
diff --git a/examples/sensors/grue/lib/gruesensor.h b/examples/sensors/grue/lib/gruesensor.h
index c0596ea..9b9469a 100644
--- a/examples/sensors/grue/lib/gruesensor.h
+++ b/examples/sensors/grue/lib/gruesensor.h
@@ -74,6 +74,7 @@ private:
 class Q_GRUE_EXPORT GrueSensor : public QSensor
 {
     Q_OBJECT
+    Q_PROPERTY(GrueSensorReading* reading READ reading)
 public:
     explicit GrueSensor(QObject *parent = 0) : QSensor(GrueSensor::type, parent) {}
     virtual ~GrueSensor() {}
diff --git a/examples/sensors/grue/lib/lib.pro b/examples/sensors/grue/lib/lib.pro
index 4d12062..3442abe 100644
--- a/examples/sensors/grue/lib/lib.pro
+++ b/examples/sensors/grue/lib/lib.pro
@@ -1,16 +1,15 @@
 TEMPLATE = lib
 TARGET = gruesensor
 
-# avoid going to release/debug subdirectory
-win32:DESTDIR = $$OUT_PWD
+DESTDIR = $$OUT_PWD/..
 
 DEFINES *= QT_BUILD_GRUE_LIB
 QT = core sensors
 
-HEADERS += gruesensor.h\
-           gruesensor_p.h\
+HEADERS += gruesensor.h \
+           gruesensor_p.h
 
-SOURCES += gruesensor.cpp\
+SOURCES += gruesensor.cpp
 
-target.path=$$[QT_INSTALL_EXAMPLES]/qtsensors/grue
+target.path=$$[QT_INSTALL_EXAMPLES]/sensors/grue
 INSTALLS += target
diff --git a/examples/sensors/grue/plugin/plugin.pro b/examples/sensors/grue/plugin/plugin.pro
index 9045353..8aa87ae 100644
--- a/examples/sensors/grue/plugin/plugin.pro
+++ b/examples/sensors/grue/plugin/plugin.pro
@@ -5,21 +5,23 @@ PLUGIN_TYPE = sensors
 
 QT = core sensors
 
+DESTDIR = ../$$PLUGIN_TYPE
+
 INCLUDEPATH += $$PWD/../lib
-LIBS += -L$$OUT_PWD/../lib -lgruesensor
+LIBS += -L$$OUT_PWD/.. -lgruesensor
 
 # Shared gruesensor library will be installed in parent directory.
 # Define rpath so that this plugin will know where to look for it.
 unix:!mac: QMAKE_LFLAGS += -Wl,-rpath,\\\$\$ORIGIN/..
 
-HEADERS += gruesensorimpl.h\
+HEADERS += gruesensorimpl.h
 
-SOURCES += gruesensorimpl.cpp\
-           main.cpp\
+SOURCES += gruesensorimpl.cpp \
+           main.cpp
 
 
 # Install the plugin under Grue example directory
-target.path=$$[QT_INSTALL_EXAMPLES]/qtsensors/grue/$$PLUGIN_TYPE
+target.path=$$[QT_INSTALL_EXAMPLES]/sensors/grue/$$PLUGIN_TYPE
 INSTALLS += target
 
 OTHER_FILES += \
diff --git a/examples/sensors/grue/qml.pro b/examples/sensors/grue/qml.pro
index d7444ca..ff0963f 100644
--- a/examples/sensors/grue/qml.pro
+++ b/examples/sensors/grue/qml.pro
@@ -1,6 +1,7 @@
 TEMPLATE = app
 TARGET = grue
 QT += quick
+
 SOURCES = main.cpp
 
 RESOURCES += \
@@ -11,6 +12,6 @@ app.files = \
     $$files(*.qml) \
     grue.png
 
-target.path = $$[QT_INSTALL_EXAMPLES]/qtsensors/grue
-app.path = $$[QT_INSTALL_EXAMPLES]/qtsensors/grue
+target.path = $$[QT_INSTALL_EXAMPLES]/sensors/grue
+app.path = $$[QT_INSTALL_EXAMPLES]/sensors/grue
 INSTALLS += target app