/****************************************************************************
**
** Copyright (C) 2008-2010 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation (developer.feedback@nokia.com)
**
** This file is part of the HbCore module of the UI Extensions for Mobile.
**
** GNU Lesser General Public License Usage
** This file may be used under the terms of the GNU Lesser General Public
** License version 2.1 as published by the Free Software Foundation and
** appearing in the file LICENSE.LGPL included in the packaging of this file.
** Please review the following information to ensure the GNU Lesser General
** Public License version 2.1 requirements will be met:
** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
**
** In addition, as a special exception, Nokia gives you certain additional
** rights.  These rights are described in the Nokia Qt LGPL Exception
** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
**
** If you have questions regarding the use of this file, please contact
** Nokia at developer.feedback@nokia.com.
**
****************************************************************************/

#include "hbtapgesture.h"
#include "hbgestures_p.h"

#include <QPointF>
#include <QVariant>
#include <QDebug>

//#define TAPGESTURE_DEBUG
#ifndef TAPGESTURE_DEBUG
# define DEBUG if (0) qDebug
#else
# define DEBUG qDebug
#endif


/*!
   @proto
   @hbcore
   \class HbTapGesture

   \brief The HbTapGesture class provides support for widgets needing both
   the tap and the tap-and-hold gestures.
   
   HbTapGesture is an extension to the Qt standard QTapGesture. It is
   optimized for mobile touch screens, and also supports recognition of
   mouse events for development purposes. Moreover, HbTapGesture extends
   QTapGesture by supporting both tap and tap-and-hold gestures. Use of
   Qt::TapAndHoldGesture in conjunction with Qt::TapGesture in the same
   widget would make it difficult to handle state updates and finishes in
   the widget.
   
   Compared to QTapGesture, HbTapGesture also provides additional information
   about the tap gesture position. Moreover, it has convenience functions for
   handling the position information directly in scene coordinates, without
   any need for manual conversions from global to scene coordinates. 
   
   Some of the existing Hb widgets (for example HbPushButton) already
   support tap gestures by emitting a signal such as clicked() or longPress()
   when they are tapped. If, however, you are implementing a custom widget
   whose base class does not emit the needed signals, you need to add
   tap gesture handling by using either QTapGesture or HbTapGesture.
   HbTapGesture is a recommended choice if your widget needs both tap and
   tap-and-hold gestures.
   
   HbTapGesture does not support double tap.
   
   \section _usecases_hbtapgesture Using the HbTapGesture class
      
   This example shows how to make a custom widget recognize the tap and
   tap-and-hold gestures. The custom widget in the example derives from
   HbWidget.

   <ol>
   <li>   
   Register for tap gestures by using the base class function
   QGraphicsObject::grabGesture(). QGraphicsObject::grabGesture() can be
   called several times with different arguments, if the widget is interested
   in other gesture types as well.
   
   \code
   // This widget is interested in tap and pan gestures.
   grabGesture(Qt::TapGesture);
   grabGesture(Qt::PanGesture);
   \endcode
   </li>
   
   <li> 
   Reimplement HbWidgetBase::gestureEvent() to handle gestures that are
   meaningful for your custom widget.
   
   HbTapGesture::tapStyleHint() can be used to query whether the tap was
   a normal tap or tap-and-hold at the time of Qt::GestureUpdated or
   Qt::GestureFinished. A gesture update will be sent at the time when
   the tap-and-hold timer triggers. No updates are sent of the finger
   movement during the tap.
     
   \code
   void MyWidget::gestureEvent(QGestureEvent *event)
   {
       if (HbTapGesture *tap = qobject_cast<HbTapGesture *>
           (event->gesture(Qt::TapGesture))) {
       
           switch (tap->state()) {
           
           case Qt::GestureStarted:
               // Visualize the active state of the widget.
               break;
           case Qt::GestureUpdated:
           
               // Long tap is triggered if the gesture takes
               // more than 0.5 seconds. Handle it here.
               if (tap->tapStyleHint() == HbTapGesture::TapAndHold) {               
                   // Emit a long tap signal.               
               }
               
               break;
           case Qt::GestureCanceled:
               // Visualize the non-active state of the widget.
               break;
           case Qt::GestureFinished:
           
               // Visualize the non-active state of the widget.
               
               // Short tap is handled when the gesture is finished.
               if (tap->tapStyleHint() == HbTapGesture::Tap) {               
                   // Emit a short tap signal.               
               }
               
               break;
           default:
               break;
           }           
       }
       
       // Handle other gesture types that have been grabbed. There may be
       // several, since all gestures that are active at the same moment
       // are sent within the same gesture event.
       if (HbPanGesture *pan = qobject_cast<HbPanGesture *>
           (event->gesture(Qt::PanGesture))) {
           // handle the pan gesture
       }
       
   }   
   \endcode
   </li>
   </ol>

   \sa TapStyleHint, QTapGesture

*/

