add QSensorGestures API. Long live QSensorGestures!

Change-Id: Iada4e8888aad8b7b2180cc0bfb8576a766f75b24
Sanity-Review: Qt Sanity Bot <qt_sanity_bot@ovi.com>
Reviewed-by: Lincoln Ramsay <lincoln.ramsay@nokia.com>

9 files changed, 455 insertions, 0 deletions

diff --git a/doc/src/qtsensorgestures-cpp.qdoc b/doc/src/qtsensorgestures-cpp.qdoc
new file mode 100644
index 00000000..ba7d1f3a
--- /dev/null
+++ b/doc/src/qtsensorgestures-cpp.qdoc
@@ -0,0 +1,63 @@
+/****************************************************************************
+**
+** 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 qtsensorgestures-cpp.html
+\title QtSensorGestures C++ API
+\brief Information about the QtSensorGestures C++ API
+
+\tableofcontents
+
+\section1
+
+
+\section1 Using QtSensorGestures
+
+With QtSensorGestures, you are able to easily utilize device gesturing using
+sensors such as the accelerometer and proximity.
+For example 'shake','spin', 'drop','cover' and 'turnover'.
+
+
+Using QtSensorGestures is easy. There are two main classes you will need to use.
+
+QSensorGestureManager can be used for determining what sensor gestures are available, and
+QSensorGesture for connecting the sensor gesture signals.
+
+\snippet snippets/sensorgestures/creating.cpp Receiving sensor gesture signals
+
+More information about the sensor gesture recognizers can be found in
+\l{QtSensorGestures Plugins}.
+
+\section1 Main Classes
+
+The primary classes that make up the QtSensorGestures API.
+
+\annotatedlist sensorgestures_main
+
+
+*/
+
diff --git a/doc/src/qtsensorgestures-plugins.qdoc b/doc/src/qtsensorgestures-plugins.qdoc
new file mode 100644
index 00000000..e73be5b9
--- /dev/null
+++ b/doc/src/qtsensorgestures-plugins.qdoc
@@ -0,0 +1,59 @@
+/****************************************************************************
+**
+** 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 sensorgesture_plugins_topics
+\title QtSensorGestures Plugins
+\brief Information about the QtSensorGestures recognizer plugins.
+
+The QtSensorGestures recognizer plugins are the way to create your own
+sensor gestures.
+
+\tableofcontents
+
+\section1 Overview
+
+    The steps to creating a sensor gesture plugin are as follows:
+\list
+\o Sub-class from QSensorGesturePluginInterface
+\o Sub-class from QSensorGestureRecognizer and implement gesture recognizer logic using QtSensors.
+\o Create an instance of that recognizer in the derived QSensorGesturePluginInterface class, and call
+ QSensorGestureManager::registerSensorGestureRecognizer(sRec); in your registerRecognizers()
+function. QSensorGestureManager will retain ownership of the recognizer object.
+\endlist
+
+\snippet snippets/sensorgestures/plugin.cpp Plugin
+
+
+\section1 Recognizer Classes
+If you are making sensorgestures available through the QtSensorGestures API, these are the
+sensor gesture classes to use.
+
+\annotatedlist sensorgestures_recognizer
+
+
+*/
diff --git a/doc/src/qtsensors.qdoc b/doc/src/qtsensors.qdoc
index 13291db4..11af5156 100644
--- a/doc/src/qtsensors.qdoc
+++ b/doc/src/qtsensors.qdoc
@@ -73,5 +73,24 @@
             \o \l {QtMobility.sensors 1.x}{Legacy QML API}
             \o Information about the legacy QtMobility.sensors QML API
     \endtable
+
+
+    \section1 Information for QtSensorGestures API
+
+    \table
+        \row
+            \o \l {QtSensorGestures C++ API}{C++ API}
+            \o Information about the QtSensorGestures C++ API
+    \endtable
+
+    \section1 Information for QtSensorGestures Recognizer Plugin Implementors.
+
+    \table
+        \row
+            \o \l {QtSensorGestures Plugins}{Plugins}
+            \o Information about the QtSensorGestures recognizer plugins.
+
+    \endtable
+
 */
 
