diff options
author | Geir Vattekar <geir.vattekar@digia.com> | 2012-10-04 13:48:23 +0200 |
---|---|---|
committer | The Qt Project <gerrit-noreply@qt-project.org> | 2012-10-12 15:16:15 +0200 |
commit | 9d4d08421acb628e0115b140e54656fc779d13db (patch) | |
tree | eb87c8fbbe0722f70fa536227fa7a311febdea81 /src/sensors/doc/src/qtsensors-cpp.qdoc | |
parent | 8f624bb5d19edb47fc4803a5eb0d6343de5bbae9 (diff) | |
download | qtsensors-9d4d08421acb628e0115b140e54656fc779d13db.tar.gz |
Doc: Modularized the Qt Sensor Docs
Change-Id: Ie8636ec443f43b1f238342e0f6f7d321e13dce09
Reviewed-by: Jerome Pasion <jerome.pasion@digia.com>
Diffstat (limited to 'src/sensors/doc/src/qtsensors-cpp.qdoc')
-rw-r--r-- | src/sensors/doc/src/qtsensors-cpp.qdoc | 150 |
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 0000000..2f60592 --- /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 + +*/ + |