Update the front page.

Link to topics in a more controlled manner.

Change-Id: I6e3ec3d6c5920be66b628d954b470685764fdd33
Reviewed-on: http://codereview.qt-project.org/6024
Reviewed-by: Qt Sanity Bot <qt_sanity_bot@ovi.com>
Reviewed-by: Lincoln Ramsay <lincoln.ramsay@nokia.com>

1 files changed, 218 insertions, 0 deletions

diff --git a/doc/src/qtsensors-backend.qdoc b/doc/src/qtsensors-backend.qdoc
new file mode 100644
index 00000000..814cb5a6
--- /dev/null
+++ b/doc/src/qtsensors-backend.qdoc
@@ -0,0 +1,218 @@
+/****************************************************************************
+**
+** 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 sensors_backend_topics
+\title QtSensors Backend
+\brief Information about the QtSensors back end
+
+The QtSensors backend connects the QtSensors 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 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 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 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.
+
+*/
+