Added documentation for the Gesture API.

Reviewed-by: trustme

8 files changed, 278 insertions, 28 deletions

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
 }