Doc: Gesture API documentation review.

Reviewed-by: Trust Me

9 files changed, 158 insertions, 109 deletions

diff --git a/doc/src/qt4-intro.qdoc b/doc/src/qt4-intro.qdoc
index 00b7709..e37d327 100644
--- a/doc/src/qt4-intro.qdoc
+++ b/doc/src/qt4-intro.qdoc
@@ -546,29 +546,32 @@
     trigger on signals and \l{QEvent}s. By inserting animations into
     the state machine, it is also easier to use the framework for
     animating GUIs, for instance.
-    
+
     See \l{The State Machine Framework} documentation for more infromation.
 
-    \section1 Multi-touch & Gestures
+    \section1 Multi-Touch and Gestures
 
-    The new multi-touch and gestures support enables user interaction
-    with more than one finger, and combines sequential touch inputs to
-    a 'gesture'.
+    Support for multi-touch input enables users to interact with many
+    parts of a user interface at the same time, and provides the basis
+    for gestures. Additional infrastructure for gesture recognition
+    allows a sequence of touch inputs to be combined to create gestures
+    that can be used to activate features and trigger actions in an
+    application.
 
     \image gestures.png
 
-    The main benefits of this new functionality are:
+    This new functionality brings a number of benefits:
 
     \list
-        \o Allow users to interact with applications in better ways.
-        \o Simplify finger-based interaction with UI components.
-        \o Allowing common basic gestures and multi-touch
-           gestures.
-        \o Enable extensibility.
+        \o Allows users to interact with applications in more natural ways.
+        \o Simplifies finger-based interaction with UI components.
+        \o Combines support for common basic gestures and multi-touch gestures
+           in a single general framework.
+        \o Enables extensibility by design.
     \endlist
 
     See the QTouchEvent class documentation for more information on multi-touch
-    and QGestureEvent for gestures.
+    input and QGestureEvent for gestures.
 
     \section1 DOM access API
 
@@ -628,7 +631,7 @@
     through C++ APIs in the Qt application, or using the xmlpatternsvalidator
     command line utility. The implementation of XML Schema Validation supports
     the specification version 1.0 in large parts.
-    
+
     \img xml-schema.png
 
     See the \l{XML Processing} and QXmlSchema class documentation for more
diff --git a/doc/src/snippets/gestures/qgesture.cpp b/doc/src/snippets/gestures/qgesture.cpp
index 65f8b24..77f5cc2 100644
--- a/doc/src/snippets/gestures/qgesture.cpp
+++ b/doc/src/snippets/gestures/qgesture.cpp
@@ -64,7 +64,7 @@ private:
     QGesture *gesture;
 };
 
-/*!
+/*
     \class QGesture
     \since 4.6
 
@@ -100,7 +100,7 @@ private:
     \sa QPanGesture
 */
 
-/*! \fn bool QGesture::filterEvent(QEvent *event)
+/* \fn bool QGesture::filterEvent(QEvent *event)
 
     Parses input \a event and emits a signal when detects a gesture.
 
@@ -111,7 +111,7 @@ private:
     This is a pure virtual function that needs to be implemented in subclasses.
 */
 
-/*! \fn void QGesture::started()
+/* \fn void QGesture::started()
 
     The signal is emitted when the gesture is started. Extended information
     about the gesture is contained in the signal sender object.
@@ -119,19 +119,19 @@ private:
     In addition to started(), a triggered() signal should also be emitted.
 */
 
-/*! \fn void QGesture::triggered()
+/* \fn void QGesture::triggered()
 
     The signal is emitted when the gesture is detected. Extended information
     about the gesture is contained in the signal sender object.
 */
 
-/*! \fn void QGesture::finished()
+/* \fn void QGesture::finished()
 
     The signal is emitted when the gesture is finished. Extended information
     about the gesture is contained in the signal sender object.
 */
 
-/*! \fn void QGesture::cancelled()
+/* \fn void QGesture::cancelled()
 
     The signal is emitted when the gesture is cancelled, for example the reset()
     function is called while the gesture was in the process of emitting a
@@ -140,7 +140,7 @@ private:
 */
 
 
-/*!
+/*
     Creates a new gesture handler object and marks it as a child of \a parent.
 
     The \a parent object is also the default event source for the gesture,
@@ -156,7 +156,7 @@ QGesture::QGesture(QObject *parent)
         parent->installEventFilter(this);
 }
 
-/*! \internal
+/* \internal
  */
 QGesture::QGesture(QGesturePrivate &dd, QObject *parent)
     : QObject(dd, parent)
