1 /*

     2 * Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:

    15 *

    16 */

    17 #include "xqaccsensor.h"

    18 #include "xqaccsensor_p.h"

    19 

    20 /*!

    21     \class XQAccelerationSensor

    22 

    23     \brief The XQAccelerationSensor class is used to determine current

    24     acceleration of the device.

    25 

    26     Note that the orientation of the device affects on the acceleration sensors

    27     due to acceleration caused by Earth's gravity. Therefore it is wrong to

    28     assume that the axis values are zero when the device stands still.

    29 

    30     XQAccelerationSensor axis data shouldn't be directly used to determine the

    31     device orientation, though. It may sound good to use XQAccelerationSensor

    32     in a game that is controlled by leaning the device but the data ranges and

    33     even axis orientation may differ highly in different devices. Instead, use

    34     the XQDeviceOrientation class for that purpose.

    35 

    36     Example:

    37     \code

    38     #include "XQAccSensor.h"

    39     class MyAccelerationFilter : public QObject,

    40         public XQAbstractAccelerationSensorFilter

    41     {

    42         Q_OBJECT

    43     protected:  //from XQAbstractAccelerationSensorFilter

    44         bool filter(int& xAcceleration, int& yAcceleration, int& zAcceleration);

    45     private:

    46         int m_xAcceleration;

    47     };

    48 

    49     bool MyAccelerationFilter::filter(int& xAcceleration,

    50         int& yAcceleration, int& zAcceleration)

    51     {

    52         zAcceleration = 0; //Suppress z axis acceleration

    53         m_xAcceleration = xAcceleration;    //Save for further use

    54         return false;   //Allow next filter to be called

    55     }

    56 

    57     XQAccelerationSensor* sensor = new XQAccelerationSensor(this);

    58     sensor->open();

    59 

    60     MyAccelerationFilter* filter = new MyAccelerationFilter(this);

    61     sensor->addFilter(*filter);

    62 

    63     sensor->startReceiving();

    64     \endcode

    65 */

    66 

    67 /*!

    68     Constructs a XQAccelerationSensor object with parent \a parent.

    69     \sa open(), startReceiving()

    70 */

    71 XQAccelerationSensor::XQAccelerationSensor(QObject* parent):

    72     XQSensor(*new XQAccelerationSensorPrivate(*this), parent)

    73 {

    74 }

    75 

    76 /*!

    77     Destroys the XQAccelerationSensor, deleting all its children.

    78 */

    79 XQAccelerationSensor::~XQAccelerationSensor()

    80 {

    81 }

    82 

    83 /*!

    84     Adds the given filter to the top of filter stack.

    85 */

    86 void XQAccelerationSensor::addFilter(XQAbstractAccelerationSensorFilter& filter)

    87 {

    88     static_cast<XQAccelerationSensorPrivate*>(d)->addFilter(filter);

    89 }

    90 

    91 

    92 /*!

    93     \return The list of filters that are on the stack

    94 */

    95 QList<XQAbstractAccelerationSensorFilter*>& XQAccelerationSensor::filters()

    96 {

    97     return static_cast<XQAccelerationSensorPrivate*>(d)->filters();

    98 }

    99 

   100 /*!

   101     \return Raw x-axis acceleration data

   102 */

   103 int XQAccelerationSensor::xAcceleration() const

   104 {

   105     return static_cast<XQAccelerationSensorPrivate*>(d)->xAcceleration();

   106 }

   107 

   108 /*!

   109     \return Raw y-axis acceleration data

   110 */

   111 int XQAccelerationSensor::yAcceleration() const

   112 {

   113     return static_cast<XQAccelerationSensorPrivate*>(d)->yAcceleration();

   114 }

   115 

   116 /*!

   117     \return Raw z-axis acceleration data

   118 */

   119 int XQAccelerationSensor::zAcceleration() const

   120 {

   121     return static_cast<XQAccelerationSensorPrivate*>(d)->zAcceleration();

   122 }

   123 

   124 /*!

   125     \class XQAbstractAccelerationSensorFilter

   126 

   127     \brief The XQAbstractAccelerationSensorFilter is an interface that can be

   128     used to filter and/or manipulate data received from the acceleration sensor.

   129 

   130     The client which is interested in sensor events implements this interface.

   131 

   132     There may potentially be several filters in stack. They are called in

   133     reverse order (i.e. the last filter added to the stack is always called first).

   134     Each filter may manipulate the acceleration data and also allow or deny the next filter in

   135     stack to be called.

   136 */

   137 

   138 /*!

   139     \fn virtual bool XQAbstractAccelerationSensorFilter::filter(int& xAcceleration, int& yAcceleration, int& zAcceleration) = 0;

   140 

   141     This function is called when the acceleration of the device changes.

   142 

   143     \param xAcceleration Reference to x-axis acceleration value

   144     \param yAcceleration Reference to y-axis acceleration value

   145     \param zAcceleration Reference to z-axis acceleration value

   146     \return True if this filter has "filtered out" the event, i.e. the event

   147     is not to be sent to the next filter in the stack. Returning false allows the next

   148     filter in the stack to be called.

   149     \sa XQSensor::startReceiving()

   150 */

   151 

   152 /*!

   153     \class XQAccelerationDataPostFilter

   154 

   155     \brief The XQAccelerationDataPostFilter is a special acceleration sensor

   156     filter. It modifies the acceleration sensor data so that the orientation of each

   157     acceleration axis is the same for all devices.

   158 */