Added some documentation.

Fixed missing const specifiers.

5 files changed, 128 insertions, 11 deletions

diff --git a/src/gui/kernel/qevent.cpp b/src/gui/kernel/qevent.cpp
index a7e1101..d7d193c 100644
--- a/src/gui/kernel/qevent.cpp
+++ b/src/gui/kernel/qevent.cpp
@@ -3509,6 +3509,50 @@ QMenubarUpdatedEvent::QMenubarUpdatedEvent(QMenuBar * const menuBar)
 
 #endif
 
+/*!
+    \class QGestureEvent
+    \ingroup events
+
+    \brief The QGestureEvent class provides the parameters used for
+    gesture recognition.
+
+    The QGestureEvent class contains a list of gestures that are being
+    executed right now (QGestureEvent::gestureTypes()) and a list of
+    gestures that are cancelled (the gesture might be cancelled
+    because the window lost focus, or because of timeout, etc).
+
+    \sa QGesture
+*/
+
+/*! \fn QWidget *QGestureEvent::targetWidget() const
+
+    Returns the widget the gesture event is send to.
+*/
+
+/*! \fn bool contains(const Qt::GestureType &type) const
+
+    Checks if the gesture event contains gesture of specific \a type.
+*/
+
+/*! \fn QList<Qt::GestureType> gestureTypes() const
+
+    Returns a list of gesture names that the event contains.
+*/
+
+/*! \fn const QGesture* gesture(const Qt::GestureType &type) const
+
+    Returns extended information about a gesture of specific \a type.
+*/
+
+/*! \fn QSet<Qt::GestureType> cancelledGestures() const
+
+    Returns a set of gesture names that used to be executed, but got
+    cancelled (i.e. they were not finished properly).
+*/
+
+
+
+
 QGestureEvent::QGestureEvent(QWidget *targetWidget, const QList<QGesture*> &gestures,
                              const QSet<Qt::GestureType> &cancelledGestures)
     : QEvent(QEvent::Gesture), m_targetWidget(targetWidget),
diff --git a/src/gui/kernel/qevent.h b/src/gui/kernel/qevent.h
index 858e2ea..cde7cb2 100644
--- a/src/gui/kernel/qevent.h
+++ b/src/gui/kernel/qevent.h
@@ -726,12 +726,12 @@ public:
     QWidget *targetWidget() const
     { return m_targetWidget; }
 
-    inline bool contains(const Qt::GestureType &gestureType) const
-    { return gesture(gestureType) != 0; }
+    inline bool contains(const Qt::GestureType &type) const
+    { return gesture(type) != 0; }
     inline QList<Qt::GestureType> gestureTypes() const
     { return m_gestures.keys(); }
-    inline const QGesture* gesture(const Qt::GestureType &gestureType) const
-    { return m_gestures.value(gestureType, QSharedPointer<QGesture>()).data(); }
+    inline const QGesture* gesture(const Qt::GestureType &type) const
+    { return m_gestures.value(type, QSharedPointer<QGesture>()).data(); }
 
     inline QSet<Qt::GestureType> cancelledGestures() const
     { return m_cancelledGestures; }
diff --git a/src/gui/kernel/qgesturerecognizer.h b/src/gui/kernel/qgesturerecognizer.h
index 3ed96c0..a831d8a 100644
--- a/src/gui/kernel/qgesturerecognizer.h
+++ b/src/gui/kernel/qgesturerecognizer.h
@@ -49,6 +49,58 @@
 
 QT_BEGIN_NAMESPACE
 
