QAccelerometer: Add AccelerationMode property

Adds a private class.

Ctor was de-inlined, this is BC, apps linked against
old versions don't use the AccelerationMode property
so don't need to call the new ctor anyway.

Change-Id: I943ba91f33612922911515527380add648155d31
Reviewed-by: Lorn Potter <lorn.potter@gmail.com>
Reviewed-by: Thomas McGuire <thomas.mcguire@kdab.com>

3 files changed, 158 insertions, 4 deletions

diff --git a/src/sensors/qaccelerometer.cpp b/src/sensors/qaccelerometer.cpp
index 02fc7825b7..ed019f34a4 100644
--- a/src/sensors/qaccelerometer.cpp
+++ b/src/sensors/qaccelerometer.cpp
@@ -162,13 +162,37 @@ void QAccelerometerReading::setZ(qreal z)
 char const * const QAccelerometer::type("QAccelerometer");
 
 /*!
+    \enum QAccelerometer::AccelerationMode
+
+    \brief This enum represents the acceleration mode of an acceleration sensor.
+
+    The acceleration mode controls how the sensor reports acceleration. QAccelerometer::Combined
+    is the only mode in which the values can be directly physically measured, the others are an
+    approximation.
+
+    \value Gravity  Only the acceleration caused by gravity is reported. Movements of the device
+                    caused by the user have no effect other than changing the direction when the
+                    device is rotated.
+    \value User     Only the acceleration caused by the user moving the device is reported, the
+                    effect of gravity is canceled out. A device at rest therefore should report
+                    values of, or close to, zero.
+                    In other APIs, this mode might be known as \e {linear acceleration}.
+    \value Combined Both the acceleration caused by gravity and the acceleration caused by the
+                    user moving the device is reported combined.
+
+    \sa QAccelerometer::accelerationMode
+    \since 1.3
+*/
+
+/*!
     \class QAccelerometer
     \ingroup sensors_type
     \inmodule QtSensors
 
     \brief The QAccelerometer class is a convenience wrapper around QSensor.
 
-    The only behavioural difference is that this class sets the type properly.
+    The only behavioural difference is that this class sets the type properly and that it supports
+    changing the acceleration mode.
 
     This class also features a reading() function that returns a QAccelerometerReading instead of a QSensorReading.
 
@@ -179,11 +203,23 @@ char const * const QAccelerometer::type("QAccelerometer");
 */
 
 /*!
+   \internal
+ */
+QAccelerometerPrivate *QAccelerometer::d_func() const
+{
+    return static_cast<QAccelerometerPrivate*>(QSensor::d_func());
+}
+
+/*!
     \fn QAccelerometer::QAccelerometer(QObject *parent)
 
     Construct the sensor as a child of \a parent.
     \since 1.0
 */
+QAccelerometer::QAccelerometer(QObject *parent)
+    : QSensor(QAccelerometer::type, new QAccelerometerPrivate(this), parent)
+{
+}
 
 /*!
     \fn QAccelerometer::~QAccelerometer()
@@ -191,6 +227,76 @@ char const * const QAccelerometer::type("QAccelerometer");
     Destroy the sensor. Stops the sensor if it has not already been stopped.
     \since 1.0
 */