@@ -165,14 +165,14 @@ QGesture::QGesture(QGesturePrivate &dd, QObject *parent)
         parent->installEventFilter(this);
 }
 
-/*!
+/*
     Destroys the gesture object.
 */
 QGesture::~QGesture()
 {
 }
 
-/*! \internal
+/* \internal
  */
 bool QGesture::eventFilter(QObject *receiver, QEvent *event)
 {
@@ -182,13 +182,13 @@ bool QGesture::eventFilter(QObject *receiver, QEvent *event)
     return filterEvent(event);
 }
 
-/*!
+/*
     \property QGesture::state
 
     \brief The current state of the gesture.
 */
 
-/*!
+/*
   Returns the gesture recognition state.
  */
 Qt::GestureState QGesture::state() const
@@ -196,7 +196,7 @@ Qt::GestureState QGesture::state() const
     return d_func()->state;
 }
 
-/*!
+/*
   Sets this gesture's recognition state to \a state and emits appropriate
   signals.
 
@@ -237,7 +237,7 @@ void QGesture::updateState(Qt::GestureState state)
     }
 }
 
-/*!
+/*
     Sets the \a graphicsItem the gesture is filtering events for.
 
     The gesture will install an event filter to the \a graphicsItem and
@@ -257,7 +257,7 @@ void QGesture::setGraphicsItem(QGraphicsItem *graphicsItem)
         graphicsItem->installSceneEventFilter(d->eventFilterProxyGraphicsItem);
 }
 
-/*!
+/*
     Returns the graphics item the gesture is filtering events for.
 
     \sa setGraphicsItem()
@@ -267,7 +267,7 @@ QGraphicsItem* QGesture::graphicsItem() const
     return d_func()->graphicsItem;
 }
 
-/*! \fn void QGesture::reset()
+/* \fn void QGesture::reset()
 
     Resets the internal state of the gesture. This function might be called by
     the filterEvent() implementation in a derived class, or by the user to
diff --git a/examples/gestures/imageviewer/imagewidget.cpp b/examples/gestures/imageviewer/imagewidget.cpp
index 5633942..b8bb7b5 100644
--- a/examples/gestures/imageviewer/imagewidget.cpp
+++ b/examples/gestures/imageviewer/imagewidget.cpp
@@ -147,6 +147,7 @@ void ImageWidget::pinchTriggered(QPinchGesture *gesture)
     update();
 }
 
+//! [swipe slot]
 void ImageWidget::swipeTriggered(QSwipeGesture *gesture)
 {
     if (gesture->horizontalDirection() == QSwipeGesture::Left
@@ -156,6 +157,7 @@ void ImageWidget::swipeTriggered(QSwipeGesture *gesture)
         goNextImage();
     update();
 }
+//! [swipe slot]
 
 void ImageWidget::resizeEvent(QResizeEvent*)
 {
diff --git a/src/corelib/global/qnamespace.qdoc b/src/corelib/global/qnamespace.qdoc
index 5956677..ba05b00 100644
--- a/src/corelib/global/qnamespace.qdoc
+++ b/src/corelib/global/qnamespace.qdoc
@@ -2816,12 +2816,12 @@
     \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
+    \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.
+    User-defined gestures are registered with the
+    QApplication::registerGestureRecognizer() function which generates a custom gesture ID
+    in the range of values from CustomGesture to LastGestureType.
 
     \sa QGesture, QWidget::grabGesture()
 */
diff --git a/src/gui/graphicsview/qgraphicsitem.cpp b/src/gui/graphicsview/qgraphicsitem.cpp
index b86f9fe..45627f6 100644
--- a/src/gui/graphicsview/qgraphicsitem.cpp
+++ b/src/gui/graphicsview/qgraphicsitem.cpp
@@ -7288,10 +7288,9 @@ QGraphicsObject::QGraphicsObject(QGraphicsItemPrivate &dd, QGraphicsItem *parent
 }
 
 /*!
-    Subscribes the graphics object to a given \a gesture with a \a context.
+    Subscribes the graphics object to the given \a gesture for the specified \a context.
 
     \sa QGestureEvent
-    \since 4.6
 */
 
 void QGraphicsObject::grabGesture(Qt::GestureType gesture, Qt::GestureContext context)
