diff options
| -rw-r--r-- | doc/src/qt4-intro.qdoc | 4 | ||||
| -rw-r--r-- | src/corelib/global/qnamespace.qdoc | 41 | ||||
| -rw-r--r-- | src/gui/graphicsview/qgraphicsitem.cpp | 11 | ||||
| -rw-r--r-- | src/gui/kernel/qapplication.cpp | 18 | ||||
| -rw-r--r-- | src/gui/kernel/qevent.cpp | 70 | ||||
| -rw-r--r-- | src/gui/kernel/qevent.h | 2 | ||||
| -rw-r--r-- | src/gui/kernel/qgesture.cpp | 65 | ||||
| -rw-r--r-- | src/gui/kernel/qgesturerecognizer.cpp | 89 | ||||
| -rw-r--r-- | src/gui/kernel/qwidget.cpp | 10 |
9 files changed, 280 insertions, 30 deletions
diff --git a/doc/src/qt4-intro.qdoc b/doc/src/qt4-intro.qdoc index a946540..00b7709 100644 --- a/doc/src/qt4-intro.qdoc +++ b/doc/src/qt4-intro.qdoc @@ -567,8 +567,8 @@ \o Enable extensibility. \endlist - See the QTouchEvent class documentation for more information. The - Gesture framework API is still subject to change. + See the QTouchEvent class documentation for more information on multi-touch + and QGestureEvent for gestures. \section1 DOM access API diff --git a/src/corelib/global/qnamespace.qdoc b/src/corelib/global/qnamespace.qdoc index 385edad..5956677 100644 --- a/src/corelib/global/qnamespace.qdoc +++ b/src/corelib/global/qnamespace.qdoc @@ -2796,15 +2796,54 @@ This enum type describes the state of a gesture. - \value NoGesture Initial state \value GestureStarted A continuous gesture has started. \value GestureUpdated A gesture continues. \value GestureFinished A gesture has finished. + \value GestureCanceled A gesture was canceled. + \omitvalue NoGesture \sa QGesture */ /*! + \enum Qt::GestureType + \since 4.6 + + This enum type describes the standard gestures. + + \value TapGesture A Tap gesture. + \value TapAndHoldGesture A Tap-And-Hold (Long-Tap) gesture. + \value PanGesture A Pan gesture. + \value PinchGesture A Pinch gesture. + \value SwipeGesture A Swipe gesture. + \value CustomGesture User-defined gesture id. + \value LastGestureType Last user gesture id + + User-defined gestures are registered with + QApplication::registerGestureRecognizer which generated a custom gesture id + within range between CustomGesture and LastGestureType. + + \sa QGesture, QWidget::grabGesture() +*/ + +/*! + \enum Qt::GestureContext + \since 4.6 + + This enum type describes the context of a gesture. + + For a QGesture to trigger, the gesture recognizer should filter events for + a widget tree. This enum describes for which widget the gesture recognizer + should filter events: + + \value WidgetGesture Gestures can only start over the widget itself. + \value WidgetWithChildrenGesture Gestures can start on the widget or over + any of its children. + + \sa QWidget::grabGesture() +*/ + +/*! \enum Qt::NavigationMode \since 4.6 diff --git a/src/gui/graphicsview/qgraphicsitem.cpp b/src/gui/graphicsview/qgraphicsitem.cpp index 81bbb5c..b86f9fe 100644 --- a/src/gui/graphicsview/qgraphicsitem.cpp +++ b/src/gui/graphicsview/qgraphicsitem.cpp @@ -7287,10 +7287,17 @@ QGraphicsObject::QGraphicsObject(QGraphicsItemPrivate &dd, QGraphicsItem *parent QGraphicsItem::d_ptr->isObject = true; } -void QGraphicsObject::grabGesture(Qt::GestureType type, Qt::GestureContext context) +/*! + Subscribes the graphics object to a given \a gesture with a \a context. + + \sa QGestureEvent + \since 4.6 +*/ + +void QGraphicsObject::grabGesture(Qt::GestureType gesture, Qt::GestureContext context) { QGraphicsItemPrivate * const d = QGraphicsItem::d_func(); - d->gestureContext.insert(type, context); + d->gestureContext.insert(gesture, context); (void)QGestureManager::instance(); // create a gesture manager } diff --git a/src/gui/kernel/qapplication.cpp b/src/gui/kernel/qapplication.cpp index bfccd41..d188468 100644 --- a/src/gui/kernel/qapplication.cpp +++ b/src/gui/kernel/qapplication.cpp @@ -5619,11 +5619,29 @@ Q_GUI_EXPORT void qt_translateRawTouchEvent(QWidget *window, QApplicationPrivate::translateRawTouchEvent(window, deviceType, touchPoints); } +/*! + Registers \a recognizer in the gesture framework and returns a gesture id. + + QApplication takes ownership of \a recognizer and returns the gesture type + id associated with it. For gesture recognizers which handle custom QGesture + objects (i.e. return Qt::CustomGesture in a QGesture::gestureType() + function, the return value is a gesture id between Qt::CustomGesture and + Qt::LastGestureType. + + \sa unregisterGestureRecognizer, QGestureRecognizer::createGesture, QGesture + \since 4.6 +*/ Qt::GestureType QApplication::registerGestureRecognizer(QGestureRecognizer *recognizer) { return QGestureManager::instance()->registerGestureRecognizer(recognizer); } +/*! + Unregisters all gesture recognizers of specified \a type. + + \sa registerGestureRecognizer + \since 4.6 +*/ void QApplication::unregisterGestureRecognizer(Qt::GestureType type) { QGestureManager::instance()->unregisterGestureRecognizer(type); diff --git a/src/gui/kernel/qevent.cpp b/src/gui/kernel/qevent.cpp index 4316714..1834874 100644 --- a/src/gui/kernel/qevent.cpp +++ b/src/gui/kernel/qevent.cpp @@ -4200,27 +4200,39 @@ QTouchEvent::TouchPoint &QTouchEvent::TouchPoint::operator=(const QTouchEvent::T gestures. The QGestureEvent class contains a list of gestures that are being executed - right now (\l{QGestureEvent::}{activeGestures()}) and a list of gestures - that are \l{QGestureEvent::canceledGestures}{cancelled} (a gesture might be - cancelled because the window lost focus, or because of timeout, etc). + right now (\l{QGestureEvent::}{activeGestures}) and a list of gestures + that are \l{QGestureEvent::canceledGestures}{canceled} (a gesture might be + canceled if the current window looses focus, or because of a timeout, etc). - \sa QGesture + If the event is not \l{QEvent::accept}{accept}ed, all individual QGesture + object that were not accepted will be propagated up the parent widget chain + until a widget accepts it with \l{QGestureEvent::accept}{accept()}, or an + event filter consumes it. + + \sa QGesture, QGestureRecognizer, + QWidget::grabGesture(), QGraphicsObject::grabGesture() */ /*! Creates new QGestureEvent containing a list of \a gestures. */ -QGestureEvent::QGestureEvent(const QList<QGesture*> &gestures) +QGestureEvent::QGestureEvent(const QList<QGesture *> &gestures) : QEvent(QEvent::Gesture), gestures_(gestures) { } -QList<QGesture*> QGestureEvent::allGestures() const +/*! + Returns all gestures that are delivered in the event. +*/ +QList<QGesture *> QGestureEvent::allGestures() const { return gestures_; } -QGesture* QGestureEvent::gesture(Qt::GestureType type) +/*! + Returns a gesture object by \a type. +*/ +QGesture *QGestureEvent::gesture(Qt::GestureType type) const { for(int i = 0; i < gestures_.size(); ++i) if (gestures_.at(i)->gestureType() == type) @@ -4228,16 +4240,34 @@ QGesture* QGestureEvent::gesture(Qt::GestureType type) return 0; } -QList<QGesture*> QGestureEvent::activeGestures() const +/*! + Returns a list of active (i.e. not canceled) gestures. +*/ +QList<QGesture *> QGestureEvent::activeGestures() const { return gestures_; } -QList<QGesture*> QGestureEvent::canceledGestures() const +/*! + Returns a list of canceled gestures. +*/ +QList<QGesture *> QGestureEvent::canceledGestures() const { return gestures_; } +/*! + Sets the accept flag of the \a gesture object + + Setting the accept parameter indicates that the event receiver wants the \a + gesture. Unwanted gestures might be propagated to the parent widget. By + default, gestures in events of type QEvent::Gesture are accepted, and + gestures in QEvent::GestureOverride events are ignored by default. + + For convenience, the accept flag can also be set with + \l{QGestureEvent::accept}{accept(gesture)}, and cleared with + \l{QGestureEvent::ignore}{ignore(gesture)}. +*/ void QGestureEvent::setAccepted(QGesture *gesture, bool value) { setAccepted(false); @@ -4245,16 +4275,38 @@ void QGestureEvent::setAccepted(QGesture *gesture, bool value) gesture->d_func()->accept = value; } +/*! + Sets the accept flag of the \a gesture object, the equivalent of calling + \l{QGestureEvent::setAccepted}{setAccepted}(gesture, true). + + Setting the accept parameter indicates that the event receiver wants the + gesture. Unwanted gestures might be propagated to the parent widget. + + \sa QGestureEvent::ignore() +*/ void QGestureEvent::accept(QGesture *gesture) { setAccepted(gesture, true); } +/*! + Clears the accept flag parameter of the \a gesture object, the equivalent + of calling \l{QGestureEvent::setAccepted}{setAccepted}(gesture, false). + + Clearing the accept parameter indicates that the event receiver does not + want the gesture. Unwanted gestures might be propgated to the parent + widget. + + \sa QGestureEvent::accept() +*/ void QGestureEvent::ignore(QGesture *gesture) { setAccepted(gesture, false); } +/*! + Returns true if the \a gesture is accepted. +*/ bool QGestureEvent::isAccepted(QGesture *gesture) const { return gesture ? gesture->d_func()->accept : false; diff --git a/src/gui/kernel/qevent.h b/src/gui/kernel/qevent.h index 224b479..3516222 100644 --- a/src/gui/kernel/qevent.h +++ b/src/gui/kernel/qevent.h @@ -826,7 +826,7 @@ public: QGestureEvent(const QList<QGesture *> &gestures); QList<QGesture *> allGestures() const; - QGesture *gesture(Qt::GestureType type); + QGesture *gesture(Qt::GestureType type) const; QList<QGesture *> activeGestures() const; QList<QGesture *> canceledGestures() const; diff --git a/src/gui/kernel/qgesture.cpp b/src/gui/kernel/qgesture.cpp index 68cb9cd..2bcf98b 100644 --- a/src/gui/kernel/qgesture.cpp +++ b/src/gui/kernel/qgesture.cpp @@ -51,35 +51,82 @@ QT_BEGIN_NAMESPACE \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). + QGesture objects are delivered to widgets and + \l{QGraphicsObject}{QGraphicsObject}s with a QGestureEvent. - 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. + The class has a list of properties that can be queried by the user to get + some gesture-specific arguments (i.e. an scale factor of the Pinch + gesture). + + When creating custom gesture recognizers, they might add new dynamic + properties to the QGesture object, or custom gesture recognizer developers + might subclass the QGesture class (or any of classes that derive from it) + to provide additional information. \sa QGestureEvent, QGestureRecognizer */ +/*! + Constructs a new gesture object with the given \a parent. + + QGesture objects are created by gesture recognizers in the + QGestureRecognizer::createGesture() function. +*/ QGesture::QGesture(QObject *parent) : QObject(*new QGesturePrivate, parent) { d_func()->gestureType = Qt::CustomGesture; } +/*! + \internal +*/ QGesture::QGesture(QGesturePrivate &dd, QObject *parent) : QObject(dd, parent) { } +/*! + Destroys the gesture object. +*/ QGesture::~QGesture() { } +/*! + \property QGesture::state + + The current state of the gesture. +*/ + +/*! + \property QGesture::gestureType + + The type of the gesture. +*/ + +/*! + \property QGesture::hotSpot + + \brief The point that is used to find the receiver for the gesture event. + + If the hotSpot is not set, targetObject is used as the receiver of the + gesture event. +*/ + +/*! + \property QGesture::hasHotSpot + + Whether the hotSpot property is set. +*/ + +/*! + \property QGesture::targetObject + + The target object which will receive the gesture event if the hotSpot is + not set. +*/ + Qt::GestureType QGesture::gestureType() const { return d_func()->gestureType; diff --git a/src/gui/kernel/qgesturerecognizer.cpp b/src/gui/kernel/qgesturerecognizer.cpp index 590f09e..e0515c2 100644 --- a/src/gui/kernel/qgesturerecognizer.cpp +++ b/src/gui/kernel/qgesturerecognizer.cpp @@ -45,27 +45,108 @@ QT_BEGIN_NAMESPACE +/*! + \class QGestureRecognizer + \since 4.6 + + \brief The QGestureRecognizer is a base class for implementing custom + gestures. + + \sa QGesture +*/ + +/*! + \enum QGestureRecognizer::ResultFlags + + This enum type describes the result of the current event filtering step in + a gesture recognizer state machine. + + The result consists of a state value (one of Ignore, NotGesture, + MaybeGesture, GestureTriggered, GestureFinished) and an optional hint + (ConsumeEventHint). + + \value Ignore The event doesn't change the state of the recognizer. + + \value NotGesture The event made it clear that it is not a gesture. If the + gesture recognizer was in GestureTriggered state before, then the gesture + is canceled and the appropriate QGesture object will be delivered to the + target as a part of a QGestureEvent. + + \value MaybeGesture The event changed the internal state of the recognizer, + but it isn't clear yet if it is a gesture or not. The recognizer needs to + filter more events to decide. Gesture recognizers in the MaybeGesture state + may be reset automatically if it takes too long to recognizer a gesture. + + \value GestureTriggered The gesture has been triggered and the appropriate + QGesture object will be delivered to the target as a part of a + QGestureEvent. + + \value GestureFinished The gesture has been finished successfully and the + appropriate QGesture object will be delivered to the target as a part of a + QGestureEvent. + + \value ConsumeEventHint The hint specifies if the gesture framework should + consume the filtered event and not deliver it to the receiver. + + \omitvalue ResultState_Mask + \omitvalue ResultHint_Mask + + \sa QGestureRecognizer::filterEvent() +*/ + +/*! + Constructs a new gesture recognizer object. +*/ QGestureRecognizer::QGestureRecognizer() { } +/*! + Destroys the gesture recognizer object. +*/ QGestureRecognizer::~QGestureRecognizer() { } -QGesture *QGestureRecognizer::createGesture(QObject *) +/*! + This function is called by Qt to creates a new QGesture object for the + given \a target (QWidget or QGraphicsObject). + + Reimplement this function to create a custom QGesture-derived gesture + object if necessary. +*/ +QGesture *QGestureRecognizer::createGesture(QObject *target) { + Q_UNUSED(target); return new QGesture; } -void QGestureRecognizer::reset(QGesture *state) +/*! + This function is called by Qt to reset a \a gesture. + + Reimplement this function if a custom QGesture-derived gesture object is + used which requires resetting additional properties. +*/ +void QGestureRecognizer::reset(QGesture *gesture) { - if (state) { - QGesturePrivate *d = state->d_func(); + if (gesture) { + QGesturePrivate *d = gesture->d_func(); d->state = Qt::NoGesture; d->hotSpot = QPointF(); d->targetObject = 0; } } +/*! + \fn QGestureRecognizer::filterEvent(QGesture *gesture, QObject *watched, QEvent *event) + + This function is called by Qt to filter an \a event for a \a watched object + (QWidget or QGraphicsObject). + + Returns the result of the current recognition step. The state of the \a + gesture object is set depending on the result. + + \sa Qt::GestureState +*/ + QT_END_NAMESPACE diff --git a/src/gui/kernel/qwidget.cpp b/src/gui/kernel/qwidget.cpp index bce06e0..7dc3ae9 100644 --- a/src/gui/kernel/qwidget.cpp +++ b/src/gui/kernel/qwidget.cpp @@ -11672,10 +11672,16 @@ QGraphicsProxyWidget *QWidget::graphicsProxyWidget() const Synonym for QList<QWidget *>. */ -void QWidget::grabGesture(Qt::GestureType type, Qt::GestureContext context) +/*! + Subscribes the widget to a given \a gesture with a \a context. + + \sa QGestureEvent + \since 4.6 +*/ +void QWidget::grabGesture(Qt::GestureType gesture, Qt::GestureContext context) { Q_D(QWidget); - d->gestureContext.insert(type, context); + d->gestureContext.insert(gesture, context); (void)QGestureManager::instance(); // create a gesture manager } |