summaryrefslogtreecommitdiffstats
path: root/src/sensors/doc/src/qtsensors-cpp.qdoc
diff options
context:
space:
mode:
Diffstat (limited to 'src/sensors/doc/src/qtsensors-cpp.qdoc')
-rw-r--r--src/sensors/doc/src/qtsensors-cpp.qdoc150
1 files changed, 150 insertions, 0 deletions
diff --git a/src/sensors/doc/src/qtsensors-cpp.qdoc b/src/sensors/doc/src/qtsensors-cpp.qdoc
new file mode 100644
index 00000000..2f60592a
--- /dev/null
+++ b/src/sensors/doc/src/qtsensors-cpp.qdoc
@@ -0,0 +1,150 @@
+/****************************************************************************
+**
+** 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 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 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
+
+*/
+