diff options
Diffstat (limited to 'doc/src/qtsensors-backend.qdoc')
| -rw-r--r-- | doc/src/qtsensors-backend.qdoc | 184 |
1 files changed, 0 insertions, 184 deletions
diff --git a/doc/src/qtsensors-backend.qdoc b/doc/src/qtsensors-backend.qdoc deleted file mode 100644 index d3c6e755..00000000 --- a/doc/src/qtsensors-backend.qdoc +++ /dev/null @@ -1,184 +0,0 @@ -/**************************************************************************** -** -** 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 snippets/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. - -*/ |