diff options
Diffstat (limited to 'src/sensors/doc/src')
| -rw-r--r-- | src/sensors/doc/src/compatmap.qdoc | 142 | ||||
| -rw-r--r-- | src/sensors/doc/src/genericbackend.qdoc | 55 | ||||
| -rw-r--r-- | src/sensors/doc/src/porting.qdoc | 121 | ||||
| -rw-r--r-- | src/sensors/doc/src/qtmobilitysensors1.qdoc | 74 | ||||
| -rw-r--r-- | src/sensors/doc/src/qtsensorgestures-cpp.qdoc | 60 | ||||
| -rw-r--r-- | src/sensors/doc/src/qtsensorgestures-emulator.qdoc | 51 | ||||
| -rw-r--r-- | src/sensors/doc/src/qtsensorgestures-plugins.qdoc | 167 | ||||
| -rw-r--r-- | src/sensors/doc/src/qtsensors-backend.qdoc | 184 | ||||
| -rw-r--r-- | src/sensors/doc/src/qtsensors-cpp.qdoc | 150 | ||||
| -rw-r--r-- | src/sensors/doc/src/qtsensors.qdoc | 117 | ||||
| -rw-r--r-- | src/sensors/doc/src/qtsensors5.qdoc | 78 | ||||
| -rw-r--r-- | src/sensors/doc/src/sensor-examples.qdoc | 40 |
12 files changed, 1239 insertions, 0 deletions
diff --git a/src/sensors/doc/src/compatmap.qdoc b/src/sensors/doc/src/compatmap.qdoc new file mode 100644 index 00000000..0fd4951c --- /dev/null +++ b/src/sensors/doc/src/compatmap.qdoc @@ -0,0 +1,142 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Research In Motion +** 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 compatmap.html + \title Compatibility Map + \brief Overview of supported sensors for each platform + + \raw HTML + + <table cellpadding="2" cellspacing="1" border="1" width="90%"> + <tbody> + <tr> + <td>Color</td> + <td>Explanation</td> + </tr> + <tr> + <td bgcolor="green"></td> + <td>The feature is fully supported.</td> + </tr> + <tr> + <td bgcolor="gray"></td> + <td>The feature is not supported.</td> + </tr> + </tbody> + </table> + + <table align="center" cellpadding="2" cellspacing="1" border="1" rules="all" width="90%"> + <tbody> + <tr> + <td><b>Feature</b></td> + <td><b>Blackberry</b></td> + <td><b>Linux</b></td> + <td><b>Generic</b></td> + </tr> + <tr> + <td nowrap="nowrap">Accelerometer</td> + <td bgcolor="green"></td> + <td bgcolor="green"></td> + <td bgcolor="gray"></td> + </tr> + <tr> + <td nowrap="nowrap">Ambient Light Sensor</td> + <td bgcolor="green"></td> + <td bgcolor="gray"></td> + <td bgcolor="green"></td> + </tr> + <tr> + <td nowrap="nowrap">Compass</td> + <td bgcolor="green"></td> + <td bgcolor="gray"></td> + <td bgcolor="gray"></td> + </tr> + <tr> + <td nowrap="nowrap">Gyroscope</td> + <td bgcolor="green"></td> + <td bgcolor="gray"></td> + <td bgcolor="gray"></td> + </tr> + <tr> + <td nowrap="nowrap">IR Proximity Sensor</td> + <td bgcolor="green"></td> + <td bgcolor="gray"></td> + <td bgcolor="gray"></td> + </tr> + <tr> + <td nowrap="nowrap">Light Sensor</td> + <td bgcolor="green"></td> + <td bgcolor="gray"></td> + <td bgcolor="gray"></td> + </tr> + <tr> + <td nowrap="nowrap">Magnetometer</td> + <td bgcolor="green"></td> + <td bgcolor="gray"></td> + <td bgcolor="gray"></td> + </tr> + <tr> + <td nowrap="nowrap">Orientation Sensor</td> + <td bgcolor="green"></td> + <td bgcolor="gray"></td> + <td bgcolor="green"></td> + </tr> + <tr> + <td nowrap="nowrap">Proximity Sensor</td> + <td bgcolor="green"></td> + <td bgcolor="gray"></td> + <td bgcolor="gray"></td> + </tr> + <tr> + <td nowrap="nowrap">Rotation Sensor</td> + <td bgcolor="green"></td> + <td bgcolor="gray"></td> + <td bgcolor="green"></td> + </tr> + <tr> + <td nowrap="nowrap">Tap Sensor</td> + <td bgcolor="gray"></td> + <td bgcolor="gray"></td> + <td bgcolor="gray"></td> + </tr> + <tr> + <td nowrap="nowrap">Sensor Gestures</td> + <td bgcolor="gray"></td> + <td bgcolor="gray"></td> + <td bgcolor="green">1)</td> + </tr> + </table> + + \endraw + + 1) Support depends on the underlying platform + + In addition to the table above, each sensor type might support specific features. For example + a magnetometer might support returning geo values. See QSensor::isFeatureSupported() for + additional details. +*/ + diff --git a/src/sensors/doc/src/genericbackend.qdoc b/src/sensors/doc/src/genericbackend.qdoc new file mode 100644 index 00000000..689b4124 --- /dev/null +++ b/src/sensors/doc/src/genericbackend.qdoc @@ -0,0 +1,55 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Research In Motion +** 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 genericbackend.html + \title Generic Backend + \brief Information about the generic sensor backend + + The generic sensor backend provides emulation of some of the sensors that are not supported on the + platform. + For example, on a platform without a rotation sensor but with an accelerometer, the accelerometer + is used to calculate the rotation, thus providing an emulated rotation sensor. + + The following generic sensors are supported: + \table + \header + \li Emulated Sensor + \li Source Sensor + \row + \li Ambient Light Sensor + \li Light Sensor + \row + \li Orientation Sensor + \li Accelerometer + \row + \li Rotation Sensor + \li Accelerometer + \endtable + If a platform doesn't support the source sensor, then the sensor can not be emulated. +*/ + diff --git a/src/sensors/doc/src/porting.qdoc b/src/sensors/doc/src/porting.qdoc new file mode 100644 index 00000000..b52da351 --- /dev/null +++ b/src/sensors/doc/src/porting.qdoc @@ -0,0 +1,121 @@ +/**************************************************************************** +** +** 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-porting.html + \title Porting Applications from QtMobility Sensors to Qt Sensors + + \tableofcontents + + \section1 Overview + + The initial release of Qt Sensors (5.0) is generally expected to be source + compatible with QtMobility Sensors 1.2. This document attempts to explain + where things must be changed in order to port applications to Qt Sensors. + + \section1 QML + + Compatibility for QML applications is provided by shipping the legacy \c QtMobility.sensors + QML import. QML applications should not require any changes to continue operating. + + Applications using the legacy QML import may not be able to trivially port over + to the new QML import because the new QML import does not provide types for + every sensor like the legacy QML import does. + + \table + \row + \li \l {Qt Sensors QML Types}{QML API} + \li Information about the Qt Sensors QML API + \row + \li \l {QtMobility.sensors 1.x}{Legacy QML API} + \li Information about the legacy QtMobility.sensors QML API + \endtable + + \section1 C++ + + \section2 Includes + + QtMobility Sensors installed headers into a \c Qt Sensors directory. This is + also the directory that Qt Sensors uses. It is therefore expected that includes + that worked with QtMobility Sensors should continue to work. + + For example: + \code + #include <QAccelerometer> + #include <qaccelerometer.h> + #include <QtSensors/QAccelerometer> + #include <QtSensors/qaccelerometer.h> + \endcode + + \section2 Macros and Namespace + + QtMobility Sensors was built in a \c QtMobility namespace. This was enabled by + the use of various macros. Qt Sensors does not normally build into a namespace + and the macros from QtMobility no longer exist. + + \list + \li QTM_BEGIN_NAMESPACE + \li QTM_END_NAMESPACE + \li QTM_USE_NAMESPACE + \li QTM_PREPEND_NAMESPACE(x) + \endlist + + Note that Qt can be configured to build into a namespace. If Qt is built in this + way then Qt Sensors is also built into the nominated namespace. However, as this + is optional, the macros for this are typically defined to do nothing. + + \list + \li QT_BEGIN_NAMESPACE + \li QT_END_NAMESPACE + \li QT_USE_NAMESPACE + \li QT_PREPEND_NAMESPACE(x) + \endlist + + \section2 qtimestamp + + qtimestamp was previously defined as an opaque type equivalent to a quint64. It existed + as a class due to an implementation detail. + + In Qt Sensors, the API uses quint64 instead of qtimestamp. qtimestamp still exists as a + typedef so that applications that refer to qtimestamp can be compiled. + + \section1 Project Files + + QtMobility Sensors applications used this in their project files to enable the Sensors API. + + \code + CONFIG += mobility + MOBILITY += sensors + \endcode + + Applications should remove these lines and instead use this to enable the Qt Sensors API. + + \code + QT += sensors + \endcode +*/ + diff --git a/src/sensors/doc/src/qtmobilitysensors1.qdoc b/src/sensors/doc/src/qtmobilitysensors1.qdoc new file mode 100644 index 00000000..f9ba814f --- /dev/null +++ b/src/sensors/doc/src/qtmobilitysensors1.qdoc @@ -0,0 +1,74 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \qmlmodule QtMobility.sensors 1.3 + \title QtMobility.sensors 1.x + \brief Legacy QML import for QtSensors + + \section1 Overview + + This is the legacy QML import. It exists for compatibility with the QtMobiltiy 1.2 release + and is not recommended for new applications. + + See \l{Qt Sensors} for more information about the Sensors API. + + \section1 QML Module API + + See \l {Qt Sensors} for more information about the Sensors API. + + If the module is imported into a namespace, some additional methods become available. + + \code + import QtMobility.sensors 1.3 as Sensors + ... + Component.onCompleted: { + var types = Sensors.sensorTypes(); + console.log(types.join(", ")); + } + \endcode + + The documentation for the module API can be found in SensorGlobal. + + \section1 QML Sensor types + + These types represent specific types of sensors. + + Note that most properties come from the abstract \l{QtMobility.sensors1::Sensor}{Sensor} element. + + \annotatedlist qml-sensors_type + + \section1 QML Reading types + + The data from a sensor comes through a reading class. + + \annotatedlist qml-sensors_reading + + \section1 Alphabetical Listing of QML Types + +*/ + diff --git a/src/sensors/doc/src/qtsensorgestures-cpp.qdoc b/src/sensors/doc/src/qtsensorgestures-cpp.qdoc new file mode 100644 index 00000000..e78ce4d6 --- /dev/null +++ b/src/sensors/doc/src/qtsensorgestures-cpp.qdoc @@ -0,0 +1,60 @@ +/**************************************************************************** +** +** 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 qtsensorgestures-cpp.html +\title Sensor Gestures C++ Overview +\brief Information about the QtSensorGestures C++ API + +\tableofcontents + +\section1 Using QtSensorGestures + +With the Sensor Gestures classes, you are able to easily utilize device gesturing using +sensors such as the accelerometer and proximity. + +A list of currently supported sensor gestures and their descriptions can be found here: +\l {Qt Sensor Gestures} + +Using QtSensorGestures is easy. There are two main classes you will need to use. + +QSensorGestureManager can be used for determining what sensor gestures are available, and +QSensorGesture for connecting the sensor gesture signals. + +\snippet sensorgestures/creating.cpp Receiving sensor gesture signals + +More information about the sensor gesture recognizers can be found in +\l{QtSensorGestures Plugins}. + +\section1 Main Classes + +The primary classes that make up the QtSensorGestures API. + +\annotatedlist sensorgestures_main + +*/ + diff --git a/src/sensors/doc/src/qtsensorgestures-emulator.qdoc b/src/sensors/doc/src/qtsensorgestures-emulator.qdoc new file mode 100644 index 00000000..af061e2a --- /dev/null +++ b/src/sensors/doc/src/qtsensorgestures-emulator.qdoc @@ -0,0 +1,51 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +/*! +\group sensorgesture_emulator_topics +\title QtSensorGestures Emulator +\brief Information about the development of clients and recognizer plugins + using QtSensorGestures + +\section1 Overview + +Whether creating client apps using Qt's built-in sensor gestures, or +creating customized recognizers, the Emulator can be used to help develop client +apps and recognizers. + +\section1 Developing sensor gesture clients. + +For instance, the Emulator can be used for writing a client app that needs +to use the 'slam' gesture. + +Under the 'Sensors' heading in the Emulator control, you will see an edit +box for 'Sensor gestures' that will contain a list of signals available +when your client instantiates a QSensorGesture. + +Select 'slam', and then click the 'Send' button +to send a detected("slam") signal to the client. + +*/ diff --git a/src/sensors/doc/src/qtsensorgestures-plugins.qdoc b/src/sensors/doc/src/qtsensorgestures-plugins.qdoc new file mode 100644 index 00000000..67734aad --- /dev/null +++ b/src/sensors/doc/src/qtsensorgestures-plugins.qdoc @@ -0,0 +1,167 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! +\group sensorgesture_plugins_topics +\title QtSensorGestures Plugins +\brief Information about the QtSensorGestures recognizer plugins. + +The QtSensorGestures recognizer plugins are the way to create your own +sensor gestures. + +Creating software to recognize motion gestures using sensors is a huge subject not covered here. + +The QSensorGesture API does not limit usage to any of the common classification methods of gesture +recognition such as Hidden Markov Models, Neural Networks, Dynamic Time Warping, or even the +ad-hoc heuristic recognizers of Qt's built-in sensor gesture recognizers. It's basically a +signaling system for lower level gesture recogition methods and algorithms to communicate to the +higher level applications. + +\tableofcontents + +\section1 Overview + + The steps to creating a sensor gesture plugin are as follows: +\list +\li Sub-class from QSensorGesturePluginInterface +\li Sub-class from QSensorGestureRecognizer and implement gesture recognizer logic using QtSensors. +\li Create an instance of that recognizer in the derived QSensorGesturePluginInterface class, and call + QSensorGestureManager::registerSensorGestureRecognizer(sRec); in your registerRecognizers() +function. QSensorGestureManager will retain ownership of the recognizer object. + +This is the class in which the gesture recognizer system should be implemented from. + +\endlist + +\snippet sensorgestures/plugin.cpp Plugin + + +\section2 Recognizer Classes + +If you are making sensorgestures available through the QtSensorGestures API, these are the +classes to subclass. + +\annotatedlist sensorgestures_recognizer + +\target Qt Sensor Gestures +\section3 Recognizer Plugins + +The Sensor Gesture Recognizers that come with Qt are made using an ad-hock heurustic approach. +The user cannot define their own gestures, and must learn how to perform and accomodate the +pre-defined gestures herein. + +A developer may use any method including computationally and training intensive well + known classifiers, to produce gesture recognizers. There are currently no classes in Qt for +gesture training, nor ability for the user to define their own sensor based motion gestures. + +A procedure for writing ad-hock recognizers might include: +\list + \li Obtain and gather output from the accelerometer through QAccelerometerReading of a gesture being performed. + \li Use various methods and constraints on the accelerometer data to recognize the various states: + \list i + \li Initial 'listening' state for a gesture + \li Start of a possible gesture, moving into a 'detecting' state + \li End of a possible gesture, moving into a 'recognizing' state + \li and finally, if it is recognized, the 'recognized' state, or if not recognized, move back to + the 'listening' state. + \endlist + \li Test procedure to make sure it is easy to perform, and will not + produce too many false positive recognitions. And if used with other gestures, collisions. Meaning +that gestures performed get recognized as another gesture instead. + +\endlist + +Here is a list of included plugins and their signals + +For ShakeGestures plugin: + \table + \row + \li Recognizer Id + \li Signals + \row + \li QtSensors.shake + \li shake +\endtable + +For QtSensorGestures plugin: + \table + \row + \li Recognizer Id + \li Signals + \li Description + \li Images + \row + \li QtSensors.cover + \li cover + \li Hand covers up phone display for one second, when it's face up, using the Proximity and Orientation sensors. + \li \image sensorgesture-cover.png + \row + \li QtSensors.doubletap + \li doubletap + \li Double tap of finger on phone, using the DoubleTap sensor. + \li \image sensorgesture-doubletap.png + \row + \li QtSensors.hover + \li hover + \li Hand hovers about 4 cm above the phone for more than 1 second, then is removed when face up, + using the IR Proximity sensor. + \li \image sensorgesture-hover.png + \row + \li QtSensors.pickup + \li pickup + \li Phone is resting face up on a flat curface, and is then picked up and brought up into viewing position, using the Accelerometer sensor. + \li \image sensorgesture-faceup.png + \row + \li QtSensors.shake2 + \li shakeLeft, shakeRight, shakeUp, shakeDown + \li Shake phone in a certain direction, using the Accelerometer sensor. + \li \image sensorgesture-shake.png + \row + \li QtSensors.slam + \li slam + \li Phone is held in a top up position with a side facing forward for a moment. Swing it quickly with a downward motion + like it is being used to point at something with the top corner. using the Accelerometer and Orientation sensors. + \li \image sensorgesture-slam_1.png + \image sensorgesture-slam_2.png + \row + \li QtSensors.turnover + \li turnover + \li Phone is turned face down and placed on a surface, using Proximity and Orientation sensors. + \li \image sensorgesture-facedown.png + \row + \li QtSensors.twist + \li twistLeft, twistRight + \li Phone is held face up and then twisted left or right (left side up or right side up) and back, using the Accelerometer and Orientation sensors. + \li \image sensorgesture-twist.png + \row + \li QtSensors.whip + \li whip + \li Move phone quickly down and then back up. using the Accelerometer and Orientation sensors. + \li \image sensorgesture-whip.png + \endtable + +*/ diff --git a/src/sensors/doc/src/qtsensors-backend.qdoc b/src/sensors/doc/src/qtsensors-backend.qdoc new file mode 100644 index 00000000..e26c05ad --- /dev/null +++ b/src/sensors/doc/src/qtsensors-backend.qdoc @@ -0,0 +1,184 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! +\group sensors_backend_topics +\title Qt Sensors Backend +\brief Information about the Qt Sensors back end + +The Qt Sensors backend connects the Qt Sensors API to the platform services or hardware sensors. + +\tableofcontents + +\section1 Overview + +\section1 Backend API + +QSensor instances talk to a backend object. Backends are usually supplied +with the Qt Sensors library for a specific device although third party +backends may be used as well. A backend may talk +directly to hardware or it may talk to a system service. In some instances +it may even talk to another sensor. +An example of this is the orientation sensor backend that talks to an +accelerometer to determine the device orientation. + +\section1 Backend Classes +If you are making sensors available through the Sensors API, these are the +classes to use. +\annotatedlist sensors_backend + +\section1 Backend Topics + +\generatelist related + +*/ + +/*! +\page creating-a-sensor-plugin.html +\title Creating a sensor plugin +\ingroup sensors_backend_topics + +\section1 How a sensor plugin is loaded + +Since sensor backends are created on demand, the sensor plugin is loaded and asked +to register the sensor backends it handles. The plugin should implement +QSensorPluginInterface::registerSensors() and call QSensorManager::registerBackend() +to register available backends. Typically the plugin will also inherit from +QSensorBackendFactory and implement +QSensorBackendFactory::createBackend() in order to instantiate backends it has registered. + +The simplest plugin will have just once sensor backend although there is no reason +that multiple sensor backends cannot be in a plugin. + +An example follows. + +\snippet sensors/plugin.cpp Plugin + +*/ + +/*! +\page determining-the-default-sensor-for-a-type.html +\title Determining the default sensor for a type +\ingroup sensors_backend_topics + +\section1 Multiple sensors can exist for a type + +Sensors was designed so that multiple sensors could exist for a given type. Why? +Consider this example. + +The N900 has an accelerometer built-in. It also features bluetooth and can pair +with a gaming controller that features an accelerometer. To a developer writing +a game these two devices are conceptually the same type. + +\section1 Default sensor for a type + +To avoid the need to know (or check) what the default sensor for a type is, the system will +use the default sensor for a type. Most of the time this is what the app developer wants to +do. In cases where the app developer wants to select a specific sensor they must call the +QSensor::setIdentifier() method before they start the sensor so that the appropriate backend +is used. + +From a system perspective though, selecting which sensor should be the default gets tricky. +The sensors library uses the first registered identifier as the default. This means that the +order in which sensor backends are registered is important so the system will allow a config +file to determine the default instead. + +\section1 Sensors.conf + +The config file that determines the default sensor for a type is called Sensors.conf. If present, +it is located in /etc/xdg/Nokia. It has the standard formatting of an ini file. + +The settings live in the Default group and the general format is: +\code +type = identifier +\endcode + +An example Sensors.conf that ensures the N900 accelerometer is used as the default no matter the +order in which backends were registered is presented here. + +\code +[Default] +QAccelerometer = n900.accelerometer +\endcode + +If Sensors.conf specifies an identifier that is not registered then the system will fall back to +the first registered identifier as the default. + +Note that there is special case logic to prevent the generic plugin's backends from becoming the +default when another backend is registered for the same type. This logic means that a backend +identifier starting with \c{generic.} will only be the default if no other backends have been +registered for that type or if it is specified in \c{Sensors.conf}. + +*/ + +/*! +\page dynamic-sensor-backend-registration.html +\title Dynamic Sensor Backend Registration +\ingroup sensors_backend_topics + +\section1 Static Backend Registration + +Sensor backends are generally registered statically. The registration happens when the sensors +library is first used and the registration remains in effect while the program runs. + +\image sensors-static.png + +Statically registered backends may still exhibit some dynamic behaviour as the +QSensorBackendFactory is free to return 0 to indicate that a backend cannot be created. + +\section1 Dynamic Backend Registration + +While static registration is fine for most backends there are some situations where this is +problematic. + +The clearest example is backends that represent non-fixed hardware. As an example, lets consider +a game controller that is connected via Bluetooth. As there may be more than one game controller +in range of the phone, the program wants to record that a specific game controller should be used. +If the backend had been registered statically there would have been no unique information about +the controller. Instead, the registration is delayed until the controller is seen. + +\image sensors-dynamic.png + +\section1 Suggested Registration Policy + +A backend for fixed hardware should be registered immediately. Applications can see that the +sensor can be used. + +A backend for remote hardware should not be registered immediately. Applications can see that +the sensor cannot be used. When the remote hardware becomes available the backend should be +registered. Applications can see that the sensor is now available. + +If it is necessary to return 0 from a factory for a backend that was registered, the backend +should be unregistered. Applications can see that the sensor is no longer available. If the +factory can create the backend again it should be registered. Applications can see that the +sensor is available again. + +When the underlying hardware is no longer available, the backend should be deregistered. +Existing instances of the backend should report error states to the application but should +handle the situation gracefully. + +*/ 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 + +*/ + diff --git a/src/sensors/doc/src/qtsensors.qdoc b/src/sensors/doc/src/qtsensors.qdoc new file mode 100644 index 00000000..61286733 --- /dev/null +++ b/src/sensors/doc/src/qtsensors.qdoc @@ -0,0 +1,117 @@ +/**************************************************************************** +** +** 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-index.html + \title Qt Sensors + \brief The Qt Sensors API provides access to sensors via QML and C++ interfaces. + \ingroup technology-apis + + The Qt Sensors API provides access to sensor hardware via QML and C++ interfaces. + The Qt Sensors API also provides motion gesture recognition API for devices. + + \section1 Information for Application Writers + + Applications can access Qt Sensors using QML or C++. + + \table + \row + \li \l {Qt Sensors QML Types}{QML Types} + \li Information about the Qt Sensors QML API + \row + \li \l {Qt Sensors C++ Classes}{C++ Classes} + \li Information about the Qt Sensors C++ API + \row + \li \l{Qt Sensors C++ Overview} + \li High-level information on how to use the C++ API. + \row + \li \l {Sensor Gestures C++ Overview} + \li High-level information specific to sensor gestures. + \row + \li \l {Qt Sensors Examples}{Examples} + \li Examples demonstrating use of the Qt Sensors APIs + \endtable + + \section1 Information for Backend Implementors + + \table + \row + \li \l {Qt Sensors Backend}{Backend} + \li Information about the Qt Sensors back end + \row + \li \l {Qt Sensors - Grue Sensor Example} + \li The Qt Sensors - Grue Sensor Example demonstrates creation of a sensor backend + \endtable + + \section1 Compatibility with QtMobility Sensors API + + Qt Sensors 5.0 (the initial release) is generally expected to be source compatible + with QtMobility Sensors 1.2. + + \table + \row + \li \l {Porting Applications from QtMobility Sensors to Qt Sensors}{Porting Guide} + \li Information about the steps needed to port applications to the Qt Sensors API. + \endtable + + \omit + \section1 Information for Qt SensorGestures API + + Qt SensorGestures provides a motion gesture recognition API for devices. + + \table + \row + \li \l {SensorGesture}{QML API} + \li Information about the Qt SensorGestures QML API + \row + \li \l {QtSensorGestures C++ API}{C++ API} + \li Information about the Qt SensorGestures C++ API + \endtable + + \section1 Information for Qt SensorGestures Recognizer Plugin Implementors. + + \table + \row + \li \l {QtSensorGestures Plugins}{Plugins} + \li Information about the Qt SensorGestures recognizer plugins. + \row + \li \l {QtSensorGestures Emulator}{Emulator} + \li Information about Qt SensorGestures use in the Emulator. + \endtable + \endomit + + \section1 Platform-specific Information + \table + \row + \li \l {Compatibility Map}{Compatibility Map} + \li Compatibility map of all supported platforms. + \row + \li \l {Generic Backend}{Generic Backend} + \li Information about the generic sensor backend. + \endtable +*/ + diff --git a/src/sensors/doc/src/qtsensors5.qdoc b/src/sensors/doc/src/qtsensors5.qdoc new file mode 100644 index 00000000..71b62dae --- /dev/null +++ b/src/sensors/doc/src/qtsensors5.qdoc @@ -0,0 +1,78 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + + +/*! + \module QtSensors + \title Qt Sensors C++ Classes + \ingroup modules + + \brief The QtSensors module provides classes for reading sensor data. + + Mobile devices contains sensor hardware that allow detecting changes in various physical + properties of the device itself or its immediate environment. Examples of device properties + include the angle at which the device is held, whereas environmental properties include for + example the current level of ambient light. +*/ + +/*! + \qmlmodule QtSensors 5 + \title Qt Sensors QML Types + \ingroup qmlmodules + + \brief The QtSensors QML module provides types for reading sensor data. + + \section1 QML Module API + + If the module is imported into a namespace, some additional methods become available. + + \code + import QtSensors 5.0 as Sensors + ... + Component.onCompleted: { + var types = Sensors.sensorTypes(); + console.log(types.join(", ")); + } + \endcode + + The documentation for the module API can be found in SensorGlobal. + + \section1 QML Sensor types + + These types represent specific types of sensors. + + Note that most properties come from the abstract \l{QtSensors::Sensor}{Sensor} element. + + \annotatedlist qml-sensors_type + + \section1 QML Reading types + + The data from a sensor comes through a reading class. + + \annotatedlist qml-sensors_reading +*/ + diff --git a/src/sensors/doc/src/sensor-examples.qdoc b/src/sensors/doc/src/sensor-examples.qdoc new file mode 100644 index 00000000..d934c8a0 --- /dev/null +++ b/src/sensors/doc/src/sensor-examples.qdoc @@ -0,0 +1,40 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \group qtsensors-examples + \title Qt Sensors Examples + \brief Examples for the Qt Sensors module + \ingroup all-examples + + These are the Qt Sensors examples. + + \generatelist related +*/ + + + |