diff options
| -rw-r--r-- | doc/src/examples/sensors.qdoc | 1 | ||||
| -rw-r--r-- | doc/src/imports/qtmobilitysensors1.qdoc | 1 | ||||
| -rw-r--r-- | doc/src/imports/qtsensors5.qdoc | 1 | ||||
| -rw-r--r-- | doc/src/qtsensors-backend.qdoc (renamed from doc/src/sensors.qdoc) | 158 | ||||
| -rw-r--r-- | doc/src/qtsensors-cpp.qdoc | 150 | ||||
| -rw-r--r-- | doc/src/qtsensors.qdoc | 89 |
6 files changed, 246 insertions, 154 deletions
diff --git a/doc/src/examples/sensors.qdoc b/doc/src/examples/sensors.qdoc index 3c045256..db02d7d6 100644 --- a/doc/src/examples/sensors.qdoc +++ b/doc/src/examples/sensors.qdoc @@ -30,7 +30,6 @@ \title QtSensors Examples \brief Examples for the QtSensors module \ingroup all-examples - \ingroup qtsensors These are the QtSensors examples. diff --git a/doc/src/imports/qtmobilitysensors1.qdoc b/doc/src/imports/qtmobilitysensors1.qdoc index f47c96be..913e35cc 100644 --- a/doc/src/imports/qtmobilitysensors1.qdoc +++ b/doc/src/imports/qtmobilitysensors1.qdoc @@ -29,7 +29,6 @@ \qmlmodule QtMobility.sensors 1 \title QtMobility.sensors 1.x \brief Legacy QML import for QtSensors - \ingroup qtsensors \section1 Overview diff --git a/doc/src/imports/qtsensors5.qdoc b/doc/src/imports/qtsensors5.qdoc index ed28985c..80fde894 100644 --- a/doc/src/imports/qtsensors5.qdoc +++ b/doc/src/imports/qtsensors5.qdoc @@ -29,7 +29,6 @@ \qmlmodule QtSensors 5 \title QtSensors 5.x \brief The QML import for QtSensors - \ingroup qtsensors \section1 Overview diff --git a/doc/src/sensors.qdoc b/doc/src/qtsensors-backend.qdoc index 36bb441a..814cb5a6 100644 --- a/doc/src/sensors.qdoc +++ b/doc/src/qtsensors-backend.qdoc @@ -26,148 +26,11 @@ ****************************************************************************/ /*! - \group qtsensors - \title QtSensors - \brief The QtSensors API provides access to sensors via QML and C++ interfaces. - \ingroup technology-apis - - The QtSensors API provides access to sensors via QML and C++ interfaces. - - \section1 Topics - - \generatelist related -*/ - -/*! -\page qtsensors-cpp.html -\title QtSensors C++ API -\brief Information about the QtSensors C++ API -\ingroup qtsensors - -\tableofcontents - -\section1 Sensor Types - -On a device there can be many types of sensors. Not all of the types that the Sensors API -supports may be available. There may also be types available that are not defined in the -Sensors API. You can find the sensor types available on a device 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, sensors shall use 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 sensor is typically: - -\list -\o Create an instance of QSensor or one of its sub-classes on the stack or heap. -\o Setup as required by the application. -\o Start receiving values. -\o Sensor data is used by the application. -\o Stop receiving values. -\endlist - -Here is an example of creating a sensor on the heap and on the stack. - -\snippet snippets/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 -\o The sensor type. -\o The property name or index. -\o 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 snippets/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 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{Sensors Backend}. - -\section1 Main Classes - -The primary classes that make up the 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 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 - -*/ - -/*! -\page sensors-backend.html -\title Sensors Backend -\brief The Sensors Backend connects the Sensors API to the platform services or hardware sensors. +\group sensors_backend_topics +\title QtSensors Backend +\brief Information about the QtSensors back end -The Sensors Backend connects the Sensors API to the platform services or hardware sensors. +The QtSensors backend connects the QtSensors API to the platform services or hardware sensors. \tableofcontents @@ -181,24 +44,17 @@ 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 orientation. - -There are also some \l{Sensors Backend Topics}{topics} specific to backend -implementors. +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 -\sa {Sensors Backend Topics} - -*/ +\section1 Backend Topics -/*! -\group sensors_backend_topics -\title Sensors Backend Topics \generatelist related + */ /*! diff --git a/doc/src/qtsensors-cpp.qdoc b/doc/src/qtsensors-cpp.qdoc new file mode 100644 index 00000000..83ab8361 --- /dev/null +++ b/doc/src/qtsensors-cpp.qdoc @@ -0,0 +1,150 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** 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. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page qtsensors-cpp.html +\title QtSensors C++ API +\brief Information about the QtSensors C++ API + +\tableofcontents + +\section1 Sensor Types + +On a device there can be many types of sensors. Not all of the types that the QtSensors API +supports may be available. There may also be types available that are not defined in the +QtSensors API. You can find the sensor types available on a device 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, QtSensors shall use 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 sensor is typically: + +\list +\o Create an instance of QSensor or one of its sub-classes on the stack or heap. +\o Setup as required by the application. +\o Start receiving values. +\o Sensor data is used by the application. +\o Stop receiving values. +\endlist + +Here is an example of creating a sensor on the heap and on the stack. + +\snippet snippets/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 +\o The sensor type. +\o The property name or index. +\o 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 snippets/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 QtSensors 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{QtSensors Backend}. + +\section1 Main Classes + +The primary classes that make up the QtSensors 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 QtSensors 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/doc/src/qtsensors.qdoc b/doc/src/qtsensors.qdoc new file mode 100644 index 00000000..2e5ea211 --- /dev/null +++ b/doc/src/qtsensors.qdoc @@ -0,0 +1,89 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** 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. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page qtsensors.html + \title QtSensors + \brief The QtSensors API provides access to sensors via QML and C++ interfaces. + \ingroup technology-apis + + The QtSensors API provides access to sensors via QML and C++ interfaces. + + \section1 Information for Application Writers + + Applications can access QtSensors using QML or C++. + + \table + \row + \o \l {QtSensors 5.x}{QML API} + \o Information about the QtSensors QML API + \row + \o \l {QtSensors C++ API}{C++ API} + \o Information about the QtSensors C++ API + \row + \o \l {QtSensors Examples}{Examples} + \o Examples demonstrating use of the QtSensors APIs + \endtable + + \section1 Information for Backend Implementors + + \table + \row + \o \l {QtSensors Backend}{Backend} + \o Information about the QtSensors back end + \row + \o \l {Grue Sensor Example} + \o The Grue Sensor Example demonstrates creation of a sensor backend + \endtable + + \section1 Compatibility with QtMobility Sensors API + + QtSensors 5.0 (the initial release) is expected to be source compatible with + Mobility Sensors 1.2. + + Applications using the C++ API may need a few minor changes + (such as removing QTM_* macros) but should otherwise work the same. The .pro file + needs to be updated too. Instead of using: + \code + CONFIG += mobility + MOBILITY += sensors + \endcode + Applications should now use: + \code + QT += sensors + \endcode + + Applications using the QML API should not need any changes because QtSensors + supplies a legacy import. + + \table + \row + \o \l {QtMobility.sensors 1.x}{Legacy QML API} + \o Information about the legacy QtMobility.sensors QML API + \endtable +*/ + |