path: root/src/gui/kernel/qgesture.cpp

/****************************************************************************
**
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the QtGui module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** No Commercial Usage
** This file contains pre-release code and may not be distributed.
** You may use this file in accordance with the terms and conditions
** contained in the Technology Preview License Agreement accompanying
** this package.
**
** GNU Lesser General Public License Usage
** Alternatively, 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 qt-info@nokia.com.
**
**
**
**
**
**
**
**
** $QT_END_LICENSE$
**
****************************************************************************/

#include "qgesture.h"
#include <private/qgesture_p.h>
#include "qgraphicsitem.h"

QT_BEGIN_NAMESPACE


class QEventFilterProxyGraphicsItem : public QGraphicsItem
{
public:
    QEventFilterProxyGraphicsItem(QGesture *g)
            : gesture(g)
    {
    }
    bool sceneEventFilter(QGraphicsItem *, QEvent *event)
    {
        return gesture ? gesture->filterEvent(event) : false;
    }
    QRectF boundingRect() const { return QRectF(); }
    void paint(QPainter*, const QStyleOptionGraphicsItem*, QWidget*) { }

private:
    QGesture *gesture;
};

/*!
    \class QGesture
    \since 4.6

    \brief The QGesture class is the base class for implementing custom
    gestures.

    This class represents both an object that recognizes a gesture out of a set
    of input events (a gesture recognizer), and a gesture object itself that
    can be used to get extended information about the triggered gesture.

    The class has a list of properties that can be queried by the user to get
    some gesture-specific parameters (for example, an offset of a Pan gesture).

    Usually gesture recognizer implements a state machine, storing its state
    internally in the recognizer object. The recognizer receives input events
    through the \l{QGesture::}{filterEvent()} virtual function and decides
    whether the event should change the state of the recognizer by emitting an
    appropriate signal.

    Input events should be either fed to the recognizer one by one with a
    filterEvent() function, or the gesture recognizer should be attached to an
    object it filters events for by specifying it as a parent object. The
    QGesture object installs itself as an event filter to the parent object
    automatically, the unsetObject() function should be used to remove an event
    filter from the parent object. To make a
    gesture that operates on a QGraphicsItem, both the appropriate QGraphicsView
    should be passed as a parent object and setGraphicsItem() functions should
    be used to attach a gesture to a graphics item.

    This is a base class, to create a custom gesture type, you should subclass
    it and implement its pure virtual functions.

    \sa QPanGesture
*/

/*! \fn bool QGesture::filterEvent(QEvent *event)

    Parses input \a event and emits a signal when detects a gesture.

    In your reimplementation of this function, if you want to filter the \a
    event out, i.e. stop it being handled further, return true; otherwise
    return false;

    This is a pure virtual function that needs to be implemented in subclasses.
*/

/*! \fn void QGesture::started()

    The signal is emitted when the gesture is started. Extended information
    about the gesture is contained in the signal sender object.

    In addition to started(), a triggered() signal should also be emitted.
*/

/*! \fn void QGesture::triggered()

    The signal is emitted when the gesture is detected. Extended information
    about the gesture is contained in the signal sender object.
*/

/*! \fn void QGesture::finished()

    The signal is emitted when the gesture is finished. Extended information
    about the gesture is contained in the signal sender object.
*/

/*! \fn void QGesture::cancelled()

  The signal is emitted when the gesture is cancelled, for example the
  reset() function is called while the gesture was in the process of
  emitting a triggered() signal.  Extended information about the
  gesture is contained in the sender object.
*/

/*!
  Creates a new gesture handler object and marks it as a child of \a
  parent.  \a gestureTarget is the object that the gesture will watch
  for events.

  The \a parent object is also the default event source for the
  gesture, meaning that the gesture installs itself as an event filter
  for the \a parent.

  \sa setGraphicsItem()
*/
QGesture::QGesture(QObject *gestureTarget, QObject *parent)
    : QObject(*new QGesturePrivate, parent)
{
    setGestureTarget(gestureTarget);
}

