Refactored gesture api

Rewritten the api almost from scratch, making it simplier and more
flexible at the same time.

The current implementation will not have complex gseturemanager class
inside Qt, but the QGesture base class, which represents both a
gesture recognizer and a gesture itself with a set of properties. A
set of common gestures that can use used in third-party applications
(and in Qt itself internally) is supposed to be found in
qstandardgestures.h, and a base class for user-defined gestures is in
qgesture.h

Gesture implementation for Pan on Windows7 has also been added as a
reference implementation for platform gestures.

1 files changed, 133 insertions, 175 deletions

diff --git a/src/gui/kernel/qgesture.cpp b/src/gui/kernel/qgesture.cpp
index ff369e2..32a219c 100644
--- a/src/gui/kernel/qgesture.cpp
+++ b/src/gui/kernel/qgesture.cpp
@@ -41,190 +41,166 @@
 
 #include "qgesture.h"
 #include <private/qgesture_p.h>
+#include "qgraphicsitem.h"
 
 QT_BEGIN_NAMESPACE
 
-QString qt_getStandardGestureTypeName(Qt::GestureType type);
+
+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 represents a gesture, containing all
-    properties that describe a gesture.
-
-    The widget receives a QGestureEvent with a list of QGesture
-    objects that represent gestures that are occuring on it. The class
-    has a list of properties that can be queried by the user to get
-    some gesture-specific arguments (i.e. position of the tap in the
-    DoubleTap gesture).
-
-    When creating custom gesture recognizers, they might add new
-    properties to the gesture object, or custom gesture developers
-    might subclass the QGesture objects to provide some extended
-    information. However, if the gesture developer wants to add a new
-    property to the gesture object that describe coordinate (like a
-    QPoint or QRect), it is required to subclass the QGesture and
-    re-implement the \l{QGesture::}{translate()} function to make sure
-    the coordinates are translated properly when the gesture event is
-    propagated to parent widgets.
-
-    \sa QGestureEvent, QGestureRecognizer
-*/
+    \brief The QGesture class is the base class for implementing custom
+    gestures.
 
-/*!
-    Creates a new gesture object of type \a type in a \a state and
-    marks it as a child of \a parent.
+    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.
 
-    Usually QGesture objects should only be contructed by the
-    QGestureRecognizer classes.
-*/
-QGesture::QGesture(QObject *parent, const QString &type, Qt::GestureState state)
-    : QObject(*new QGesturePrivate, parent), m_accept(0)
-{
-    Q_D(QGesture);
-    d->type = type;
-    d->state = state;
-}
+    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).
 
-/*!
-    Creates a new gesture object of type \a type in a \a state and
-    marks it as a child of \a parent.
-
-    This constructor also fills some basic information about the
-    gesture like a \a startPos which describes the start point of the
-    gesture, \a lastPos - last point where the gesture happened, \a
-    pos - a current point, \a rect - a bounding rect of the gesture,
-    \a hotSpot - a center point of the gesture, \a startTime - a time
-    when the gesture has started, \a duration - how long the gesture
-    is going on.
-
-    Usually QGesture objects should only be contructed by the
-    QGestureRecognizer classes.
-*/
-QGesture::QGesture(QObject *parent, const QString &type, const QPoint &startPos,
-                   const QPoint &lastPos, const QPoint &pos, const QRect &rect,
-                   const QPoint &hotSpot, const QDateTime &startTime,
-                   uint duration, Qt::GestureState state)
-    : QObject(*new QGesturePrivate, parent)
-{
-    Q_D(QGesture);
-    d->type = type;
-    d->state = state;
-    d->init(startPos, lastPos, pos, rect, hotSpot, startTime, duration);
-}
+    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.
 
-/*! \internal
+    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, QTapAndHoldGesture
 */
-QGesture::QGesture(QGesturePrivate &dd, QObject *parent, const QString &type,
-                   Qt::GestureState state)
-    : QObject(dd, parent)
-{
-    Q_D(QGesture);
-    d->type = type;
-    d->state = state;
-}
 
-/*!
-    Destroys the gesture object.
+/*! \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.
 */
-QGesture::~QGesture()
-{
-}
 
-/*!
-    \property QGesture::type
+/*! \fn void QGesture::started()
 
-    \brief The type of the gesture.
+    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.
 */
-QString QGesture::type() const
-{
-    return d_func()->type;
-}
 
+/*! \fn void QGesture::triggered()
 
-/*!
-    \property QGesture::state
+    The signal is emitted when the gesture is detected. Extended information
+    about the gesture is contained in the signal sender object.
+*/
 
-    \brief The current state of the gesture.
+/*! \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.
 */
-Qt::GestureState QGesture::state() const
-{
-    return d_func()->state;
-}
 
-/*!
-    Translates the internal gesture properties that represent
-    coordinates by \a offset.
+/*! \fn void QGesture::cancelled()
 
-    Custom gesture recognizer developer have to re-implement this
-    function if they want to store custom properties that represent
-    coordinates.
+    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.
 */