+/*!
+    \class QGestureRecognizer
+
+    \brief The base class for implementing custom gestures.
+
+    This is a base class, to create a custom gesture type, you should
+    subclass it and implement pure virtual functions.
+
+    Usually gesture recognizer implements state machine, storing its
+    state internally in the recognizer object. The recognizer receives
+    input events through the QGestureRecognizer::recognize() virtual
+    function and decides whether the parsed event should change the
+    state of the recognizer - i.e. if the event starts or ends a
+    gesture or if it isn't related to gesture at all.
+*/
+
+/*! \fn Qt::GestureType gestureType() const
+
+    Returns the name of the gesture that is handled by the recognizer.
+*/
+
+/*! \fn Result recognize(const QList<QEvent*> &events)
+
+    This is a pure virtual function that need to be implemented in
+    subclasses.
+
+    Parses input \a events and returns the result, saying if the event
+    sequence is a gesture or not.
+*/
+
+/*! \fn QGesture* makeEvent() const
+
+    Creates a new gesture object that will be send to the widget. This
+    function is called when the gesture recognizer returned a
+    QGestureRecognizer::GestureStarted or
+    QGestureRecognizer::GestureFinished state.
+
+    Created gesture object is owned by the caller.
+ */
+
+/*! \fn void reset()
+
+    Resets the internal state of the gesture recognizer.
+*/
+
+/*! \fn void triggered(QGestureRecognizer::Result result)
+
+    The gesture recognizer might emit the signal when the gesture
+    state changes asynchronously, i.e. without any event being
+    received.
+*/
+
 class QGestureRecognizer : public QObject
 {
     Q_OBJECT
@@ -67,7 +119,7 @@ public:
     inline QGestureRecognizer(const Qt::GestureType &type) : type_(type) { }
     inline Qt::GestureType gestureType() const { return type_; }
 
-    virtual Result recognize(const QList<QEvent*> &inputEvents) = 0;
+    virtual Result recognize(const QList<QEvent*> &events) = 0;
     virtual QGesture* makeEvent() const = 0;
     virtual void reset() = 0;
 
diff --git a/src/gui/kernel/qwidget.cpp b/src/gui/kernel/qwidget.cpp
index f6be730..aea0003 100644
--- a/src/gui/kernel/qwidget.cpp
+++ b/src/gui/kernel/qwidget.cpp
@@ -11025,7 +11025,13 @@ QWindowSurface *QWidget::windowSurface() const
     return bs ? bs->windowSurface : 0;
 }
 
-void QWidget::grabGesture(Qt::GestureType gesture)
+/*!
+    \fn void QWidget::grabGesture(const Qt::GestureType &gesture)
+
+    Subscribes the widget to the specified \a gesture type.
+*/
+
+void QWidget::grabGesture(const Qt::GestureType &gesture)
 {
     Q_D(QWidget);
     if (d->gestures.contains(gesture))
@@ -11034,6 +11040,11 @@ void QWidget::grabGesture(Qt::GestureType gesture)
     ++qApp->d_func()->grabbedGestures[gesture];
 }
 
+/*!
+    \fn void QWidget::grabGestures(const QSet<Qt::GestureType> &gestures)
+
+    Subscribes the widget to the specified list of \a gestures.
+*/
 void QWidget::grabGestures(const QSet<Qt::GestureType> &gestures)
 {
     Q_D(QWidget);
@@ -11044,7 +11055,12 @@ void QWidget::grabGestures(const QSet<Qt::GestureType> &gestures)
     d->gestures.unite(gestures);
 }
 
-void QWidget::releaseGesture(Qt::GestureType gesture)
+/*!
+    \fn void QWidget::releaseGesture(const Qt::GestureType &gesture)
+
+    Unsubscribes the widget from the specified \a gesture type.
+*/
+void QWidget::releaseGesture(const Qt::GestureType &gesture)
 {
     Q_D(QWidget);
     QMap<Qt::GestureType, int>::iterator it =
@@ -11055,7 +11071,12 @@ void QWidget::releaseGesture(Qt::GestureType gesture)
     d->gestures.remove(gesture);
 }
 
-QSet<Qt::GestureType> QWidget::gestures()
+/*!
+    \fn QSet<Qt::GestureType> QWidget::gestures() const
+
+    Returns a list of gestures that the widget is subscribed to.
+*/
+QSet<Qt::GestureType> QWidget::gestures() const
 {
     Q_D(const QWidget);
     return d->gestures;
diff --git a/src/gui/kernel/qwidget.h b/src/gui/kernel/qwidget.h
index afe637d..e36b966 100644
--- a/src/gui/kernel/qwidget.h
+++ b/src/gui/kernel/qwidget.h
@@ -613,10 +613,10 @@ public:
     void setWindowSurface(QWindowSurface *surface);
     QWindowSurface *windowSurface() const;
 
-    void grabGesture(Qt::GestureType gesture);
+    void grabGesture(const Qt::GestureType &gesture);
     void grabGestures(const QSet<Qt::GestureType> &gestures);
-    void releaseGesture(Qt::GestureType gesture);
-    QSet<Qt::GestureType> gestures();
+    void releaseGesture(const Qt::GestureType &gesture);
+    QSet<Qt::GestureType> gestures() const;
 
 Q_SIGNALS:
     void customContextMenuRequested(const QPoint &pos);