Update the Grue examples.

Documentation, comments, etc.

6 files changed, 222 insertions, 21 deletions

diff --git a/doc/src/examples.qdoc b/doc/src/examples.qdoc
index 68e1ce271c..facce27c9d 100644
--- a/doc/src/examples.qdoc
+++ b/doc/src/examples.qdoc
@@ -120,5 +120,12 @@
     \list
     \o \l{sysinfo}{System Information}
     \endlist
+
+    \section2 Sensors
+
+    \list
+    \o \l{sensors/grueplugin}{Grue Plugin}
+    \o \l{sensors/grueapp}{Grue Application}
+    \endlist
 */
 
diff --git a/doc/src/examples/sensors.qdoc b/doc/src/examples/sensors.qdoc
new file mode 100644
index 0000000000..63b96e9b12
--- /dev/null
+++ b/doc/src/examples/sensors.qdoc
@@ -0,0 +1,130 @@
+/****************************************************************************
+**
+** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the Qt Mobility Components.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights.  These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \example sensors/grueplugin
+    \title Grue Plugin
+
+    The Grue plugin example demonstrates the creation of a new sensor type,
+    a sensor backend and plugin for the sensors library.
+
+    \tableofcontents
+
+    \section1 Grue Sensor Type
+
+    The files for this are:
+
+    \list
+    \o gruesensor.h
+    \o gruesensor_p.h
+    \o gruesensor.cpp
+    \endlist
+
+    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
+    to adventurers, particularly if they are going into dark places as this is
+    where Grues live.
+
+    The interface is a simple one. It provides only 1 bit of information, your
+    chance of being eaten. For the details on how this is property should be
+    interpreted please see the documentation in gruesensor.cpp.
+
+    This example was created using the make_sensor.pl script which can be found in
+    src/sensors. As such, it contains some generated code that defines the convenience
+    classes GrueFilter and GrueSensor.
+
+    \section1 Grue Sensor Backend
+
+    The files for this are:
+
+    \list
+    \o gruesensorimpl.h
+    \o gruesensorimpl.cpp
+    \endlist
+
+    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
+    gets the job done. If new hardware that can detect the actual presence of Grues
+    becomes available a backend could be created that supports this hardware and
+    applications using the Grue sensor would be able to use it without any changes.
+
+    There are a few mandatory parts to a backend. They are the start and stop methods
+    and the setReading call. The start and stop methods are used to start and stop
+    any underlying hardware. In the case of this backend they start and stop a
+    light sensor. In the start method, the backend should be sure to call the
+    sensorStopped() or sensorBusy() methods if it cannot start.
+
+    \snippet ../../examples/sensors/grueplugin/gruesensorimpl.cpp start
+
+    The setReading method is needed so that the sensors library knows where the
+    readings are coming from. This backend has a local copy of the reading so
+    it passes a pointer to the function.
+
+    \snippet ../../examples/sensors/grueplugin/gruesensorimpl.cpp setReading
+
+    However it is also possible to pass null to the setReading method in which
+    case the sensors library will create an instance and return a pointer.
+
+    \code
+    // Create a reading instance for us to use
+    m_reading = setReading<GrueSensorReading>(0);
+    \endcode
+
+    The Grue sensor backend also supplies some metadata.
+
+    The backend checks 2 things, how dark it is and how long you have been in the dark.
+    It uses the readingChanged() signal to know when to check the light sensor's
+    value. Once it is dark, it uses a timer to increase your chance of being eaten.
+
+    \section1 Grue Sensor Plugin
+
+    The files for this are:
+
+    \list
+    \o main.cpp
+    \endlist
+
+    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.
+
+*/
+
+
diff --git a/examples/sensors/grueapp/main.cpp b/examples/sensors/grueapp/main.cpp
index f2e139239e..f19c6ba2cd 100644
--- a/examples/sensors/grueapp/main.cpp
+++ b/examples/sensors/grueapp/main.cpp
@@ -45,11 +45,28 @@ QTM_USE_NAMESPACE
 
 class Filter : public QSensorFilter
 {
+    int lastPercent;
 public:
+    Filter()
+        : QSensorFilter()
+        , lastPercent(0)
+    {
+    }
+
     bool filter(QSensorReading *reading)
     {
         int percent = reading->property("chanceOfBeingEaten").value<qreal>() * 100;
-        qDebug() << "Your chance of being eaten by a Grue:" << percent << "percent.";
+        if (percent == 0) {
+            qDebug() << "It is light. You are safe from Grues.";
+        } else if (lastPercent == 0) {
+            qDebug() << "It is dark. You are likely to be eaten by a Grue.";
+        }
+        if (percent == 100) {
+            qDebug() << "You have been eaten by a Grue!";
+            QCoreApplication::instance()->quit();
+        } else if (percent)
+            qDebug() << "Your chance of being eaten by a Grue:" << percent << "percent.";
+        lastPercent = percent;
         return false;
     }
 };
@@ -65,7 +82,7 @@ int main(int argc, char **argv)
     sensor.start();
 
     if (!sensor.isActive()) {
-        qWarning("Grue sensor didn't start!");
+        qWarning("The Grue sensor didn't start. You're on your own!");
         return 1;
     }
 
diff --git a/examples/sensors/grueplugin/gruesensor.cpp b/examples/sensors/grueplugin/gruesensor.cpp
index 3bfb280d20..304fe0f433 100644
--- a/examples/sensors/grueplugin/gruesensor.cpp
+++ b/examples/sensors/grueplugin/gruesensor.cpp
@@ -53,7 +53,8 @@ IMPLEMENT_READING(GrueSensorReading)
     The Grue Sensor informs you of your chance of being eaten by a Grue.
 
     Grues love the dark so as long as your surroundings are relatively light
