/*

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

* All rights reserved.

* This component and the accompanying materials are made available

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

* which accompanies this distribution, and is available

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

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description:

*

*/

#include "xqaccsensor.h"

#include "xqaccsensor_p.h"

/*!

    \class XQAccelerationSensor

    \brief The XQAccelerationSensor class is used to determine current

    acceleration of the device.

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

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

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

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

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

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

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

    the XQDeviceOrientation class for that purpose.

    Example:

    \code

    #include "XQAccSensor.h"

    class MyAccelerationFilter : public QObject,

        public XQAbstractAccelerationSensorFilter

    {

        Q_OBJECT

    protected:  //from XQAbstractAccelerationSensorFilter

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

    private:

        int m_xAcceleration;

    };

    bool MyAccelerationFilter::filter(int& xAcceleration,

        int& yAcceleration, int& zAcceleration)

    {

        zAcceleration = 0; //Suppress z axis acceleration

        m_xAcceleration = xAcceleration;    //Save for further use

        return false;   //Allow next filter to be called

    }

    XQAccelerationSensor* sensor = new XQAccelerationSensor(this);

    sensor->open();

    MyAccelerationFilter* filter = new MyAccelerationFilter(this);

    sensor->addFilter(*filter);

    sensor->startReceiving();

    \endcode

*/

/*!

    Constructs a XQAccelerationSensor object with parent \a parent.

    \sa open(), startReceiving()

*/

XQAccelerationSensor::XQAccelerationSensor(QObject* parent):

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

{

}

/*!

    Destroys the XQAccelerationSensor, deleting all its children.

*/

XQAccelerationSensor::~XQAccelerationSensor()

{

}

/*!

    Adds the given filter to the top of filter stack.

*/

void XQAccelerationSensor::addFilter(XQAbstractAccelerationSensorFilter& filter)

{

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

}

/*!

    \return The list of filters that are on the stack

*/

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

{

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

}

/*!

    \return Raw x-axis acceleration data

*/

int XQAccelerationSensor::xAcceleration() const

{

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

}

/*!

    \return Raw y-axis acceleration data

*/

int XQAccelerationSensor::yAcceleration() const

{

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

}

/*!

    \return Raw z-axis acceleration data

*/

int XQAccelerationSensor::zAcceleration() const

{

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

}

/*!

    \class XQAbstractAccelerationSensorFilter

    \brief The XQAbstractAccelerationSensorFilter is an interface that can be

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

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

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

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

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

    stack to be called.

*/

/*!

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

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

    \param xAcceleration Reference to x-axis acceleration value

    \param yAcceleration Reference to y-axis acceleration value

    \param zAcceleration Reference to z-axis acceleration value

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

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

    filter in the stack to be called.

    \sa XQSensor::startReceiving()

*/

/*!

    \class XQAccelerationDataPostFilter

    \brief The XQAccelerationDataPostFilter is a special acceleration sensor

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

    acceleration axis is the same for all devices.

*/