Import sensors docs from Mobility.

Also bring in some examples that are referenced in the docs.

Change-Id: I74560c62be447dda06ccfd8996818225df007c2e
Reviewed-on: http://codereview.qt.nokia.com/3828
Reviewed-by: Lincoln Ramsay <lincoln.ramsay@nokia.com>

28 files changed, 1098 insertions, 0 deletions

diff --git a/doc/src/examples/sensors.qdoc b/doc/src/examples/sensors.qdoc
new file mode 100644
index 00000000..3363642b
--- /dev/null
+++ b/doc/src/examples/sensors.qdoc
@@ -0,0 +1,166 @@
+/****************************************************************************
+**
+** 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 documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** 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 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.
+**
+** 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. 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
+
+    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
+
+    \image cubehouse.png
+
+    The Cube House example demonstrates the use of the accelerometer to drive a camera
+    to create a pseudo-3D effect. It also demonstrates the use of a filter to smooth
+    out the accelerometer values.
+
+    The accelerometer is created and the filter is added.
+
+    \snippet ../../examples/sensors/cubehouse/view.cpp accelerometer
+
+    When new values are available, the view is recalculated.
+
+    \snippet ../../examples/sensors/cubehouse/view.cpp accelerometer2
+
+    The filter is defined like this.
+
+    \snippet ../../examples/sensors/cubehouse/view.cpp smoothed
+*/
+
+
+/*!
+    \example sensors/sensor_explorer
+    \title Sensor Explorer
+
+    \image sensor_explorer.png
+
+    The Sensor Explorer example demonstrates how to read the meta-data of available sensors.
+    It was designed as a debugging aid.
+*/
+
diff --git a/doc/src/images/sensor_explorer.png b/doc/src/images/sensor_explorer.png
new file mode 100644
index 00000000..91d255ec
--- /dev/null
+++ b/doc/src/images/sensor_explorer.png
diff --git a/doc/src/images/sensors-coordinates.jpg b/doc/src/images/sensors-coordinates.jpg
new file mode 100644
index 00000000..e2e98908
--- /dev/null
+++ b/doc/src/images/sensors-coordinates.jpg
diff --git a/doc/src/images/sensors-coordinates2.jpg b/doc/src/images/sensors-coordinates2.jpg
new file mode 100644
index 00000000..8dd43a21
--- /dev/null
+++ b/doc/src/images/sensors-coordinates2.jpg
diff --git a/doc/src/images/sensors-coordinates3.jpg b/doc/src/images/sensors-coordinates3.jpg
new file mode 100644
index 00000000..02634000
--- /dev/null
+++ b/doc/src/images/sensors-coordinates3.jpg
diff --git a/doc/src/images/sensors-dynamic.png b/doc/src/images/sensors-dynamic.png
new file mode 100644
index 00000000..d2ba937d
--- /dev/null
+++ b/doc/src/images/sensors-dynamic.png
diff --git a/doc/src/images/sensors-geo-vs-raw-magnetism.jpg b/doc/src/images/sensors-geo-vs-raw-magnetism.jpg
new file mode 100644
index 00000000..272fa310
--- /dev/null
+++ b/doc/src/images/sensors-geo-vs-raw-magnetism.jpg
diff --git a/doc/src/images/sensors-orientation.jpg b/doc/src/images/sensors-orientation.jpg
new file mode 100644
index 00000000..245533d5
--- /dev/null
+++ b/doc/src/images/sensors-orientation.jpg
diff --git a/doc/src/images/sensors-overview.png b/doc/src/images/sensors-overview.png
new file mode 100644
index 00000000..29e9ebd4
--- /dev/null
+++ b/doc/src/images/sensors-overview.png
diff --git a/doc/src/images/sensors-rotation-anim.gif b/doc/src/images/sensors-rotation-anim.gif
new file mode 100644
index 00000000..22c678d5
--- /dev/null
+++ b/doc/src/images/sensors-rotation-anim.gif
diff --git a/doc/src/images/sensors-rotation.jpg b/doc/src/images/sensors-rotation.jpg
new file mode 100644
index 00000000..1bd1b14b
--- /dev/null
+++ b/doc/src/images/sensors-rotation.jpg
diff --git a/doc/src/images/sensors-rotation2.jpg b/doc/src/images/sensors-rotation2.jpg
new file mode 100644
index 00000000..1bf34fee
--- /dev/null
+++ b/doc/src/images/sensors-rotation2.jpg
diff --git a/doc/src/images/sensors-rotation3.jpg b/doc/src/images/sensors-rotation3.jpg
new file mode 100644
index 00000000..d69a3e19
--- /dev/null
+++ b/doc/src/images/sensors-rotation3.jpg
diff --git a/doc/src/images/sensors-sides.jpg b/doc/src/images/sensors-sides.jpg
new file mode 100644
index 00000000..8e842242
--- /dev/null
+++ b/doc/src/images/sensors-sides.jpg
diff --git a/doc/src/images/sensors-sides2.jpg b/doc/src/images/sensors-sides2.jpg
new file mode 100644
index 00000000..db66a9b5
--- /dev/null
+++ b/doc/src/images/sensors-sides2.jpg
diff --git a/doc/src/images/sensors-static.png b/doc/src/images/sensors-static.png
new file mode 100644
index 00000000..657aaad2
--- /dev/null
+++ b/doc/src/images/sensors-static.png
diff --git a/doc/src/plugins/qml-sensors.qdoc b/doc/src/plugins/qml-sensors.qdoc
new file mode 100644
index 00000000..15f4c993
--- /dev/null
+++ b/doc/src/plugins/qml-sensors.qdoc
@@ -0,0 +1,99 @@
+/****************************************************************************
+**
+** 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$
+**
+****************************************************************************/
+
+/*!
+    \group qml-sensors
+    \title QML Sensors API Plugin
+    QML Support for the QtMobility Project Sensors API.
+*/
+
+/*!
+    \page qml-sensors.html
+
+    \title Sensors QML Plugin
+
+    \brief A QML plugin for the QtMobility Project Sensors API.
+
+    \section1 Overview
+
+    The QML Sensors Plugin provides an easy to use interface to the Sensors API.
+    It enables us to receive sensor events and to read current values from
+    sensors.
+
+    The plugin contains many sensor types and access functions to read values
+    from them. As an example consider the orientation sensor. The orientation
+    example simply displays text on-screen to show the current orientation.
+
+    The QML code that reads the value is quite simple. Here we see a QML component
+    \e orientation declared which is an \l OrientationSensor element. First
+    the sensor is started by setting the \l {Sensor::active}{active} property
+    to \e true. The element receives a signal when the reading changes and it
+    is picked up by the \e onReadingChanged slot. Now the
+    \l {OrientationSensor::reading}{reading} property of this element can be
+    used to extract the current orientation so that it can be compared against
+    the defined values of various orientations in the \l OrientationReading
+    element.
+
+    \qml
+        OrientationSensor {
+            id: orientation
+            active: true
+
+            onReadingChanged: {
+
+                if (reading.orientation == OrientationReading.FaceUp)
+                    content.state = "FaceUp";
+
+                // ... more tests for different orientations ...
+            }
+        }
+
+    \endqml
+
+    Other sensors can be treated in a similar manner. For example, the \l Compass
+    sensor could have almost identical coding
+
+    \qml
+        Compass {
+            id: compass
+            active: true
+
+            onReadingChanged: {
+                compassHeading.text = reading.azimuth;
+
+                // ...
+            }
+        }
+    \endqml
+
+    \section1 QML Elements
+    \annotatedlist qml-sensors_type
+    \annotatedlist qml-sensors_reading
+
+*/
+
+
diff --git a/doc/src/sensors-dynamic.dia b/doc/src/sensors-dynamic.dia
new file mode 100644
index 00000000..d5cb8ac7
--- /dev/null
+++ b/doc/src/sensors-dynamic.dia
diff --git a/doc/src/sensors-overview.dia b/doc/src/sensors-overview.dia
new file mode 100644
index 00000000..fb3dc66d
--- /dev/null
+++ b/doc/src/sensors-overview.dia
diff --git a/doc/src/sensors-static.dia b/doc/src/sensors-static.dia
new file mode 100644
index 00000000..cd5d3d3f
--- /dev/null
+++ b/doc/src/sensors-static.dia
diff --git a/doc/src/sensors.qdoc b/doc/src/sensors.qdoc
new file mode 100644
index 00000000..6dc1efbd
--- /dev/null
+++ b/doc/src/sensors.qdoc
@@ -0,0 +1,524 @@
+/****************************************************************************
+**
+** 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 documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** 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 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.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+\page sensors-api.html
+\title Sensors
+\brief The Sensors API provides access to sensors.
+\ingroup mobility
+\ingroup technology-apis
+
+
+The Sensors API is primarily concerned with low-level, real-time sensors such as
+the accelerometer although there are higher-level, event-driven sensors represented too.
+
+\tableofcontents
+
+\section1 Sensor Types
+
+On a device there can be many types of sensors. Not all of the types that the Sensors API
+supports may be available. There may also be types available that are not defined in the
+Sensors API. You can find the sensor types available on a device using the
+\l QSensor::sensorTypes() function.
+
+For a list of built-in sensor types, see the \l{Sensor Classes} section below.
+
+\section1 Common Conventions
+
+Unless otherwise specified, sensors shall use the
+\l{http://en.wikipedia.org/wiki/Cartesian_coordinate_system}{Right Hand Cartesian coordinate system}.
+
+\image sensors-coordinates.jpg
+
+To allow for measurements in all 6 directions, negative values are used.
+
+\image sensors-coordinates2.jpg
+
+Where rotation around an axis is used, the rotation shall be expressed as a Right Hand rotation.
+
+\image sensors-coordinates3.jpg
+
+In general, sensor data is oriented to the top of the device. If values are to be displayed on
+the screen the values may need to be transformed so that they match the user interface orientation. A sensor
+may define its data as being oriented to the UI. This will be noted in the documentation for the
+sensor.
+
+\image sensors-sides2.jpg
+
+\section1 Using a Sensor
+
+The life cycle of a sensor is typically:
+
+\list
+\o Create an instance of QSensor or one of its sub-classes on the stack or heap.
+\o Setup as required by the application.
+\o Start receiving values.
+\o Sensor data is used by the application.
+\o Stop receiving values.
+\endlist
+
+Here is an example of creating a sensor on the heap and on the stack.
+
+\snippet snippets/sensors/creating.cpp Creating a sensor
+
+\section1 Accessing sensor data in a generic fashion
+
+The preferred way to deal with sensor data is via the \l{Reading Classes}.
+However, sometimes this may not be possible. For example, you may be deploying
+an application to a device that has a new sensor type but no C++ header
+describing the reading class is available.
+
+Thanks to Qt's property system you can still access the sensor data. You need to know
+3 pieces of information in order to do this:
+
+\list
+\o The sensor type.
+\o The property name or index.
+\o The property type or a comparable type.
+\endlist
+
+For example, here is an example of how you can access a property of the accelerometer.
+This code does not require any compile-time links to \l QAccelerometer or
+\l QAccelerometerReading.
+
+\snippet snippets/sensors/start.cpp Starting a sensor
+
+You can discover all of this information at runtime too. The sensor_explorer example
+shows you information about available sensors.
+
+\section1 Platform notes
+
+\section2 S60 3rd Edition
+
+Note that support for sensors in S60 3.1 device is extremely limited due to the native API.
+Only the accelerometer is supported and only a few devices.
+
+Some devices running S60 3.2 support a newer native API and therefore support more sensors.
+
+More information about these platforms can be found \l{http://wiki.forum.nokia.com/index.php/Nokia_Sensor_APIs}{here}.
+
+Note that timestamps on this platform come from the system clock.
+Applications need to handle shifts in time caused by the user manually setting the clock or
+from the automatic time synchronization feature setting the clock.
+
+\section2 Symbian
+
+Most Symbian devices have their sensor data read via the Sensor Framework API. Some limitations
+appear in the Sensors API as a result.
+
+Only specific data rates can be selected. Setting an invalid data rate has no effect so applications
+that need to influence the used data rate should connect to the sensor, check the available data rates
+and select one as appropriate.
+
+Readings are delivered to the application via a queue. If the application blocks the event loop or otherwise
+interferes with the ability of the system to deliver readings (eg. by using up too much CPU time), they can
+get blocked in this queue. Since delayed readings are not useful, the system will drop readings as needed
+so that the application is always dealing with the most recent reading available. The application can tweak
+the policy by setting properties on the sensor.
+
+The default policy is to accept up to 100 readings from the system at once and to discard all but the last one.
+
+\code
+QAccelerometer sensor;
+sensor.setProperty("maximumReadingCount", 100);
+sensor.setProperty("processAllReadings", false);
+\endcode
+
+Applications that desire the original behaviour can set the maximumReadingCount to 1. Note that this does not
+guarantee that readings will not be dropped by the system. If the queue fills up, readings will be dropped.
+
+\code
+QAccelerometer sensor;
+sensor.setProperty("maximumReadingCount", 1);
+\endcode
+
+Larger maximumReadingCount values reduce the need for the lower-priority sensor daemon to get CPU timeslices.
+If the application is using lots of CPU but is still able to process readings quickly, it can request that
+all the fetched readings are processed.
+
+\code
+QAccelerometer sensor;
+sensor.setProperty("maximumReadingCount", 10);
+sensor.setProperty("processAllReadings", true);
+\endcode
+
+More information about the native API can be found \l{http://wiki.forum.nokia.com/index.php/Nokia_Sensor_APIs}{here}.
+
+Note that timestamps on this platform come from the system clock.
+Applications need to handle shifts in time caused by the user manually setting the clock or
+from the automatic time synchronization feature setting the clock.
+
+The ambient light sensor can only detect changes. Unlike all other sensors, it cannot report the "current value"
+so it is not possible to determine the current ambient light level.
+
+\section2 Maemo 5
+
+The N900 represents a unique device for the Sensors API. Unlike the Symbian and MeeGo platforms, sensor data is
+retrieved directly from the kernel and this has implications on the API.
+
+Axes are rotated when compared to Symbian or MeeGo devices. While Symbian and MeeGo devices orient their
+hardware sensors towards a portrait orientation, the N900 does not do this. Instead, it orients the hardware sensors
+towards its default landscape orientation. This has portability implications for applications that want to force the
+use of a particular screen orientation and use sensors. The following code shows how accelerometer values can be
+interpreted to ensure consistent results on the N900 as well as Symbian and MeeGo devices.
+
+\code
+#ifdef Q_WS_MAEMO_5
+    qreal x = reading->y();
+    qreal y = -reading->x();
+#else
+    qreal x = reading->x();
+    qreal y = reading->y();
+#endif
+    qreal z = reading->z();
+\endcode
+
+Alternatively, applications can set the environment variable \c N900_PORTRAIT_SENSORS to 1. This must be done
+before any Sensors API calls are made so the beginning of the main function is a good place to do it.
+
+\code
+int main(int argc, char **argv)
+{
+    qputenv("N900_PORTRAIT_SENSORS", "1");
+    ...
+\endcode
+
+Despite hardware that allows for multiple data rates and output ranges, the Sensors API does not allow access to
+these due to permissions issues.
+
+Readings are polled using a timer. If the application blocks the event loop or otherwise interferes with the
+ability of the timer to fire, readings will be missed. There are no queues so applications must ensure that
+they process the readings promptly (possibly saving them into a buffer for later processing if required).
+
+\section2 MeeGo
+
+The data rates offered by MeeGo are not tied to how fast the hardware runs.
+
+The default data rate for a sensor is likely to be low when compared to Symbian or Maemo 5. Applications should
+request a suitable data rate, taking care to avoid selecting invalid rates on other devices.
+
+Sensors may be suspended by the system in order to save power. Applications can avoid this by setting a property
+on the sensor object.
+
+\code
+QAccelerometer *accelerometer = new QAccelerometer(this);
+accelerometer->setProperty("alwaysOn", true);
+accelerometer->start();
+\endcode
+
+Unlike Symbian and N900, MeeGo does not currently provide initial readings. Thus, certain sensors must detect
+a change in value before a value can be reported. Examples include the orientation sensor and ambient light
+sensor.
+
+\section1 Front end, back end
+
+The Sensors API has a front end, for application developers to use and a back end,
+where device implementors write code to access their hardware. As an application
+developer you do not need to access the back end though it may be useful to understand
+how it works.
+
+Commands from the application are delivered through QSensor and then down to the
+device plugin. Data comes back through the QSensorReading class.
+
+\image sensors-overview.png
+
+More information about the back end can be found in \l{Sensors Backend}.
+
+\section1 Main Classes
+
+The primary classes that make up the Sensors API.
+
+\annotatedlist sensors_main
+
+\section1 Reading Classes
+
+The best way to access sensor data is via one of these classes.
+
+\annotatedlist sensors_reading
+
+\section1 Sensor Classes
+
+These classes provide convenience wrappers that reduce the need for casting.
+Each of these classes represents a sensor type that the Sensors API knows
+about. Note that additional types may be made available at run-time. See
+\l{Sensor Types} for more information.
+
+\annotatedlist sensors_type
+
+\section1 Filter Classes
+
+As with the sensor classes, these provide convenience wrappers that reduce
+the need for casting.
+
+\annotatedlist sensors_filter
+
+*/
+
+/*!
+\page sensors-backend.html
+\title Sensors Backend
+\brief The Sensors Backend connects the Sensors API to the platform services or hardware sensors.
+
+The Sensors Backend connects the Sensors API to the platform services or hardware sensors.
+
+\tableofcontents
+
+\section1 Overview
+
+\section1 Backend API
+
+QSensor instances talk to a backend object. Backends are usually supplied
+with the QtSensors library for a specific device although third party
+backends may be used as well. A backend may talk
+directly to hardware or it may talk to a system service. In some instances
+it may even talk to another sensor.
+An example of this is the orientation sensor backend that talks to an
+accelerometer to determine the orientation.
+
+There are also some \l{Sensors Backend Topics}{topics} specific to backend
+implementors.
+
+\section1 Backend Classes
+If you are making sensors available through the Sensors API, these are the
+classes to use.
+\annotatedlist sensors_backend
+
+\sa {Sensors Backend Topics}
+
+*/
+
+/*!
+\group sensors_backend_topics
+\title Sensors Backend Topics
+\generatelist related
+*/
+
+/*!
+\page creating-a-sensor-plugin.html
+\title Creating a sensor plugin
+\ingroup sensors_backend_topics
+
+\section1 How a sensor plugin is loaded
+
+Since sensor backends are created on demand, the sensor plugin is loaded and asked
+to register the sensor backends it handles. The plugin should implement
+QSensorPluginInterface::registerSensors() and call QSensorManager::registerBackend()
+to register available backends. Typically the plugin will also inherit from
+QSensorBackendFactory and implement
+QSensorBackendFactory::createBackend() in order to instantiate backends it has registered.
+
+The simplest plugin will have just once sensor backend although there is no reason
+that multiple sensor backends cannot be in a plugin.
+
+An example follows.
+
+\snippet snippets/sensors/plugin.cpp Plugin
+
+If you would like to build a backend into a library or application you can use the
+REGISTER_STATIC_PLUGIN() macro although it may not work in all situations as it
+uses static initialization.
+
+*/
+
+/*!
+\page determining-the-default-sensor-for-a-type.html
+\title Determining the default sensor for a type
+\ingroup sensors_backend_topics
+
+\section1 Multiple sensors can exist for a type
+
+Sensors was designed so that multiple sensors could exist for a given type. Why?
+Consider this example.
+
+The N900 has an accelerometer built-in. It also features bluetooth and can pair
+with a gaming controller that features an accelerometer. To a developer writing
+a game these two devices are conceptually the same type.
+
+\section1 Default sensor for a type
+
+To avoid the need to know (or check) what the default sensor for a type is, the system will
+use the default sensor for a type. Most of the time this is what the app developer wants to
+do. In cases where the app developer wants to select a specific sensor they must call the
+QSensor::setIdentifier() method before they start the sensor so that the appropriate backend
+is used.
+
+From a system perspective though, selecting which sensor should be the default gets tricky.
+The sensors library uses the first registered identifier as the default. This means that the
+order in which sensor backends are registered is important so the system will allow a config
+file to determine the default instead.
+
+\section1 Sensors.conf
+
+The config file that determines the default sensor for a type is called Sensors.conf. If present,
+it is located in /etc/xdg/Nokia. It is read using QSettings so it has the standard formatting
+of a QSettings .conf file.
+
+The settings live in the Default group and the general format is:
+\code
+type = identifier
+\endcode
+
+An example Sensors.conf that ensures the N900 accelerometer is used as the default no matter the
+order in which backends were registered is presented here.
+
+\code
+[Default]
+QAccelerometer = n900.accelerometer
+\endcode
+
+If Sensors.conf specifies an identifier that is not registered then the system will fall back to
+the first registered identifier as the default.
+
+Note that there is special case logic to prevent the generic plugin's backends from becoming the
+default when another backend is registered for the same type. This logic means that a backend
+identifier starting with \c{generic.} will only be the default if no other backends have been
+registered for that type or if it is specified in \c{Sensors.conf}.
+
+*/
+
+/*!
+\page dynamic-sensor-backend-registration.html
+\title Dynamic Sensor Backend Registration
+\ingroup sensors_backend_topics
+
+\section1 Static Backend Registration
+
+Sensor backends are generally registered statically. The registration happens when the sensors
+library is first used and the registration remains in effect while the program runs.
+
+\image sensors-static.png
+
+Statically registered backends may still exhibit some dynamic behaviour as the
+QSensorBackendFactory is free to return 0 to indicate that a backend cannot be created.
+
+\section1 Dynamic Backend Registration
+
+While static registration is fine for most backends there are some situations where this is
+problematic.
+
+The clearest example is backends that represent non-fixed hardware. As an example, lets consider
+a game controller that is connected via Bluetooth. As there may be more than one game controller
+in range of the phone, the program wants to record that a specific game controller should be used.
+If the backend had been registered statically there would have been no unique information about
+the controller. Instead, the registration is delayed until the controller is seen.
+
+\image sensors-dynamic.png
+
+\section1 Suggested Registration Policy
+
+A backend for fixed hardware should be registered immediately. Applications can see that the
+sensor can be used.
+
+A backend for remote hardware should not be registered immediately. Applications can see that
+the sensor cannot be used. When the remote hardware becomes available the backend should be
+registered. Applications can see that the sensor is now available.
+
+If it is necessary to return 0 from a factory for a backend that was registered, the backend
+should be unregistered. Applications can see that the sensor is no longer available. If the
+factory can create the backend again it should be registered. Applications can see that the
+sensor is available again.
+
+When the underlying hardware is no longer available, the backend should be deregistered.
+Existing instances of the backend should report error states to the application but should
+handle the situation gracefully.
+
+*/
+
+/*!
+\page qml-sensors.html
+\title Sensors QML Plugin
+\brief A QML plugin for the QtMobility Project Sensors API.
+
+\section1 Overview
+
+The identifying string for this component is \e {"QtMobility.sensors"}.
+Use this in the QML \e {import} statement.
+
+The Sensors QML Plugin registers the C++ Sensors classes directly to the QML environment.
+This causes some limitations due to the use of types that do not work in the QML environment.
+See \l{Sensors QML Limitations}{below} for a list of the known limitations.
+
+See \l Sensors for more information about the Sensors API.
+
+\section1 Sensors QML Limitations
+
+The following limitations affect the Sensors QML bindings for Qt Mobility 1.1 and 1.2.
+
+\list 1
+\o The QSensor::sensorid property cannot be set because QML does not support QByteArray.
+   This means that it is not possible to specify a particular sensor when two or more have
+   been registered with the same type.
+\o The QSensor::availableDataRates property cannot be used because QML does not support \l qrangelist.
+\o The QSensor::outputRanges property cannot be used because QML does not support \l qoutputrangelist.
+\o The QLightSensor::fieldOfView property cannot be used because QML cannot access dynamic properties.
+\o The QMagnetometer::returnGeoValues property cannot be used because QML cannot access dynamic properties.
+\o The QRotationSensor::hasZ property cannot be used because QML cannot access dynamic properties.
+\o The QTapSensor::returnDoubleTapEvents property cannot be used because QML cannot access dynamic properties.
+\endlist
+
+\section1 QML Sensor Elements
+
+These elements represent specific types of sensors.
+
+\annotatedlist qml-sensors_type
+
+\section1 QML Reading Elements
+
+The data from a sensor comes through a reading class.
+
+\annotatedlist qml-sensors_reading
+
+*/
+
+/*!
+\page meego-integration-notes.html
+\title MeeGo Integration Notes
+\ingroup sensors_backend_topics
+
+\section1 MeeGo Integration Notes
+
+The implementation of the API builds on top of the MeeGo Sensor Framework
+that provides all the sensors specified in 1.2 API version.
+
+\section2 Available sensors
+
+If HW sensor is missing, the configuration file "Sensors.conf"
+must be updated and sensor removed. The file
+has the following format:
+
+\code
+[Default]
+QAccelerometer=meego.accelerometer
+QAmbientLightSensor=meego.als
+\endcode
+
+It lists sensor types and type's default implementation by giving the sensor id.
+If the type is omitted then the backend does not support it in this device; this
+gives a way of controlling and differentiating the supported sensor set.
+
+*/
+
diff --git a/doc/src/snippets/sensors/creating.cpp b/doc/src/snippets/sensors/creating.cpp
new file mode 100644
index 00000000..98e7d5df
--- /dev/null
+++ b/doc/src/snippets/sensors/creating.cpp
@@ -0,0 +1,64 @@
+/****************************************************************************
+**
+** 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$
+** GNU Lesser General Public License Usage
+** 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.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU General
+** Public License version 3.0 as published by the Free Software Foundation
+** and appearing in the file LICENSE.GPL included in the packaging of this
+** file. Please review the following information to ensure the GNU General
+** Public License version 3.0 requirements will be met:
+** http://www.gnu.org/copyleft/gpl.html.
+**
+** 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$
+**
+****************************************************************************/
+
+#include <QWidget>
+#include <qaccelerometer.h>
+#include <qorientationsensor.h>
+
+class MyWidget : public QWidget
+{
+    void create();
+};
+
+void MyWidget::create()
+{
+//! [Creating a sensor]
+// On the heap (deleted when this object is deleted)
+QAccelerometer *sensor = new QAccelerometer(this);
+
+// On the stack (deleted when the current scope ends)
+QOrientationSensor orient_sensor;
+//! [Creating a sensor]
+
+    Q_UNUSED(sensor)
+    Q_UNUSED(orient_sensor);
+}
+
diff --git a/doc/src/snippets/sensors/main.cpp b/doc/src/snippets/sensors/main.cpp
new file mode 100644
index 00000000..81e526cb
--- /dev/null
+++ b/doc/src/snippets/sensors/main.cpp
@@ -0,0 +1,46 @@
+/****************************************************************************
+**
+** 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$
+** GNU Lesser General Public License Usage
+** 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.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU General
+** Public License version 3.0 as published by the Free Software Foundation
+** and appearing in the file LICENSE.GPL included in the packaging of this
+** file. Please review the following information to ensure the GNU General
+** Public License version 3.0 requirements will be met:
+** http://www.gnu.org/copyleft/gpl.html.
+**
+** 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$
+**
+****************************************************************************/
+
+int main(int /*argc*/, char ** /*argv*/)
+{
+    return 0;
+}
+
diff --git a/doc/src/snippets/sensors/mybackend.h b/doc/src/snippets/sensors/mybackend.h
new file mode 100644
index 00000000..7a99caa5
--- /dev/null
+++ b/doc/src/snippets/sensors/mybackend.h
@@ -0,0 +1,59 @@
+/****************************************************************************
+**
+** 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$
+** GNU Lesser General Public License Usage
+** 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.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU General
+** Public License version 3.0 as published by the Free Software Foundation
+** and appearing in the file LICENSE.GPL included in the packaging of this
+** file. Please review the following information to ensure the GNU General
+** Public License version 3.0 requirements will be met:
+** http://www.gnu.org/copyleft/gpl.html.
+**
+** 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$
+**
+****************************************************************************/
+
+#ifndef MYBACKEND_H
+#define MYBACKEND_H
+
+#include <qaccelerometer.h>
+#include <qsensorbackend.h>
+
+class MyBackend : public QSensorBackend
+{
+public:
+    MyBackend(QSensor *sensor) : QSensorBackend(sensor) {}
+    void stop() {}
+    void start() {}
+    void poll() {}
+
+    static const char *id;
+};
+
+#endif
diff --git a/doc/src/snippets/sensors/plugin.cpp b/doc/src/snippets/sensors/plugin.cpp
new file mode 100644
index 00000000..7d548b77
--- /dev/null
+++ b/doc/src/snippets/sensors/plugin.cpp
@@ -0,0 +1,69 @@
+/****************************************************************************
+**
+** 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$
+** GNU Lesser General Public License Usage
+** 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.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU General
+** Public License version 3.0 as published by the Free Software Foundation
+** and appearing in the file LICENSE.GPL included in the packaging of this
+** file. Please review the following information to ensure the GNU General
+** Public License version 3.0 requirements will be met:
+** http://www.gnu.org/copyleft/gpl.html.
+**
+** 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$
+**
+****************************************************************************/
+
+#include "mybackend.h"
+#include <qsensorplugin.h>
+#include <qsensormanager.h>
+
+const char *MyBackend::id = "mybackend";
+
+//! [Plugin]
+class MyPluginClass : public QObject, QSensorPluginInterface, public QSensorBackendFactory
+{
+    Q_OBJECT
+    Q_INTERFACES(QSensorPluginInterface)
+public:
+    void registerSensors()
+    {
+        QSensorManager::registerBackend(QAccelerometer::type, MyBackend::id, this);
+    }
+
+    QSensorBackend *createBackend(QSensor *sensor)
+    {
+        if (sensor->identifier() == MyBackend::id)
+            return new MyBackend(sensor);
+        return 0;
+    }
+};
+//! [Plugin]
+
+//Q_EXPORT_PLUGIN2(libmy_plugin_file_name, MyPluginClass);
+#include "plugin.moc"
diff --git a/doc/src/snippets/sensors/sensors.pro b/doc/src/snippets/sensors/sensors.pro
new file mode 100644
index 00000000..61a00955
--- /dev/null
+++ b/doc/src/snippets/sensors/sensors.pro
@@ -0,0 +1,9 @@
+TEMPLATE=app
+TARGET=sensorsdocsnippet
+QT += sensors
+SOURCES+=main.cpp\
+    creating.cpp\
+    start.cpp\
+    plugin.cpp
+HEADERS+=mybackend.h
+LIBS+=-rdynamic
diff --git a/doc/src/snippets/sensors/start.cpp b/doc/src/snippets/sensors/start.cpp
new file mode 100644
index 00000000..85fe1ed7
--- /dev/null
+++ b/doc/src/snippets/sensors/start.cpp
@@ -0,0 +1,59 @@
+/****************************************************************************
+**
+** 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$
+** GNU Lesser General Public License Usage
+** 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.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU General
+** Public License version 3.0 as published by the Free Software Foundation
+** and appearing in the file LICENSE.GPL included in the packaging of this
+** file. Please review the following information to ensure the GNU General
+** Public License version 3.0 requirements will be met:
+** http://www.gnu.org/copyleft/gpl.html.
+**
+** 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$
+**
+****************************************************************************/
+
+#include <qsensor.h>
+
+void start()
+{
+//! [Starting a sensor]
+// start the sensor
+QSensor sensor("QAccelerometer");
+sensor.start();
+
+// later
+QSensorReading *reading = sensor.reading();
+qreal x = reading->property("x").value<qreal>();
+qreal y = reading->value(1).value<qreal>();
+//! [Starting a sensor]
+
+    Q_UNUSED(x)
+    Q_UNUSED(y)
+}
diff --git a/doc/src/snippets/snippets.pro b/doc/src/snippets/snippets.pro
new file mode 100644
index 00000000..0685c62c
--- /dev/null
+++ b/doc/src/snippets/snippets.pro
@@ -0,0 +1,3 @@
+TEMPLATE = subdirs
+
+SUBDIRS += sensors