-    you are safe.
+    you are safe. However the more time you spend in the dark, the higher
+    your chances are of being eaten by a Grue.
 */
 
 /*!
@@ -61,9 +62,10 @@ IMPLEMENT_READING(GrueSensorReading)
     \brief holds your chance of being eaten.
 
     The value is the probability (from 0 to 1) that a Grue will eat you.
-    A probability of 1 means you will be eaten. The darker it is, the more
-    likely you are to be eaten by a Grue. If you are in a lit room, the
-    probability will be 0.
+    A probability of 1 means you are currently being eaten. The darker
+    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.
 */
 
 qreal GrueSensorReading::chanceOfBeingEaten() const
diff --git a/examples/sensors/grueplugin/gruesensorimpl.cpp b/examples/sensors/grueplugin/gruesensorimpl.cpp
index 4b7b8a8b51..2e7cba0104 100644
--- a/examples/sensors/grueplugin/gruesensorimpl.cpp
+++ b/examples/sensors/grueplugin/gruesensorimpl.cpp
@@ -40,26 +40,52 @@
 
 #include "gruesensorimpl.h"
 #include <QDebug>
+#include <QTimer>
 
 char const * const gruesensorimpl::id("grue.gruesensor");
 
 gruesensorimpl::gruesensorimpl(QSensor *sensor)
     : QSensorBackend(sensor)
 {
+    // We need a light sensor
     lightSensor = new QAmbientLightSensor(this);
-    lightSensor->addFilter(this);
+    connect(lightSensor, SIGNAL(readingChanged()), this, SLOT(lightChanged()));
     lightSensor->connectToBackend();
 
+    // We need a timer
+    darkTimer = new QTimer(this);
+    darkTimer->setInterval(1000);
+    connect(darkTimer, SIGNAL(timeout()), this, SLOT(increaseChance()));
+
+    // We use this as our timestamp source
+    timer.start();
+
+//! [setReading]
+    // Register our reading instance
     setReading<GrueSensorReading>(&m_reading);
+//! [setReading]
+
+//! [metadata]
+    // Supply metadata
+    // We can run as fast as the light sensor does
     setDataRates(lightSensor);
+    // Only one output range, 0 to 1 in .1 increments
     addOutputRange(0, 1, 0.1);
     setDescription(QLatin1String("Grue Sensor"));
+//! [metadata]
 }
 
 void gruesensorimpl::start()
 {
+//! [start]
     lightSensor->setDataRate(sensor()->dataRate());
     lightSensor->start();
+    // If the light sensor doesn't work we don't work either
+    if (!lightSensor->isActive())
+        sensorStopped();
+    if (lightSensor->isBusy())
+        sensorBusy();
+//! [start]
 }
 
 void gruesensorimpl::stop()
@@ -67,32 +93,43 @@ void gruesensorimpl::stop()
     lightSensor->stop();
 }
 
-bool gruesensorimpl::filter(QAmbientLightReading *reading)
+void gruesensorimpl::lightChanged()
 {
-    qreal chance;
+    qreal chance = 0.0;
+    darkTimer->stop();
 
-    switch (reading->lightLevel()) {
-    case QAmbientLightReading::Undefined:
-        chance = 0.5; // No idea... call it 50/50
-        break;
+    switch (lightSensor->reading()->lightLevel()) {
     case QAmbientLightReading::Dark:
-        chance = 1.0;
-        break;
-    case QAmbientLightReading::Twilight:
+        // It is dark. You are likely to be eaten by a grue.
         chance = 0.1;
+        darkTimer->start();
         break;
     default:
-        chance = 0.0;
         break;
     }
 
+    // Only send an update if the value has changed.
     if (chance != m_reading.chanceOfBeingEaten()) {
-        m_reading.setTimestamp(reading->timestamp());
+        m_reading.setTimestamp(timer.elapsed());
         m_reading.setChanceOfBeingEaten(chance);
 
         newReadingAvailable();
     }
+}
+
+void gruesensorimpl::increaseChance()
+{
+    // The longer you stay in the dark, the higher your chance of being eaten
+    qreal chance = m_reading.chanceOfBeingEaten() + 0.1;
+
+    m_reading.setTimestamp(timer.elapsed());
+    m_reading.setChanceOfBeingEaten(chance);
+
+    newReadingAvailable();
 
-    return true;
+    // No point in using the timer anymore if we've hit 1... you can't get more
+    // likely to be eaten than 100%
+    if (chance == 1.0)
+        darkTimer->stop();
 }
 
diff --git a/examples/sensors/grueplugin/gruesensorimpl.h b/examples/sensors/grueplugin/gruesensorimpl.h
index 4fbb2061c3..7b59b973d8 100644
--- a/examples/sensors/grueplugin/gruesensorimpl.h
+++ b/examples/sensors/grueplugin/gruesensorimpl.h
@@ -44,11 +44,15 @@
 #include <qsensorbackend.h>
 #include "gruesensor.h"
 #include <qambientlightsensor.h>
+#include <QTime>
 
 QTM_USE_NAMESPACE
 
-class gruesensorimpl : public QSensorBackend, public QAmbientLightFilter
+class QTimer;
+
+class gruesensorimpl : public QSensorBackend
 {
+    Q_OBJECT
 public:
     static char const * const id;
 
@@ -57,11 +61,15 @@ public:
     void start();
     void stop();
 
-    bool filter(QAmbientLightReading *reading);
+private Q_SLOTS:
+    void lightChanged();
+    void increaseChance();
 
 private:
     GrueSensorReading m_reading;
     QAmbientLightSensor *lightSensor;
+    QTimer *darkTimer;
+    QTime timer;
 };
 
 #endif