diff options
Diffstat (limited to 'src/gui/kernel/qgesture.cpp')
| -rw-r--r-- | src/gui/kernel/qgesture.cpp | 297 |
1 files changed, 139 insertions, 158 deletions
diff --git a/src/gui/kernel/qgesture.cpp b/src/gui/kernel/qgesture.cpp index d7b2d1bf77..d53b419d5d 100644 --- a/src/gui/kernel/qgesture.cpp +++ b/src/gui/kernel/qgesture.cpp @@ -41,190 +41,173 @@ #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() + + The signal is emitted when the gesture is started. Extended information + about the gesture is contained in the signal sender object. - \brief The type of the gesture. + 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 + +/*! + Returns the gesture recognition state. + */ +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 + Sets this gesture's recognition state to \a state. + */ +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 +222,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 +237,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 { @@ -267,49 +250,47 @@ void QGesture::setPos(const QPoint &point) } /*! - \class QPanningGesture - \since 4.6 - - \brief The QPanningGesture class represents a Pan gesture, - providing additional information related to panning. + Sets the \a graphicsItem the gesture is filtering events for. - This class is provided for convenience, panning direction - information is also contained in the QGesture object in it's - properties. -*/ + The gesture will install an event filter to the \a graphicsItem and + redirect them to the filterEvent() function. -/*! \internal + \sa graphicsItem() */ -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 |