// Copyright (C) 2017 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!
\page qtsensors-cpp.html
\title Qt Sensors C++ Overview
\brief Explains how to use the Qt Sensors C++ API.
\ingroup explanation

\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 QScreen::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.

\section1 Discovering Sensors And Reading Properties At Runtime

Sometimes it may be that the available sensors are not known at development time.
It is possible to find out which sensors are available as illustrated below:

\snippet sensors/start.cpp Find sensors

Furthermore it is possible to discover the reading details for these sensors, as illustrated below:

\snippet sensors/start.cpp Print reading properties

\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

*/