diff --git a/src/gui/kernel/qapplication.cpp b/src/gui/kernel/qapplication.cpp
index d188468..b990fe2 100644
--- a/src/gui/kernel/qapplication.cpp
+++ b/src/gui/kernel/qapplication.cpp
@@ -5620,16 +5620,18 @@ Q_GUI_EXPORT void qt_translateRawTouchEvent(QWidget *window,
 }
 
 /*!
-    Registers \a recognizer in the gesture framework and returns a gesture id.
+    \since 4.6
 
-    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.
+    Registers the given \a recognizer in the gesture framework and returns a gesture ID
+    for it.
 
-    \sa unregisterGestureRecognizer, QGestureRecognizer::createGesture, QGesture
-    \since 4.6
+    The application takes ownership of the \a recognizer and returns the gesture type
+    ID associated with it. For gesture recognizers which handle custom QGesture
+    objects (i.e., those which return Qt::CustomGesture in a QGesture::gestureType()
+    function) the return value is a gesture ID between Qt::CustomGesture and
+    Qt::LastGestureType, inclusive.
+
+    \sa unregisterGestureRecognizer(), QGestureRecognizer::createGesture(), QGesture
 */
 Qt::GestureType QApplication::registerGestureRecognizer(QGestureRecognizer *recognizer)
 {
@@ -5637,10 +5639,11 @@ Qt::GestureType QApplication::registerGestureRecognizer(QGestureRecognizer *reco
 }
 
 /*!
-    Unregisters all gesture recognizers of specified \a type.
+    \since 4.6
+
+    Unregisters all gesture recognizers of the specified \a type.
 
     \sa registerGestureRecognizer
-    \since 4.6
 */
 void QApplication::unregisterGestureRecognizer(Qt::GestureType type)
 {
diff --git a/src/gui/kernel/qevent.cpp b/src/gui/kernel/qevent.cpp
index 1834874..4826704 100644
--- a/src/gui/kernel/qevent.cpp
+++ b/src/gui/kernel/qevent.cpp
@@ -4196,18 +4196,22 @@ QTouchEvent::TouchPoint &QTouchEvent::TouchPoint::operator=(const QTouchEvent::T
     \since 4.6
     \ingroup events
 
-    \brief The QGestureEvent class provides the description of triggered
-    gestures.
+    \brief The QGestureEvent class provides the description of triggered 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}{canceled} (a gesture might be
-    canceled if the current window looses focus, or because of a timeout, etc).
+    The QGestureEvent class contains a list of gestures, which can be obtained using the
+    allGestures() function.
 
-    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.
+    The gestures are either active or canceled. A list of those that are currently being
+    executed can be obtained using the activeGestures() function. A list of those which
+    were previously active and have been canceled can be accessed using the
+    canceledGestures() function. A gesture might be canceled if the current window loses
+    focus, for example, or because of a timeout, or for other reasons.
+
+    If the event handler does not accept the event by calling the generic
+    QEvent::accept() function, all individual QGesture object that were not accepted
+    will be propagated up the parent widget chain until a widget accepts them
+    individually, by calling QGestureEvent::accept() for each of them, or an event
+    filter consumes the event.
 
     \sa QGesture, QGestureRecognizer,
         QWidget::grabGesture(), QGraphicsObject::grabGesture()
@@ -4241,7 +4245,7 @@ QGesture *QGestureEvent::gesture(Qt::GestureType type) const
 }
 
 /*!
-    Returns a list of active (i.e. not canceled) gestures.
+    Returns a list of active (not canceled) gestures.
 */
 QList<QGesture *> QGestureEvent::activeGestures() const
 {
@@ -4257,16 +4261,17 @@ QList<QGesture *> QGestureEvent::canceledGestures() const
 }
 
 /*!
-    Sets the accept flag of the \a gesture object
+    Sets the accept flag of the given \a gesture object to the specified \a value.
+
+    Setting the accept flag indicates that the event receiver wants the \a gesture.
+    Unwanted gestures may be propagated to the parent widget.
 
-    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.
+    By default, gestures in events of type QEvent::Gesture are accepted, and
+    gestures in QEvent::GestureOverride events are ignored.
 
     For convenience, the accept flag can also be set with
-    \l{QGestureEvent::accept}{accept(gesture)}, and cleared with
-    \l{QGestureEvent::ignore}{ignore(gesture)}.
+    \l{QGestureEvent::accept()}{accept(gesture)}, and cleared with
+    \l{QGestureEvent::ignore()}{ignore(gesture)}.
 */
 void QGestureEvent::setAccepted(QGesture *gesture, bool value)
 {
@@ -4276,11 +4281,11 @@ void QGestureEvent::setAccepted(QGesture *gesture, bool value)
 }
 
 /*!
-    Sets the accept flag of the \a gesture object, the equivalent of calling
-    \l{QGestureEvent::setAccepted}{setAccepted}(gesture, true).
+    Sets the accept flag of the given \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.
+    Setting the accept flag indicates that the event receiver wants the
+    gesture. Unwanted gestures may be propagated to the parent widget.
 
     \sa QGestureEvent::ignore()
 */
@@ -4290,12 +4295,11 @@ void QGestureEvent::accept(QGesture *gesture)
 }
 
 /*!
-    Clears the accept flag parameter of the \a gesture object, the equivalent
-    of calling \l{QGestureEvent::setAccepted}{setAccepted}(gesture, false).
+    Clears the accept flag parameter of the given \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.
+    Clearing the accept flag indicates that the event receiver does not
+    want the gesture. Unwanted gestures may be propgated to the parent widget.
 
     \sa QGestureEvent::accept()
 */
