Grue Sensor example

Updated, documented as an example.
Now with a QML import and a QML app.

Fixes: MTMW-85
Change-Id: I06772cf4a07ea0d2ec7bfccda6e8f51b5d866c20
Reviewed-on: http://codereview.qt-project.org/6016
Reviewed-by: Lincoln Ramsay <lincoln.ramsay@nokia.com>

2 files changed, 165 insertions, 110 deletions

diff --git a/doc/src/examples/grue.qdoc b/doc/src/examples/grue.qdoc
new file mode 100644
index 00000000..d4dc66fe
--- /dev/null
+++ b/doc/src/examples/grue.qdoc
@@ -0,0 +1,165 @@
+/****************************************************************************
+**
+** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** GNU Free Documentation License
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file.
+**
+** Other Usage
+** Alternatively, this file may be used in accordance with the terms
+** and conditions contained in a signed written agreement between you
+** and Nokia.
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \page gruesensorexample.html
+    \title Grue Sensor Example
+    \brief The Grue sensor example demonstrates all the steps from creating a new sensor to using it.
+    \ingroup qtsensors-examples
+
+    The 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
+    lives in a plugin.
+
+    \list
+    \o \l{Grue Sensor Definition}
+    \o \l{Grue Sensor Implementation}
+    \endlist
+
+    The sensor can now be used by a C++ application, even if the application does not have access to the
+    definition.
+
+    \list
+    \o \l{Grue Sensor Console Application}
+    \endlist
+
+    To make the sensor available to a QML application an import must be created.
+
+    \list
+    \o \l{Grue Sensor QML Import}
+    \o \l{Grue Sensor QML Application}
+    \endlist
+*/
+
+/*!
+    \example sensors/grue/lib
+    \title Grue Sensor Definition
+    \brief The Grue sensor is defined in a library so that applications can use it.
+
+    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 piece 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.
+
+    \sa {Grue Sensor Example}
+*/
+
+/*!
+    \example sensors/grue/plugin
+    \title Grue Sensor Implementation
+    \brief The Grue sensor implementation lives in a plugin that is loaded by the QtSensors library.
+
+    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/grue/plugin/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/grue/plugin/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.
+
+    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 {Grue Sensor Example}
+*/
+
+/*!
+    \example sensors/grue/console_app
+    \title Grue Sensor Console Application
+    \brief The Grue sensor console application demonstrates use of the Grue sensor.
+
+    This is a simple commandline application. It demonstrates how to use the generic
+    access feature of QtSensors to avoid a link-time dependency on the Grue Sensor
+    library.
+
+    \sa {Grue Sensor Example}
+*/
+
+/*!
+    \example sensors/grue/import
+    \title Grue Sensor QML Import
+    \brief The Grue sensor QML import exports the GrueSensor class as a QML element.
+
+    This example creates the \l {Grue 1.0} import.
+
+    \sa {Grue Sensor Example}
+*/
+
+/*!
+    \example sensors/grue/qml_app
+    \title Grue Sensor QML Application
+    \brief The Grue sensor QML application demonstrates use of the GrueSensor QML element.
+
+    blah blah blah
+
+    \sa {Grue Sensor Example}
+*/
+
+/*!
+    \qmlmodule Grue 1
+    \title Grue 1.0
+    \brief QML import for the Grue Sensor Example
+
+    blah blah blah
+
+*/
+
diff --git a/doc/src/examples/sensors.qdoc b/doc/src/examples/sensors.qdoc
index db02d7d6..6cb3ce78 100644
--- a/doc/src/examples/sensors.qdoc
+++ b/doc/src/examples/sensors.qdoc
@@ -37,115 +37,6 @@
 */
 
 /*!
-    \example sensors/grueplugin
-    \title Grue Plugin
-    \brief The Grue Plugin demonstrates creation of a new sensor backend.
-    \ingroup qtsensors-examples
-
-    The Grue plugin example demonstrates the creation of a new sensor type,
-    a sensor backend and plugin for the sensors library. Related to this example
-    is the \l{sensors/grueapp}{Grue Application} example.
-
-    \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 piece 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.
-
-    \sa {sensors/grueapp}{Grue Application}
-*/
-
-
-/*!
-    \example sensors/grueapp
-    \title Grue Application
-    \brief The Grue Application demonstrates use of a new sensor type.
-    \ingroup qtsensors-examples
-
-    The Grue application example demonstrates the use of the Grue sensor which
-    was defined and implemented by the \l{sensors/grueplugin}{Grue Plugin} example.
-    The Grue application is a commandline application. It is significant to note that
-    there is no link-time dependency on the Grue plugin. The Grue application uses
-    the generic access feature of the Sensors API.
-
-    \sa {sensors/grueplugin}{Grue Plugin}
-*/
-
-
-/*!
     \example sensors/cubehouse
     \title Cube House
     \ingroup qtsensors-examples
@@ -169,7 +60,6 @@
     \snippet ../examples/sensors/cubehouse/view.cpp smoothed
 */
 
-
 /*!
     \example sensors/sensor_explorer
     \title Sensor Explorer