/****************************************************************************
**
** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Digia.  For licensing terms and
** conditions see http://qt.digia.com/licensing.  For further information
** use the contact form at http://qt.digia.com/contact-us.
**
** GNU Free Documentation License Usage
** 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.  Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
\page qtsensors-cpp.html
\title Qt Sensors C++ Overview
\brief Explains how to use 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 specified otherwise, 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 relative to \l QPlatformScreen::nativeOrientation,
that is to the top of the device when the device is held in its natural orientation
(normally when the device logo appears the right side up). 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 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 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

*/