diff --git a/doc/src/snippets/sensorgestures/creating.cpp b/doc/src/snippets/sensorgestures/creating.cpp
new file mode 100644
index 00000000..37191707
--- /dev/null
+++ b/doc/src/snippets/sensorgestures/creating.cpp
@@ -0,0 +1,73 @@
+/****************************************************************************
+**
+** 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 QtSensors module of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
+**     the names of its contributors may be used to endorse or promote
+**     products derived from this software without specific prior written
+**     permission.
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#include <QObject>
+#include <QString>
+#include <QSensorGestureManager>
+
+class MyObject : public QObject
+{
+    void create();
+public slots:
+    void gestureDetected(const QString &);
+};
+
+void MyObject::create()
+{
+//! [Receiving sensor gesture signals]
+
+// Create a QSensorGestureManager
+    QSensorGestureManager gestureManager;
+
+// Get a list of known recognizers
+    QStringList recognizersList = gestureManager.gestureIds();
+
+// Create a QSensorGeture object for each of those gesture recognizers
+        QSensorGesture *gesture = new QSensorGesture( gestureManager.gestureIds(), this);
+// Connect the known signals up.
+        connect(gesture, SIGNAL(detected(QString)), this, SLOT(gestureDetected(QString)));
+//! [Receiving sensor gesture signals]
+}
+
+void MyObject::gestureDetected(const QString &gesture)
+{
+    Q_UNUSED(gesture);
+}
+
diff --git a/doc/src/snippets/sensorgestures/main.cpp b/doc/src/snippets/sensorgestures/main.cpp
new file mode 100644
index 00000000..1f68b7dc
--- /dev/null
+++ b/doc/src/snippets/sensorgestures/main.cpp
@@ -0,0 +1,45 @@
+/****************************************************************************
+**
+** 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 QtSensors module of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
+**     the names of its contributors may be used to endorse or promote
+**     products derived from this software without specific prior written
+**     permission.
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+int main(int /*argc*/, char ** /*argv*/)
+{
+    return 0;
+}
+
diff --git a/doc/src/snippets/sensorgestures/myplugin.h b/doc/src/snippets/sensorgestures/myplugin.h
new file mode 100644
index 00000000..91020f0b
--- /dev/null
+++ b/doc/src/snippets/sensorgestures/myplugin.h
@@ -0,0 +1,82 @@
+/****************************************************************************
+**
+** 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 QtSensors module of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
+**     the names of its contributors may be used to endorse or promote
+**     products derived from this software without specific prior written
+**     permission.
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#ifndef MYPLUGIN_H
+#define MYPLUGIN_H
+
+#include <QObject>
+#include <qsensorgestureplugininterface.h>
+#include <qsensorgesturerecognizer.h>
+
+class MySensorGestureRecognizer :  public QSensorGestureRecognizer
+{
+    Q_OBJECT
+ public:
+
+    MySensorGestureRecognizer(QObject *parent = 0);
+    ~MySensorGestureRecognizer();
+
+    void create();
+
+    QString id() const;
+    bool start();
+    bool stop();
+    bool isActive();
+
+Q_SIGNALS:
+// all signals will get exported to QSensorGesture
+    void mySignal();
+};
+
+class MySensorGesturePlugin : public  QObject, QSensorGesturePluginInterface
+{
+    Q_OBJECT
+    Q_INTERFACES(QSensorGesturePluginInterface)
+    explicit MySensorGesturePlugin();
+    ~MySensorGesturePlugin();
+
+    QList <QSensorGestureRecognizer *>  createRecognizers();
+    QStringList supportedIds() const;
+    QString name() const { return "MyGestures"; }
+};
+
+//Q_EXPORT_PLUGIN2(MySensorGestureRecognizer, MySensorGesturePlugin)
+
+#endif
diff --git a/doc/src/snippets/sensorgestures/plugin.cpp b/doc/src/snippets/sensorgestures/plugin.cpp
new file mode 100644
index 00000000..cc68cebb
--- /dev/null
+++ b/doc/src/snippets/sensorgestures/plugin.cpp
@@ -0,0 +1,103 @@
+/****************************************************************************
+**
+** 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 QtSensors module of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
+**     the names of its contributors may be used to endorse or promote
+**     products derived from this software without specific prior written
+**     permission.
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#include "myplugin.h"
+
+#include <qsensorgestureplugininterface.h>
+#include <qsensorgesturemanager.h>
+
+//! [Plugin]
+
+MySensorGestureRecognizer::MySensorGestureRecognizer(QObject *parent)
+    : QSensorGestureRecognizer(parent)
+{
+}
+
+MySensorGestureRecognizer::~MySensorGestureRecognizer()
+{
+}
+
+bool MySensorGestureRecognizer::start()
+{
+    Q_EMIT mySignal();
+    return true;
+}
+
+bool MySensorGestureRecognizer::stop()
+{
+    return true;
+}
+
+bool MySensorGestureRecognizer::isActive()
+{
+    return true;
+}
+
+void  MySensorGestureRecognizer::create()
+{
+}
+
+QString MySensorGestureRecognizer::id() const
+{
+    return QString("QtSensors.mygestures");
+}
+
+
+MySensorGesturePlugin::MySensorGesturePlugin(){}
+MySensorGesturePlugin::~MySensorGesturePlugin(){}
+
+QList <QSensorGestureRecognizer *>  MySensorGesturePlugin::createRecognizers()
+{
+    QList <QSensorGestureRecognizer *>  recognizers;
+    MySensorGestureRecognizer *recognizer = new MySensorGestureRecognizer(this);
+    recognizers.append(recognizer);
+
+    return recognizers;
+}
+
+QStringList MySensorGesturePlugin::supportedIds() const
+{
+       return QStringList() << "QtSensors.mygestures";
+}
+
+//! [Plugin]
+
+//Q_EXPORT_PLUGIN2(libmy_plugin_file_name, MySensorGesturePlugin);
+//#include "plugin.moc"
diff --git a/doc/src/snippets/sensorgestures/sensorgestures.pro b/doc/src/snippets/sensorgestures/sensorgestures.pro
new file mode 100644
index 00000000..c34a0188
--- /dev/null
+++ b/doc/src/snippets/sensorgestures/sensorgestures.pro
@@ -0,0 +1,9 @@
+TEMPLATE=app
+TARGET=sensorgesturessdocsnippet
+QT += sensors
+SOURCES+=main.cpp\
+    creating.cpp\
+    plugin.cpp
+HEADERS+=myplugin.h
+LIBS+=-rdynamic
+QT+=widgets
diff --git a/doc/src/snippets/snippets.pro b/doc/src/snippets/snippets.pro
index 0685c62c..f73d4a35 100644
--- a/doc/src/snippets/snippets.pro
+++ b/doc/src/snippets/snippets.pro
@@ -1,3 +1,5 @@
 TEMPLATE = subdirs
 
 SUBDIRS += sensors
+SUBDIRS += sensorgestures
+