-void QGesture::translate(const QPoint &offset)
-{
-    Q_D(QGesture);
-    d->rect.translate(offset);
-    d->hotSpot += offset;
-    d->startPos += offset;
-    d->lastPos += offset;
-    d->pos += offset;
-}
+
 
 /*!
-    \property QGesture::rect
+    Creates a new gesture handler object and marks it as a child of \a parent.
+
+    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.
 
-    \brief The bounding rect of a gesture.
+    \sa setGraphicsItem()
 */
-QRect QGesture::rect() const
+QGesture::QGesture(QObject *parent)
+    : QObject(*new QGesturePrivate, parent)
 {
-    return d_func()->rect;
+    if (parent)
+        installEventFilter(parent);
 }
 
-void QGesture::setRect(const QRect &rect)
+/*! \internal
+ */
+QGesture::QGesture(QGesturePrivate &dd, QObject *parent)
+    : QObject(dd, parent)
 {
-    d_func()->rect = rect;
+    if (parent)
+        installEventFilter(parent);
 }
 
 /*!
-    \property QGesture::hotSpot
-
-    \brief The center point of a gesture.
+    Destroys the gesture object.
 */
-QPoint QGesture::hotSpot() const
+QGesture::~QGesture()
 {
-    return d_func()->hotSpot;
 }
 
-void QGesture::setHotSpot(const QPoint &point)
+/*! \internal
+ */
+bool QGesture::eventFilter(QObject *receiver, QEvent *event)
 {
-    d_func()->hotSpot = point;
+    Q_D(QGesture);
+    if (d->graphicsItem && receiver == parent())
+        return false;
+    return filterEvent(event);
 }
 
 /*!
-    \property QGesture::startTime
+    \property QGesture::state
 
-    \brief The time when the gesture has started.
+    \brief The current state of the gesture.
 */
-QDateTime QGesture::startTime() const
+Qt::GestureState QGesture::state() const
 {
-    return d_func()->startTime;
+    return d_func()->state;
 }
 
-/*!
-    \property QGesture::duration
-
-    \brief The duration time of a gesture.
-*/
-uint QGesture::duration() const
+void QGesture::setState(Qt::GestureState state)
 {
-    return d_func()->duration;
+    d_func()->state = state;
 }
 
 /*!
     \property QGesture::startPos
 
-    \brief The start position of the pointer.
+    \brief The start position of the gesture (if relevant).
 */
 QPoint QGesture::startPos() const
 {
@@ -239,7 +215,7 @@ void QGesture::setStartPos(const QPoint &point)
 /*!
     \property QGesture::lastPos
 
-    \brief The last recorded position of the pointer.
+    \brief The last recorded position of the gesture (if relevant).
 */
 QPoint QGesture::lastPos() const
 {
@@ -254,7 +230,7 @@ void QGesture::setLastPos(const QPoint &point)
 /*!
     \property QGesture::pos
 
-    \brief The current position of the pointer.
+    \brief The current position of the gesture (if relevant).
 */
 QPoint QGesture::pos() const
 {
@@ -266,66 +242,48 @@ void QGesture::setPos(const QPoint &point)
     d_func()->pos = point;
 }
 
-/*! \fn void QGesture::setAccepted(bool accepted)
-  Marks the gesture with the value of \a accepted.
- */
-
-/*! \fn bool QGesture::isAccepted() const
-  Returns true if the gesture is marked accepted.
- */
-
-/*! \fn void QGesture::accept()
-  Marks the gesture accepted.
-*/
-
-/*! \fn void QGesture::ignore()
-  Marks the gesture ignored.
-*/
-
 /*!
-    \class QPanningGesture
-    \since 4.6
+    Sets the \a graphicsItem the gesture is filtering events for.
 
-    \brief The QPanningGesture class represents a Pan gesture,
-    providing additional information related to panning.
+    The gesture will install an event filter to the \a graphicsItem and
+    redirect them to the filterEvent() function.
 
-    This class is provided for convenience, panning direction
-    information is also contained in the QGesture object in it's
-    properties.
+    \sa graphicsItem()
 */
-
-/*! \internal
-*/
-QPanningGesture::QPanningGesture(QObject *parent)
-    : QGesture(*new QPanningGesturePrivate, parent,
-               qt_getStandardGestureTypeName(Qt::PanGesture))
-{
-}
-
-/*! \internal
-*/
-QPanningGesture::~QPanningGesture()
+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);
 }
 
 /*!
-    \property QPanningGesture::lastDirection
+    Returns the graphics item the gesture is filtering events for.
 
-    \brief The last recorded direction of panning.
+    \sa setGraphicsItem()
 */
-Qt::DirectionType QPanningGesture::lastDirection() const
+QGraphicsItem* QGesture::graphicsItem() const
 {
-    return d_func()->lastDirection;
+    return d_func()->graphicsItem;
 }
 
-/*!
-    \property QPanningGesture::direction
+/*! \fn void QGesture::reset()
 
-    \brief The current direction of panning.
+    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 emits the cancelled()
+    signal if the state() of the gesture wasn't empty.
 */
-Qt::DirectionType QPanningGesture::direction() const
+void QGesture::reset()
 {
-    return d_func()->direction;
+    if (state() != Qt::NoGesture)
+        emit cancelled();
+    setState(Qt::NoGesture);
 }
 
 QT_END_NAMESPACE