@@ -4305,7 +4309,7 @@ void QGestureEvent::ignore(QGesture *gesture)
 }
 
 /*!
-    Returns true if the \a gesture is accepted.
+    Returns true if the \a gesture is accepted; otherwise returns false.
 */
 bool QGestureEvent::isAccepted(QGesture *gesture) const
 {
diff --git a/src/gui/kernel/qgesture.cpp b/src/gui/kernel/qgesture.cpp
index 2bcf98b..7b2cd6d 100644
--- a/src/gui/kernel/qgesture.cpp
+++ b/src/gui/kernel/qgesture.cpp
@@ -48,20 +48,20 @@ QT_BEGIN_NAMESPACE
     \class QGesture
     \since 4.6
 
-    \brief The QGesture class represents a gesture, containing all
-    properties that describe a gesture.
+    \brief The QGesture class represents a gesture, containing properties that
+    describe the corresponding user input.
 
-    QGesture objects are delivered to widgets and
-    \l{QGraphicsObject}{QGraphicsObject}s with a QGestureEvent.
+    QGesture objects are delivered to widgets and \l{QGraphicsObject}s with
+    \l{QGestureEvent}s.
 
     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).
+    some gesture-specific arguments. For example, the QPinchGesture gesture has a scale
+    factor that is exposed as a property.
 
-    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.
+    Developers of custom gesture recognizers can add additional properties in
+    order to provide additional information about a gesture. This can be done
+    by adding new dynamic properties to a QGesture object, or by subclassing
+    the QGesture class (or one of its subclasses).
 
     \sa QGestureEvent, QGestureRecognizer
 */
@@ -95,14 +95,12 @@ QGesture::~QGesture()
 
 /*!
     \property QGesture::state
-
-    The current state of the gesture.
+    \brief the current state of the gesture
 */
 
 /*!
     \property QGesture::gestureType
-
-    The type of the gesture.
+    \brief the type of the gesture
 */
 
 /*!
@@ -110,21 +108,19 @@ QGesture::~QGesture()
 
     \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
+    If the hot-spot is not set, the targetObject is used as the receiver of the
     gesture event.
 */
 
 /*!
     \property QGesture::hasHotSpot
-
-    Whether the hotSpot property is set.
+    \brief whether the gesture has a hot-spot
 */
 
 /*!
     \property QGesture::targetObject
-
-    The target object which will receive the gesture event if the hotSpot is
-    not set.
+    \brief the target object which will receive the gesture event if the hotSpot is
+    not set
 */
 
 Qt::GestureType QGesture::gestureType() const