+QAccelerometer::~QAccelerometer()
+{
+}
+
+/*!
+    \property QAccelerometer::accelerationMode
+    \brief The acceleration mode controls how acceleration values are reported.
+
+    The acceleration mode controls how the acceleration sensor reports its values.
+    The default mode is QAccelerometer::Combined, which means the acceleration caused
+    by gravity is included in the reported values.
+
+    Acceleration caused by gravity and acceleration caused by the user moving the device
+    are physically impossible to distinguish because of general relativity. Most devices use
+    sensor fusion to figure out which parts of the acceleration is caused by gravity, for example
+    by using a rotation sensor to calculate the gravity direction and assuming a fixed magnitude
+    for gravity. Therefore the result is only an approximation and may be inaccurate.
+    The QAccelerometer::Combined mode is the most accurate one, as it does not involve approximating
+    the gravity.
+
+    Not all backends and devices might support setting the acceleration mode. For those cases, the
+    default mode QAccelerometer::Combined is used, changing it has no effect.
+
+    \since 1.3
+*/
+QAccelerometer::AccelerationMode QAccelerometer::accelerationMode() const
+{
+    Q_D(const QAccelerometer);
+    return d->accelerationMode;
+}
+
+/*!
+    Sets the acceleration mode to \a accelerationMode.
+    \since 1.3
+*/
+void QAccelerometer::setAccelerationMode(QAccelerometer::AccelerationMode accelerationMode)
+{
+    Q_D(QAccelerometer);
+    if (d->accelerationMode != accelerationMode) {
+        d->accelerationMode = accelerationMode;
+        emit accelerationModeChanged(d->accelerationMode);
+    }
+}
+
+/*!
+   Convenience method to set the acceleration mode to QAccelerometer::User.
+   \since 1.3
+*/
+void QAccelerometer::setUserAcceleration()
+{
+    setAccelerationMode(QAccelerometer::User);
+}
+
+/*!
+   Convenience method to set the acceleration mode to QAccelerometer::Gravity.
+   \since 1.3
+*/
+void QAccelerometer::setGravityAcceleration()
+{
+    setAccelerationMode(QAccelerometer::Gravity);
+}
+
+/*!
+   Convenience method to set the acceleration mode to QAccelerometer::Combined.
+   \since 1.3
+*/
+void QAccelerometer::setCombinedAcceleration()
+{
+    setAccelerationMode(QAccelerometer::Combined);
+}
 
 /*!
     \fn QAccelerometer::reading() const
@@ -201,6 +307,12 @@ char const * const QAccelerometer::type("QAccelerometer");
     \since 1.0
 */
 
+/*!
+    \fn QAccelerometer::accelerationModeChanged(AccelerationMode accelerationMode)
+
+    Emitted when the acceleration mode was changed.
+    \since 1.3
+*/
+
 #include "moc_qaccelerometer.cpp"
 QTM_END_NAMESPACE
-
diff --git a/src/sensors/qaccelerometer.h b/src/sensors/qaccelerometer.h
index 540112053b..c518734460 100644
--- a/src/sensors/qaccelerometer.h
+++ b/src/sensors/qaccelerometer.h
@@ -74,14 +74,42 @@ private:
     bool filter(QSensorReading *reading) { return filter(static_cast<QAccelerometerReading*>(reading)); }
 };
 
+class QAccelerometerPrivate;
+
 class Q_SENSORS_EXPORT QAccelerometer : public QSensor
 {
     Q_OBJECT
+    Q_ENUMS(AccelerationMode)
+    Q_PROPERTY(AccelerationMode accelerationMode READ accelerationMode WRITE setAccelerationMode
+               NOTIFY accelerationModeChanged)
 public:
-    explicit QAccelerometer(QObject *parent = 0) : QSensor(QAccelerometer::type, parent) {}
-    virtual ~QAccelerometer() {}
+    explicit QAccelerometer(QObject *parent = 0);
+    virtual ~QAccelerometer();
+
+    enum AccelerationMode {
+        Gravity,
+        User,
+        Combined
+    };
+
+    AccelerationMode accelerationMode() const;
+    void setAccelerationMode(AccelerationMode accelerationMode);
+
     QAccelerometerReading *reading() const { return static_cast<QAccelerometerReading*>(QSensor::reading()); }
     static char const * const type;
+
+public slots:
+    void setUserAcceleration();
+    void setGravityAcceleration();
+    void setCombinedAcceleration();
+
+signals:
+    void accelerationModeChanged(AccelerationMode accelerationMode);
+
+private:
+    friend class QAccelerometerPrivate;
+    QAccelerometerPrivate *d_func() const;
+    Q_DISABLE_COPY(QAccelerometer)
 };
 
 QTM_END_NAMESPACE
diff --git a/src/sensors/qaccelerometer_p.h b/src/sensors/qaccelerometer_p.h
index 873caf0d6f..6a7d18739a 100644
--- a/src/sensors/qaccelerometer_p.h
+++ b/src/sensors/qaccelerometer_p.h
@@ -53,6 +53,8 @@
 // We mean it.
 //
 
+#include "qsensor_p.h"
+
 QTM_BEGIN_NAMESPACE
 
 class QAccelerometerReadingPrivate
@@ -70,6 +72,18 @@ public:
     qreal z;
 };
 
+class QAccelerometerPrivate : public QSensorPrivate
+{
+public:
+    QAccelerometerPrivate(QSensor *sensor)
+        : QSensorPrivate(sensor),
+          accelerationMode(QAccelerometer::Combined)
+    {
+    }
+
+    QAccelerometer::AccelerationMode accelerationMode;
+};
+
 QTM_END_NAMESPACE
 
 #endif