/*!
    \enum HbTapGesture::TapStyleHint
    Defines the tap style.
*/

/*!
    \var HbTapGesture::TapStyleHint HbTapGesture::Tap
    Normal (short) tap.
*/

/*!
    \var HbTapGesture::TapStyleHint HbTapGesture::TapAndHold
    Long press (tap-and-hold).
*/

/*!
    Constructor.
    
    \param parent Parent for the gesture.
*/
HbTapGesture::HbTapGesture(QObject *parent)
    : QTapGesture(parent), d_ptr(new HbTapGesturePrivate)
{
    DEBUG() << "Creating" << this;
}

/*!
    Constructor required by the shared d-pointer paradigm.
    \param dd Custom private data.
    \param parent Parent for the gesture.

*/
HbTapGesture::HbTapGesture( HbTapGesturePrivate &dd, QObject *parent )
    : QTapGesture(parent), d_ptr( &dd )
{
    DEBUG() << "Creating" << this;
}

/*!
    Destructor.
*/
HbTapGesture::~HbTapGesture()
{
    DEBUG() << "Deleting" << this;
    delete d_ptr;
}

/*!
    Returns the starting position of the tap gesture in screen coordinates.
    
    \sa setStartPos()
*/
QPointF HbTapGesture::startPos() const
{
    Q_D(const HbTapGesture);
    return d->mStartPos;
}

/*!
    Sets the starting position of the tap gesture in screen coordinates.
    This function is used by the framework gesture recognition logic,
    and it should not be used by the widget receiving the gesture.
    
    \sa startPos()
*/
void HbTapGesture::setStartPos(const QPointF &startPos)
{
    Q_D(HbTapGesture);
    d->mStartPos = startPos;
}

/*!
    Returns the starting position of the tap gesture in scene coordinates.
    
    \sa setSceneStartPos()
*/
QPointF HbTapGesture::sceneStartPos() const
{
    Q_D(const HbTapGesture);
    return d->mSceneStartPos;
}

/*!
    Sets the starting position of the tap gesture in scene coordinates.
    This function is used by the framework gesture recognition logic,
    and it should not be used by the widget receiving the gesture.
    
    \sa sceneStartPos()
*/
void HbTapGesture::setSceneStartPos(const QPointF &startPos)
{
    Q_D(HbTapGesture);
    d->mSceneStartPos = startPos;
}

/*!
    Returns the current position of the tap gesture in scene coordinates.
    
    \sa setScenePosition(), QTapGesture::position()
*/
QPointF HbTapGesture::scenePosition() const
{
    Q_D(const HbTapGesture);
    return d->mScenePosition;
}

/*!
    Sets the current position of the tap gesture in scene coordinates.
    This function is used by the framework gesture recognition logic,
    and it should not be used by the widget receiving the gesture.
    
    \sa scenePosition(), QTapGesture::position()
*/
void HbTapGesture::setScenePosition(const QPointF &startPos)
{
    Q_D(HbTapGesture);
    d->mScenePosition = startPos;
}

/*!
    Returns information about whether the tap is a short tap or long press
    (tap-and-hold).

    The tapStyleHint property is by default Tap and in case of long press,
    a gesture update event is sent and tapStyleHint changed to TapAndHold.
*/
HbTapGesture::TapStyleHint HbTapGesture::tapStyleHint() const
{
    Q_D(const HbTapGesture);
    return d->mTapStyleHint;
}