diff --git a/src/gui/kernel/qgesturerecognizer.cpp b/src/gui/kernel/qgesturerecognizer.cpp
index e0515c2..2af087f 100644
--- a/src/gui/kernel/qgesturerecognizer.cpp
+++ b/src/gui/kernel/qgesturerecognizer.cpp
@@ -48,9 +48,47 @@ QT_BEGIN_NAMESPACE
 /*!
    \class QGestureRecognizer
    \since 4.6
+   \brief The QGestureRecognizer class provides the infrastructure for gesture recognition.
 
-   \brief The QGestureRecognizer is a base class for implementing custom
-   gestures.
+   Gesture recognizers are responsible for creating and managing QGesture objects and
+   monitoring input events sent to QWidget and QGraphicsObject subclasses.
+   QGestureRecognizer is the base class for implementing custom gestures.
+
+   Developers that only need to provide gesture recognition for standard gestures do not
+   need to use this class directly. Instances will be created behind the scenes by the
+   framework.
+
+   \section1 Recognizing Gestures
+
+   The process of recognizing gestures involves filtering input events sent to specific
+   objects, and modifying the associated QGesture objects to include relevant information
+   about the user's input.
+
+   Gestures are created when the framework calls createGesture() to handle user input
+   for a particular target QWidget or QGraphicsObject instance. Once a QGesture has been
+   created for one of these objects, the gesture recognizer will receive events for it
+   in its filterEvent() handler function.
+
+   When a gesture is canceled, the reset() function is called, giving the recognizer the
+   chance to update the appropriate properties in the corresponding QGesture object.
+
+   \section1 Supporting New Gestures
+
+   To add support for new gestures, you need to derive from QGestureRecognizer to create
+   a custom recognizer class and register it with the application by calling
+   QApplication::registerGestureRecognizer(). You can also derive from QGesture to create
+   a custom gesture class, or rely on dynamic properties to express specific details
+   of the gesture you want to handle.
+
+   Your custom QGestureRecognizer subclass needs to reimplement the filterEvent() function
+   to handle and filter the incoming input events for QWidget and QGraphicsObject subclasses.
+   Although the logic for gesture recognition is implemented in this function, the state of
+   recognition for each target object can be recorded in the QGesture object supplied.
+
+   If you choose to represent a gesture by a custom QGesture subclass, you will need to
+   reimplement the createGesture() function to construct instances of your gesture class.
+   Similarly, you may need to reimplement the reset() function if your custom gesture
+   objects need to be specially handled when a gesture is canceled.
 
    \sa QGesture
 */
@@ -58,14 +96,14 @@ QT_BEGIN_NAMESPACE
 /*!
     \enum QGestureRecognizer::ResultFlags
 
-    This enum type describes the result of the current event filtering step in
+    This enum 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 Ignore The event does not 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
@@ -75,7 +113,7 @@ QT_BEGIN_NAMESPACE
     \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.
+    may be reset automatically if they take too long to recognize gestures.
 
     \value GestureTriggered The gesture has been triggered and the appropriate
     QGesture object will be delivered to the target as a part of a
@@ -85,7 +123,7 @@ QT_BEGIN_NAMESPACE
     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
+    \value ConsumeEventHint This hint specifies that the gesture framework should
     consume the filtered event and not deliver it to the receiver.
 
     \omitvalue ResultState_Mask
@@ -102,14 +140,14 @@ QGestureRecognizer::QGestureRecognizer()
 }
 
 /*!
-    Destroys the gesture recognizer object.
+    Destroys the gesture recognizer.
 */
 QGestureRecognizer::~QGestureRecognizer()
 {
 }
 
 /*!
-    This function is called by Qt to creates a new QGesture object for the
+    This function is called by Qt to create a new QGesture object for the
     given \a target (QWidget or QGraphicsObject).
 
     Reimplement this function to create a custom QGesture-derived gesture
@@ -122,10 +160,11 @@ QGesture *QGestureRecognizer::createGesture(QObject *target)
 }
 
 /*!
-    This function is called by Qt to reset a \a gesture.
+    This function is called by the framework to reset a given \a gesture.
 
-    Reimplement this function if a custom QGesture-derived gesture object is
-    used which requires resetting additional properties.
+    Reimplement this function to implement additional requirements for custom QGesture
+    objects. This may be necessary if you implement a custom QGesture whose properties
+    need special handling when the gesture is reset.
 */
 void QGestureRecognizer::reset(QGesture *gesture)
 {
@@ -140,11 +179,14 @@ void QGestureRecognizer::reset(QGesture *gesture)
 /*!
     \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).
+    Handles the given \a event for the \a watched object, updating the state of the \a gesture
+    object as required, and returns a suitable Result for the current recognition step.
+
+    This function is called by the framework to allow the recognizer to filter input events
+    dispatched to QWidget or QGraphicsObject instances that it is monitoring.
 
-    Returns the result of the current recognition step. The state of the \a
-    gesture object is set depending on the result.
+    The result reflects how much of the gesture has been recognized. The state of the
+    \a gesture object is set depending on the result.
 
     \sa Qt::GestureState
 */