Added documentation for the Gesture API.

Reviewed-by: trustme

1 files changed, 61 insertions, 9 deletions

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;