From a53bcc52d0092b523781e8e731de3e476dc4d4b0 Mon Sep 17 00:00:00 2001 From: Lincoln Ramsay Date: Thu, 6 Oct 2011 16:54:05 +1000 Subject: Sensors "porting" guide. Change-Id: Ie471fcb632d3cfc581076c36b1c9bfc78c2b4d22 Reviewed-on: http://codereview.qt-project.org/6211 Reviewed-by: Qt Sanity Bot Reviewed-by: Lincoln Ramsay --- doc/src/porting.qdoc | 121 +++++++++++++++++++++++++++++++++++++++++++++++++ doc/src/qtsensors.qdoc | 22 ++------- 2 files changed, 126 insertions(+), 17 deletions(-) create mode 100644 doc/src/porting.qdoc (limited to 'doc') diff --git a/doc/src/porting.qdoc b/doc/src/porting.qdoc new file mode 100644 index 0000000..3d3b84a --- /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 + #include + #include + #include + \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 +*/ + diff --git a/doc/src/qtsensors.qdoc b/doc/src/qtsensors.qdoc index 2e5ea21..13291db 100644 --- a/doc/src/qtsensors.qdoc +++ b/doc/src/qtsensors.qdoc @@ -62,25 +62,13 @@ \section1 Compatibility with QtMobility Sensors API - QtSensors 5.0 (the initial release) is expected to be source compatible with - Mobility Sensors 1.2. - - Applications using the C++ API may need a few minor changes - (such as removing QTM_* macros) but should otherwise work the same. The .pro file - needs to be updated too. Instead of using: - \code - CONFIG += mobility - MOBILITY += sensors - \endcode - Applications should now use: - \code - QT += sensors - \endcode - - Applications using the QML API should not need any changes because QtSensors - supplies a legacy import. + QtSensors 5.0 (the initial release) is generally expected to be source compatible + with QtMobility Sensors 1.2. \table + \row + \o \l {Porting Applications from QtMobility Sensors to QtSensors}{Porting Guide} + \o Information about the steps needed to port applications to the QtSensors API. \row \o \l {QtMobility.sensors 1.x}{Legacy QML API} \o Information about the legacy QtMobility.sensors QML API -- cgit v1.2.1