From 7553fe500a0059ca2975e291b9acde6e372c002d Mon Sep 17 00:00:00 2001 From: Lincoln Ramsay Date: Tue, 27 Sep 2011 16:34:20 +1000 Subject: Getting some structure into the sensors docs. QtSensors is a landing page (from the Modules index). There's a QtSensors Examples page that has all the examples on it. The QtSensors page links off to the C++ and QML API pages. More to do but this is a good start. Change-Id: I2b795a759490e712137024101a630193d2d26033 Reviewed-on: http://codereview.qt-project.org/5589 Reviewed-by: Qt Sanity Bot Reviewed-by: Lincoln Ramsay --- doc/src/examples/sensors.qdoc | 37 +++ doc/src/imports/qml-qtsensors5.qdoc | 109 ------- doc/src/imports/qml-sensors.qdoc | 99 ------ doc/src/imports/qtmobilitysensors1.qdoc | 73 +++++ doc/src/imports/qtsensors5.qdoc | 85 ++++++ doc/src/mobility_sensors.qdoc | 524 -------------------------------- doc/src/sensors.qdoc | 186 +----------- 7 files changed, 206 insertions(+), 907 deletions(-) delete mode 100644 doc/src/imports/qml-qtsensors5.qdoc delete mode 100644 doc/src/imports/qml-sensors.qdoc create mode 100644 doc/src/imports/qtmobilitysensors1.qdoc create mode 100644 doc/src/imports/qtsensors5.qdoc delete mode 100644 doc/src/mobility_sensors.qdoc (limited to 'doc') diff --git a/doc/src/examples/sensors.qdoc b/doc/src/examples/sensors.qdoc index 3f5a9a2..3c04525 100644 --- a/doc/src/examples/sensors.qdoc +++ b/doc/src/examples/sensors.qdoc @@ -25,9 +25,23 @@ ** ****************************************************************************/ +/*! + \group qtsensors-examples + \title QtSensors Examples + \brief Examples for the QtSensors module + \ingroup all-examples + \ingroup qtsensors + + These are the QtSensors examples. + + \generatelist related +*/ + /*! \example sensors/grueplugin \title Grue Plugin + \brief The Grue Plugin demonstrates creation of a new sensor backend. + \ingroup qtsensors-examples The Grue plugin example demonstrates the creation of a new sensor type, a sensor backend and plugin for the sensors library. Related to this example @@ -119,6 +133,8 @@ /*! \example sensors/grueapp \title Grue Application + \brief The Grue Application demonstrates use of a new sensor type. + \ingroup qtsensors-examples The Grue application example demonstrates the use of the Grue sensor which was defined and implemented by the \l{sensors/grueplugin}{Grue Plugin} example. @@ -133,6 +149,7 @@ /*! \example sensors/cubehouse \title Cube House + \ingroup qtsensors-examples \image cubehouse.png @@ -157,6 +174,7 @@ /*! \example sensors/sensor_explorer \title Sensor Explorer + \ingroup qtsensors-examples \image sensor_explorer.png @@ -164,3 +182,22 @@ It was designed as a debugging aid. */ +/*! + \example sensors/qmlqtsensors5 + \title QtSensors 5 QML API example + \ingroup qtsensors-examples + + The QtSensors 5 QML API example demonstrates the QML elements in the QtSensors 5 import. + + \sa QtSensors +*/ + +/*! + \example sensors/maze + \title Maze + \brief The Maze example demonstrates the TiltSensor QML element + \ingroup qtsensors-examples + + The Maze example demonstrates the use of the TiltSensor QML element. +*/ + diff --git a/doc/src/imports/qml-qtsensors5.qdoc b/doc/src/imports/qml-qtsensors5.qdoc deleted file mode 100644 index 39407a5..0000000 --- a/doc/src/imports/qml-qtsensors5.qdoc +++ /dev/null @@ -1,109 +0,0 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ - -/*! - \qmlmodule QtSensors 5 - \title Sensors QML Plugin for Qt 5 - \brief A QML plugin for the Qt 5 Project Sensors API. -*/ - -/*! - \page qmlqtsensors5.html - \title Sensors 5 QML Plugin example - \example qmlqtsensors5 -*/ - -/*! - \page maze.html - \title Sensors 5 QML TiltSensor example - \example maze -*/ - -/*! - \page qml-sensors5.html - \title Sensors 5 QML Plugin - - \brief A QML plugin for the Qt Project Sensors 5 API. - - \section1 Overview - - The identifying string for this component is \i {"QtSensors"}. - Use this in the QML \i {import} statement. - - The QML Sensors 5 Plugin provides an easy to use interface to the Sensors API. - It enables us to receive sensor events and to read current values from - sensors. - - The plugin contains many sensor types and properties to read values - from them. As an example consider the tilt sensor. The qmlsensors2 - simply displays text on-screen to show the current tilt. - - The QML code that reads the value is quite simple. Here we see a QML component - tilt declared which is an \l TiltSensor element. First - the sensor is started by setting the running property - to true. The element receives a signal when the x and y rotation changes and it - can be picked up by the onXRotationChanged and onYRotationChanged slot. Now the - xRotation and yRotation property of this element can be - used to extract the current tilt so that it can be used for further calulations. - - \qml - TiltSensor { - id: tilt - radian: false - measureFrom: TiltSensor.FaceUp - running: false - } - \endqml - - \qml - Text { - x:5 - y:160 - text: "X Rotation: " + tilt.xRotation - } - \endqml - - \qml - Text { - x:5 - y:180 - text: "Y Rotation: " + tilt.yRotation - } - - \endqml - - \section1 QML Elements - \annotatedlist qml-QtSensors5 - - \section1 QML QtSensors Example - The \l {qmlqtsensors5}{qmlqtsensors5} example shows you how to use all those diferent QML elements. - - \section1 Maze QML TiltSensor Example - The \l {maze}{maze} example shows you how to use the TiltSeonsor QML element. -*/ - - diff --git a/doc/src/imports/qml-sensors.qdoc b/doc/src/imports/qml-sensors.qdoc deleted file mode 100644 index e547daa..0000000 --- a/doc/src/imports/qml-sensors.qdoc +++ /dev/null @@ -1,99 +0,0 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ - -/*! - \group qml-sensors - \title QML Sensors API Plugin - QML Support for the QtMobility Project Sensors API. -*/ - -/*! - \page qml-sensors.html - - \title Sensors QML Plugin - - \brief A QML plugin for the QtMobility Project Sensors API. - - \section1 Overview - - The QML Sensors Plugin provides an easy to use interface to the Sensors API. - It enables us to receive sensor events and to read current values from - sensors. - - The plugin contains many sensor types and access functions to read values - from them. As an example consider the orientation sensor. The orientation - example simply displays text on-screen to show the current orientation. - - The QML code that reads the value is quite simple. Here we see a QML component - \i orientation declared which is an \l OrientationSensor element. First - the sensor is started by setting the \l {Sensor::active}{active} property - to \i true. The element receives a signal when the reading changes and it - is picked up by the \i onReadingChanged slot. Now the - \l {OrientationSensor::reading}{reading} property of this element can be - used to extract the current orientation so that it can be compared against - the defined values of various orientations in the \l OrientationReading - element. - - \qml - OrientationSensor { - id: orientation - active: true - - onReadingChanged: { - - if (reading.orientation == OrientationReading.FaceUp) - content.state = "FaceUp"; - - // ... more tests for different orientations ... - } - } - - \endqml - - Other sensors can be treated in a similar manner. For example, the \l Compass - sensor could have almost identical coding - - \qml - Compass { - id: compass - active: true - - onReadingChanged: { - compassHeading.text = reading.azimuth; - - // ... - } - } - \endqml - - \section1 QML Elements - \annotatedlist qml-sensors_type - \annotatedlist qml-sensors_reading - -*/ - - diff --git a/doc/src/imports/qtmobilitysensors1.qdoc b/doc/src/imports/qtmobilitysensors1.qdoc new file mode 100644 index 0000000..341eb7e --- /dev/null +++ b/doc/src/imports/qtmobilitysensors1.qdoc @@ -0,0 +1,73 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \qmlmodule QtMobility.sensors 1 + \title QtMobility.sensors 1.x + \brief Legacy QML import for QtSensors + \ingroup qtsensors + + \section1 Overview + + The identifying string for this component is \e {"QtMobility.sensors"}. + Use this in the QML \e {import} statement. + + The Sensors QML Plugin registers the C++ Sensors classes directly to the QML environment. + This causes some limitations due to the use of types that do not work in the QML environment. + See \l{Sensors QML Limitations}{below} for a list of the known limitations. + + See \l QtSensors for more information about the Sensors API. + + \section1 Sensors QML Limitations + + The following limitations affect the Sensors QML bindings for Qt Mobility 1.1 and 1.2. + + \list 1 + \o The QSensor::sensorid property cannot be set because QML does not support QByteArray. + This means that it is not possible to specify a particular sensor when two or more have + been registered with the same type. + \o The QSensor::availableDataRates property cannot be used because QML does not support \l qrangelist. + \o The QSensor::outputRanges property cannot be used because QML does not support \l qoutputrangelist. + \o The QLightSensor::fieldOfView property cannot be used because QML cannot access dynamic properties. + \o The QMagnetometer::returnGeoValues property cannot be used because QML cannot access dynamic properties. + \o The QRotationSensor::hasZ property cannot be used because QML cannot access dynamic properties. + \o The QTapSensor::returnDoubleTapEvents property cannot be used because QML cannot access dynamic properties. + \endlist + + \section1 QML Sensor Elements + + These elements represent specific types of sensors. + + \annotatedlist qml-sensors_type + + \section1 QML Reading Elements + + The data from a sensor comes through a reading class. + + \annotatedlist qml-sensors_reading +*/ + diff --git a/doc/src/imports/qtsensors5.qdoc b/doc/src/imports/qtsensors5.qdoc new file mode 100644 index 0000000..ed28985 --- /dev/null +++ b/doc/src/imports/qtsensors5.qdoc @@ -0,0 +1,85 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \qmlmodule QtSensors 5 + \title QtSensors 5.x + \brief The QML import for QtSensors + \ingroup qtsensors + + \section1 Overview + + The identifying string for this component is \e QtSensors. + Use this in the QML \e import statement. + + The QML Sensors 5 Plugin provides an easy to use interface to the Sensors API. + It enables us to receive sensor events and to read current values from + sensors. + + The plugin contains many sensor types and properties to read values + from them. As an example consider the tilt sensor. The qmlsensors2 + simply displays text on-screen to show the current tilt. + + The QML code that reads the value is quite simple. Here we see a QML component + tilt declared which is an \l TiltSensor element. First + the sensor is started by setting the running property + to true. The element receives a signal when the x and y rotation changes and it + can be picked up by the onXRotationChanged and onYRotationChanged slot. Now the + xRotation and yRotation property of this element can be + used to extract the current tilt so that it can be used for further calulations. + + \qml + TiltSensor { + id: tilt + radian: false + measureFrom: TiltSensor.FaceUp + running: false + } + \endqml + + \qml + Text { + x:5 + y:160 + text: "X Rotation: " + tilt.xRotation + } + \endqml + + \qml + Text { + x:5 + y:180 + text: "Y Rotation: " + tilt.yRotation + } + + \endqml + + \section1 QML Elements + +*/ + + diff --git a/doc/src/mobility_sensors.qdoc b/doc/src/mobility_sensors.qdoc deleted file mode 100644 index 408922d..0000000 --- a/doc/src/mobility_sensors.qdoc +++ /dev/null @@ -1,524 +0,0 @@ -/**************************************************************************** -** -** 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 mobility-sensors-api.html -\title QtMobility Sensors -\brief The Sensors API provides access to sensors. -\ingroup mobility -\ingroup technology-apis - - -The Sensors API is primarily concerned with low-level, real-time sensors such as -the accelerometer although there are higher-level, event-driven sensors represented too. - -\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 ../doc/src/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 ../doc/src/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 Platform notes - -\section2 S60 3rd Edition - -Note that support for sensors in S60 3.1 device is extremely limited due to the native API. -Only the accelerometer is supported and only a few devices. - -Some devices running S60 3.2 support a newer native API and therefore support more sensors. - -More information about these platforms can be found \l{http://wiki.forum.nokia.com/index.php/Nokia_Sensor_APIs}{here}. - -Note that timestamps on this platform come from the system clock. -Applications need to handle shifts in time caused by the user manually setting the clock or -from the automatic time synchronization feature setting the clock. - -\section2 Symbian - -Most Symbian devices have their sensor data read via the Sensor Framework API. Some limitations -appear in the Sensors API as a result. - -Only specific data rates can be selected. Setting an invalid data rate has no effect so applications -that need to influence the used data rate should connect to the sensor, check the available data rates -and select one as appropriate. - -Readings are delivered to the application via a queue. If the application blocks the event loop or otherwise -interferes with the ability of the system to deliver readings (eg. by using up too much CPU time), they can -get blocked in this queue. Since delayed readings are not useful, the system will drop readings as needed -so that the application is always dealing with the most recent reading available. The application can tweak -the policy by setting properties on the sensor. - -The default policy is to accept up to 100 readings from the system at once and to discard all but the last one. - -\code -QAccelerometer sensor; -sensor.setProperty("maximumReadingCount", 100); -sensor.setProperty("processAllReadings", false); -\endcode - -Applications that desire the original behaviour can set the maximumReadingCount to 1. Note that this does not -guarantee that readings will not be dropped by the system. If the queue fills up, readings will be dropped. - -\code -QAccelerometer sensor; -sensor.setProperty("maximumReadingCount", 1); -\endcode - -Larger maximumReadingCount values reduce the need for the lower-priority sensor daemon to get CPU timeslices. -If the application is using lots of CPU but is still able to process readings quickly, it can request that -all the fetched readings are processed. - -\code -QAccelerometer sensor; -sensor.setProperty("maximumReadingCount", 10); -sensor.setProperty("processAllReadings", true); -\endcode - -More information about the native API can be found \l{http://wiki.forum.nokia.com/index.php/Nokia_Sensor_APIs}{here}. - -Note that timestamps on this platform come from the system clock. -Applications need to handle shifts in time caused by the user manually setting the clock or -from the automatic time synchronization feature setting the clock. - -The ambient light sensor can only detect changes. Unlike all other sensors, it cannot report the "current value" -so it is not possible to determine the current ambient light level. - -\section2 Maemo 5 - -The N900 represents a unique device for the Sensors API. Unlike the Symbian and MeeGo platforms, sensor data is -retrieved directly from the kernel and this has implications on the API. - -Axes are rotated when compared to Symbian or MeeGo devices. While Symbian and MeeGo devices orient their -hardware sensors towards a portrait orientation, the N900 does not do this. Instead, it orients the hardware sensors -towards its default landscape orientation. This has portability implications for applications that want to force the -use of a particular screen orientation and use sensors. The following code shows how accelerometer values can be -interpreted to ensure consistent results on the N900 as well as Symbian and MeeGo devices. - -\code -#ifdef Q_WS_MAEMO_5 - qreal x = reading->y(); - qreal y = -reading->x(); -#else - qreal x = reading->x(); - qreal y = reading->y(); -#endif - qreal z = reading->z(); -\endcode - -Alternatively, applications can set the environment variable \c N900_PORTRAIT_SENSORS to 1. This must be done -before any Sensors API calls are made so the beginning of the main function is a good place to do it. - -\code -int main(int argc, char **argv) -{ - qputenv("N900_PORTRAIT_SENSORS", "1"); - ... -\endcode - -Despite hardware that allows for multiple data rates and output ranges, the Sensors API does not allow access to -these due to permissions issues. - -Readings are polled using a timer. If the application blocks the event loop or otherwise interferes with the -ability of the timer to fire, readings will be missed. There are no queues so applications must ensure that -they process the readings promptly (possibly saving them into a buffer for later processing if required). - -\section2 MeeGo - -The data rates offered by MeeGo are not tied to how fast the hardware runs. - -The default data rate for a sensor is likely to be low when compared to Symbian or Maemo 5. Applications should -request a suitable data rate, taking care to avoid selecting invalid rates on other devices. - -Sensors may be suspended by the system in order to save power. Applications can avoid this by setting a property -on the sensor object. - -\code -QAccelerometer *accelerometer = new QAccelerometer(this); -accelerometer->setProperty("alwaysOn", true); -accelerometer->start(); -\endcode - -Unlike Symbian and N900, MeeGo does not currently provide initial readings. Thus, certain sensors must detect -a change in value before a value can be reported. Examples include the orientation sensor and ambient light -sensor. - -\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. - -The Sensors Backend connects the 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 QtSensors 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 orientation. - -There are also some \l{Sensors Backend Topics}{topics} specific to backend -implementors. - -\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} - -*/ - -/*! -\group sensors_backend_topics -\title Sensors 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 ../doc/src/snippets/sensors/plugin.cpp Plugin - -If you would like to build a backend into a library or application you can use the -REGISTER_STATIC_PLUGIN() macro although it may not work in all situations as it -uses static initialization. - -*/ - -/*! -\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 is read using QSettings so it has the standard formatting -of a QSettings .conf 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. - -*/ - -/*! -\page qml-sensors.html -\title Sensors QML Plugin -\brief A QML plugin for the QtMobility Project Sensors API. - -\section1 Overview - -The identifying string for this component is \i {"QtMobility.sensors"}. -Use this in the QML \i {import} statement. - -The Sensors QML Plugin registers the C++ Sensors classes directly to the QML environment. -This causes some limitations due to the use of types that do not work in the QML environment. -See \l{Sensors QML Limitations}{below} for a list of the known limitations. - -See \l Sensors for more information about the Sensors API. - -\section1 Sensors QML Limitations - -The following limitations affect the Sensors QML bindings for Qt Mobility 1.1 and 1.2. - -\list 1 -\o The QSensor::sensorid property cannot be set because QML does not support QByteArray. - This means that it is not possible to specify a particular sensor when two or more have - been registered with the same type. -\o The QSensor::availableDataRates property cannot be used because QML does not support \l qrangelist. -\o The QSensor::outputRanges property cannot be used because QML does not support \l qoutputrangelist. -\o The QLightSensor::fieldOfView property cannot be used because QML cannot access dynamic properties. -\o The QMagnetometer::returnGeoValues property cannot be used because QML cannot access dynamic properties. -\o The QRotationSensor::hasZ property cannot be used because QML cannot access dynamic properties. -\o The QTapSensor::returnDoubleTapEvents property cannot be used because QML cannot access dynamic properties. -\endlist - -\section1 QML Sensor Elements - -These elements represent specific types of sensors. - -\annotatedlist qml-sensors_type - -\section1 QML Reading Elements - -The data from a sensor comes through a reading class. - -\annotatedlist qml-sensors_reading - -*/ - -/*! -\page meego-integration-notes.html -\title MeeGo Integration Notes -\ingroup sensors_backend_topics - -\section1 MeeGo Integration Notes - -The implementation of the API builds on top of the MeeGo Sensor Framework -that provides all the sensors specified in 1.2 API version. - -\section2 Available sensors - -If HW sensor is missing, the configuration file "Sensors.conf" -must be updated and sensor removed. The file -has the following format: - -\code -[Default] -QAccelerometer=meego.accelerometer -QAmbientLightSensor=meego.als -\endcode - -It lists sensor types and type's default implementation by giving the sensor id. -If the type is omitted then the backend does not support it in this device; this -gives a way of controlling and differentiating the supported sensor set. - -*/ - diff --git a/doc/src/sensors.qdoc b/doc/src/sensors.qdoc index 1b2c61a..83ef704 100644 --- a/doc/src/sensors.qdoc +++ b/doc/src/sensors.qdoc @@ -26,13 +26,19 @@ ****************************************************************************/ /*! -\page qtsensors.html -\title QtSensors -\brief The Sensors API provides access to sensors. + \group qtsensors + \title QtSensors + The QtSensors API provides access to sensors via QML and C++ interfaces. -The Sensors API is primarily concerned with low-level, real-time sensors such as -the accelerometer although there are higher-level, event-driven sensors represented too. + \generatelist related +*/ + +/*! +\page qtsensors-cpp.html +\title QtSensors C++ API +\brief Information about the QtSensors C++ API +\ingroup qtsensors \tableofcontents @@ -108,130 +114,6 @@ This code does not require any compile-time links to \l QAccelerometer or You can discover all of this information at runtime too. The sensor_explorer example shows you information about available sensors. -\section1 Platform notes - -\section2 S60 3rd Edition - -Note that support for sensors in S60 3.1 device is extremely limited due to the native API. -Only the accelerometer is supported and only a few devices. - -Some devices running S60 3.2 support a newer native API and therefore support more sensors. - -More information about these platforms can be found \l{http://wiki.forum.nokia.com/index.php/Nokia_Sensor_APIs}{here}. - -Note that timestamps on this platform come from the system clock. -Applications need to handle shifts in time caused by the user manually setting the clock or -from the automatic time synchronization feature setting the clock. - -\section2 Symbian - -Most Symbian devices have their sensor data read via the Sensor Framework API. Some limitations -appear in the Sensors API as a result. - -Only specific data rates can be selected. Setting an invalid data rate has no effect so applications -that need to influence the used data rate should connect to the sensor, check the available data rates -and select one as appropriate. - -Readings are delivered to the application via a queue. If the application blocks the event loop or otherwise -interferes with the ability of the system to deliver readings (eg. by using up too much CPU time), they can -get blocked in this queue. Since delayed readings are not useful, the system will drop readings as needed -so that the application is always dealing with the most recent reading available. The application can tweak -the policy by setting properties on the sensor. - -The default policy is to accept up to 100 readings from the system at once and to discard all but the last one. - -\code -QAccelerometer sensor; -sensor.setProperty("maximumReadingCount", 100); -sensor.setProperty("processAllReadings", false); -\endcode - -Applications that desire the original behaviour can set the maximumReadingCount to 1. Note that this does not -guarantee that readings will not be dropped by the system. If the queue fills up, readings will be dropped. - -\code -QAccelerometer sensor; -sensor.setProperty("maximumReadingCount", 1); -\endcode - -Larger maximumReadingCount values reduce the need for the lower-priority sensor daemon to get CPU timeslices. -If the application is using lots of CPU but is still able to process readings quickly, it can request that -all the fetched readings are processed. - -\code -QAccelerometer sensor; -sensor.setProperty("maximumReadingCount", 10); -sensor.setProperty("processAllReadings", true); -\endcode - -More information about the native API can be found \l{http://wiki.forum.nokia.com/index.php/Nokia_Sensor_APIs}{here}. - -Note that timestamps on this platform come from the system clock. -Applications need to handle shifts in time caused by the user manually setting the clock or -from the automatic time synchronization feature setting the clock. - -The ambient light sensor can only detect changes. Unlike all other sensors, it cannot report the "current value" -so it is not possible to determine the current ambient light level. - -\section2 Maemo 5 - -The N900 represents a unique device for the Sensors API. Unlike the Symbian and MeeGo platforms, sensor data is -retrieved directly from the kernel and this has implications on the API. - -Axes are rotated when compared to Symbian or MeeGo devices. While Symbian and MeeGo devices orient their -hardware sensors towards a portrait orientation, the N900 does not do this. Instead, it orients the hardware sensors -towards its default landscape orientation. This has portability implications for applications that want to force the -use of a particular screen orientation and use sensors. The following code shows how accelerometer values can be -interpreted to ensure consistent results on the N900 as well as Symbian and MeeGo devices. - -\code -#ifdef Q_WS_MAEMO_5 - qreal x = reading->y(); - qreal y = -reading->x(); -#else - qreal x = reading->x(); - qreal y = reading->y(); -#endif - qreal z = reading->z(); -\endcode - -Alternatively, applications can set the environment variable \c N900_PORTRAIT_SENSORS to 1. This must be done -before any Sensors API calls are made so the beginning of the main function is a good place to do it. - -\code -int main(int argc, char **argv) -{ - qputenv("N900_PORTRAIT_SENSORS", "1"); - ... -\endcode - -Despite hardware that allows for multiple data rates and output ranges, the Sensors API does not allow access to -these due to permissions issues. - -Readings are polled using a timer. If the application blocks the event loop or otherwise interferes with the -ability of the timer to fire, readings will be missed. There are no queues so applications must ensure that -they process the readings promptly (possibly saving them into a buffer for later processing if required). - -\section2 MeeGo - -The data rates offered by MeeGo are not tied to how fast the hardware runs. - -The default data rate for a sensor is likely to be low when compared to Symbian or Maemo 5. Applications should -request a suitable data rate, taking care to avoid selecting invalid rates on other devices. - -Sensors may be suspended by the system in order to save power. Applications can avoid this by setting a property -on the sensor object. - -\code -QAccelerometer *accelerometer = new QAccelerometer(this); -accelerometer->setProperty("alwaysOn", true); -accelerometer->start(); -\endcode - -Unlike Symbian and N900, MeeGo does not currently provide initial readings. Thus, certain sensors must detect -a change in value before a value can be reported. Examples include the orientation sensor and ambient light -sensor. - \section1 Front end, back end The Sensors API has a front end, for application developers to use and a back end, @@ -446,52 +328,6 @@ handle the situation gracefully. */ -/*! -\page qml-sensors.html -\title Sensors QML Plugin -\brief A QML plugin for the QtMobility Project Sensors API. - -\section1 Overview - -The identifying string for this component is \e {"QtMobility.sensors"}. -Use this in the QML \e {import} statement. - -The Sensors QML Plugin registers the C++ Sensors classes directly to the QML environment. -This causes some limitations due to the use of types that do not work in the QML environment. -See \l{Sensors QML Limitations}{below} for a list of the known limitations. - -See \l Sensors for more information about the Sensors API. - -\section1 Sensors QML Limitations - -The following limitations affect the Sensors QML bindings for Qt Mobility 1.1 and 1.2. - -\list 1 -\o The QSensor::sensorid property cannot be set because QML does not support QByteArray. - This means that it is not possible to specify a particular sensor when two or more have - been registered with the same type. -\o The QSensor::availableDataRates property cannot be used because QML does not support \l qrangelist. -\o The QSensor::outputRanges property cannot be used because QML does not support \l qoutputrangelist. -\o The QLightSensor::fieldOfView property cannot be used because QML cannot access dynamic properties. -\o The QMagnetometer::returnGeoValues property cannot be used because QML cannot access dynamic properties. -\o The QRotationSensor::hasZ property cannot be used because QML cannot access dynamic properties. -\o The QTapSensor::returnDoubleTapEvents property cannot be used because QML cannot access dynamic properties. -\endlist - -\section1 QML Sensor Elements - -These elements represent specific types of sensors. - -\annotatedlist qml-sensors_type - -\section1 QML Reading Elements - -The data from a sensor comes through a reading class. - -\annotatedlist qml-sensors_reading - -*/ - /*! \page meego-integration-notes.html \title MeeGo Integration Notes -- cgit v1.2.1