/****************************************************************************
**
** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/
**
** 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 qtsensors-cpp.html
\title Qt Sensors C++ API
\brief Information about the Qt Sensors C++ API

\tableofcontents

\section1 Sensor Types

On a device there can be many types of sensors. Not all of the types that the Qt Sensors API
supports may be available. There may also be types available that are not defined in the
Qt Sensors API. The types of sensors available on a device is found 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, Qt Sensors uses 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 QSensor is typically:

\list
\li Create an instance of QSensor or one of its sub-classes on the stack or heap.
\li Setup as required by the application.
\li Start receiving values.
\li Sensor data is used by the application.
\li 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
\li The sensor type.
\li The property name or index.
\li 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 Front end, back end

The Qt 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{Qt Sensors Backend}.

\section1 Main Classes

The primary classes that make up the Qt 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 Qt 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

*/