diff options
Diffstat (limited to 'doc/src/sensors.qdoc')
| -rw-r--r-- | doc/src/sensors.qdoc | 186 |
1 files changed, 11 insertions, 175 deletions
diff --git a/doc/src/sensors.qdoc b/doc/src/sensors.qdoc index 1b2c61a5..83ef7048 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, @@ -447,52 +329,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 \ingroup sensors_backend_topics |