Sensors "porting" guide.

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

1 files changed, 121 insertions, 0 deletions

diff --git a/doc/src/porting.qdoc b/doc/src/porting.qdoc
new file mode 100644
index 00000000..3d3b84a1
--- /dev/null
+++ b/doc/src/porting.qdoc
@@ -0,0 +1,121 @@
+/****************************************************************************
+**
+** 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-porting.html
+    \title Porting Applications from QtMobility Sensors to QtSensors
+
+    \tableofcontents
+
+    \section1 Overview
+
+    The initial release of QtSensors (5.0) is generally expected to be source
+    compatible with QtMobility Sensors 1.2. This document attempts to explain
+    where things must be changed in order to port applications to QtSensors.
+
+    \section1 QML
+
+    Compatibility for QML applications is provided by shipping the legacy \c QtMobility.sensors
+    QML import. QML applications should not require any changes to continue operating.
+
+    Applications using the legacy QML import may not be able to trivially port over
+    to the new QML import because the new QML import does not provide elements for
+    every sensor like the legacy QML import does.
+
+    \table
+        \row
+            \o \l {QtSensors 5.x}{QML API}
+            \o Information about the QtSensors QML API
+        \row
+            \o \l {QtMobility.sensors 1.x}{Legacy QML API}
+            \o Information about the legacy QtMobility.sensors QML API
+    \endtable
+
+    \section1 C++
+
+    \section2 Includes
+
+    QtMobility Sensors installed headers into a \c QtSensors directory. This is
+    also the directory that QtSensors uses. It is therefore expected that includes
+    that worked with QtMobility Sensors should continue to work.
+
+    For example:
+    \code
+    #include <QAccelerometer>
+    #include <qaccelerometer.h>
+    #include <QtSensors/QAccelerometer>
+    #include <QtSensors/qaccelerometer.h>
+    \endcode
+
+    \section2 Macros and Namespace
+
+    QtMobility Sensors was built in a \c QtMobility namespace. This was enabled by
+    the use of various macros. QtSensors does not normally build into a namespace
+    and the macros from QtMobility no longer exist.
+
+    \list
+    \o QTM_BEGIN_NAMESPACE
+    \o QTM_END_NAMESPACE
+    \o QTM_USE_NAMESPACE
+    \o QTM_PREPEND_NAMESPACE(x)
+    \endlist
+
+    Note that Qt can be configured to build into a namespace. If Qt is built in this
+    way then QtSensors is also built into the nominated namespace. However, as this
+    is optional, the macros for this are typically defined to do nothing.
+
+    \list
+    \o QT_BEGIN_NAMESPACE
+    \o QT_END_NAMESPACE
+    \o QT_USE_NAMESPACE
+    \o QT_PREPEND_NAMESPACE(x)
+    \endlist
+
+    \section2 qtimestamp
+
+    qtimestamp was previously defined as an opaque type equivalent to a quint64. It existed
+    as a class due to an implementation detail.
+
+    In QtSensors, the API uses quint64 instead of qtimestamp. qtimestamp still exists as a
+    typedef so that applications that refer to qtimestamp can be compiled.
+
+    \section1 Project Files
+
+    QtMobility Sensors applications used this in their project files to enable the Sensors API.
+
+    \code
+    CONFIG += mobility
+    MOBILITY += sensors
+    \endcode
+
+    Applications should remove these lines and instead use this to enable the QtSensors API.
+
+    \code
+    QT += sensors
+    \endcode
+*/
+