Doc: Gesture API documentation review and improvements.

Reviewed-by: Trust Me

2 files changed, 37 insertions, 12 deletions

diff --git a/src/gui/kernel/qgesture.cpp b/src/gui/kernel/qgesture.cpp
index 3639a45..6231d19 100644
--- a/src/gui/kernel/qgesture.cpp
+++ b/src/gui/kernel/qgesture.cpp
@@ -51,11 +51,14 @@ QT_BEGIN_NAMESPACE
     \brief The QGesture class represents a gesture, containing properties that
     describe the corresponding user input.
 
-    QGesture objects are delivered to widgets and \l{QGraphicsObject}s with
-    \l{QGestureEvent}s.
+    Gesture objects are not constructed directly by developers. They are created by
+    the QGestureRecognizer object that is registered with the application; see
+    QApplication::registerGestureRecognizer().
+
+    \section1 Gesture Properties
 
     The class has a list of properties that can be queried by the user to get
-    some gesture-specific arguments. For example, the QPinchGesture gesture has a scale
+    some gesture-specific arguments. For example, the pinch gesture has a scale
     factor that is exposed as a property.
 
     Developers of custom gesture recognizers can add additional properties in
@@ -63,6 +66,23 @@ QT_BEGIN_NAMESPACE
     by adding new dynamic properties to a QGesture object, or by subclassing
     the QGesture class (or one of its subclasses).
 
+    \section1 Lifecycle of a Gesture Object
+
+    A QGesture instance is created when the application calls QWidget::grabGesture()
+    or QGraphicsObject::grabGesture() to configure a widget or graphics object (the
+    target object) for gesture input. One gesture object is created for each target
+    object.
+
+    The registered gesture recognizer monitors the input events for the target
+    object via its \l{QGestureRecognizer::}{filterEvent()} function, updating the
+    properties of the gesture object as required.
+
+    The gesture object may be delivered to the target object in a QGestureEvent if
+    the corresponding gesture is active or has just been canceled. Each event that
+    is delivered contains a list of gesture objects, since support for more than
+    one gesture may be enabled for the target object. Due to the way events are
+    handled in Qt, gesture events may be filtered by other objects.
+
     \sa QGestureEvent, QGestureRecognizer
 */
 
diff --git a/src/gui/kernel/qgesturerecognizer.cpp b/src/gui/kernel/qgesturerecognizer.cpp
index 2af087f..1998cba 100644
--- a/src/gui/kernel/qgesturerecognizer.cpp
+++ b/src/gui/kernel/qgesturerecognizer.cpp
@@ -65,9 +65,11 @@ QT_BEGIN_NAMESPACE
    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.
+   for a particular instance of a QWidget or QGraphicsObject subclass. A QGesture object
+   is created for each widget or item that is configured to use gestures.
+
+   Once a QGesture has been created for a target object, 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.
@@ -75,15 +77,18 @@ QT_BEGIN_NAMESPACE
    \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.
+   a custom recognizer class, construct an instance of this class, and register it with
+   the application by calling QApplication::registerGestureRecognizer(). You can also
+   subclass 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.
+   Although the logic for gesture recognition is implemented in this function, you can
+   store persistent information about the state of the recognition process in the QGesture
+   object supplied. The filterEvent() function must return a value of Qt::GestureState that
+   indicates the state of recognition for a given gesture and target object. This determines
+   whether or not a gesture event will be delivered to a target object.
 
    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.