Added documentation for the Gesture API.

Reviewed-by: trustme

1 files changed, 85 insertions, 4 deletions

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