/*! \internal
 */
QGesture::QGesture(QGesturePrivate &dd, QObject *gestureTarget, QObject *parent)
    : QObject(dd, parent)
{
    setGestureTarget(gestureTarget);
}

/*!
    Destroys the gesture object.
*/
QGesture::~QGesture()
{
}

/*!
    \property QGesture::gestureTarget

    Gesture target is the object that the gesture will watch for events.
    Typically this means that the gesture installs an event filter on the
    target object.
*/
void QGesture::setGestureTarget(QObject *object)
{
    d_func()->setupGestureTarget(object);
}

QObject* QGesture::gestureTarget() const
{
    return d_func()->gestureTarget;
}

void QGesturePrivate::setupGestureTarget(QObject *object)
{
    Q_Q(QGesture);
    if (gestureTarget)
        gestureTarget->removeEventFilter(q);
    if (object)
        object->installEventFilter(q);
    gestureTarget = object;
}

/*! \internal
 */
bool QGesture::eventFilter(QObject *receiver, QEvent *event)
{
    Q_D(QGesture);
    if (d->graphicsItem && receiver == parent())
        return false;
    return filterEvent(event);
}

/*!
    \property QGesture::state

    \brief The current state of the gesture.
*/

/*!
  Returns the gesture recognition state.
 */
Qt::GestureState QGesture::state() const
{
    return d_func()->state;
}

/*!
  Sets this gesture's recognition state to \a state and emits appropriate
  signals.

  This functions emits the signals according to the old state and the new
  \a state, and it should be called after all the internal properties have been
  initialized.

  \sa started(), triggered(), finished(), cancelled()
 */
void QGesture::updateState(Qt::GestureState state)
{
    Q_D(QGesture);
    if (d->state == state) {
        if (state == Qt::GestureUpdated)
            emit triggered();
        return;
    }
    const Qt::GestureState oldState = d->state;
    d->state = state;
    if (state != Qt::NoGesture && oldState > state) {
        // comparing the state as ints: state should only be changed from
        // started to (optionally) updated and to finished.
        qWarning("QGesture::updateState: incorrect new state");
        return;
    }
    if (oldState == Qt::NoGesture)
        emit started();
    if (state == Qt::GestureUpdated)
        emit triggered();
    else if (state == Qt::GestureFinished)
        emit finished();
    else if (state == Qt::NoGesture)
        emit cancelled();

    if (state == Qt::GestureFinished) {
        // gesture is finished, so we reset the internal state.
        d->state = Qt::NoGesture;
    }
}

/*!
    Sets the \a graphicsItem the gesture is filtering events for.

    The gesture will install an event filter to the \a graphicsItem and
    redirect them to the filterEvent() function.

    \sa graphicsItem()
*/
void QGesture::setGraphicsItem(QGraphicsItem *graphicsItem)
{
    Q_D(QGesture);
    if (d->graphicsItem && d->eventFilterProxyGraphicsItem)
        d->graphicsItem->removeSceneEventFilter(d->eventFilterProxyGraphicsItem);
    d->graphicsItem = graphicsItem;
    if (!d->eventFilterProxyGraphicsItem)
        d->eventFilterProxyGraphicsItem = new QEventFilterProxyGraphicsItem(this);
    if (graphicsItem)
        graphicsItem->installSceneEventFilter(d->eventFilterProxyGraphicsItem);
}

/*!
    Returns the graphics item the gesture is filtering events for.

    \sa setGraphicsItem()
*/
QGraphicsItem* QGesture::graphicsItem() const
{
    return d_func()->graphicsItem;
}

/*! \fn void QGesture::reset()

    Resets the internal state of the gesture. This function might be called by
    the filterEvent() implementation in a derived class, or by the user to
    cancel a gesture.  The base class implementation calls
    updateState(Qt::NoGesture) which emits the cancelled()
    signal if the state() of the gesture indicated it was active.
*/
void QGesture::reset()
{
    updateState(Qt::NoGesture);
}

QT_END_NAMESPACE