Doc: Gesture API documentation review and improvements.

Reviewed-by: Trust Me

1 files changed, 92 insertions, 153 deletions

diff --git a/doc/src/frameworks-technologies/gestures.qdoc b/doc/src/frameworks-technologies/gestures.qdoc
index 158a273..e5947a2 100644
--- a/doc/src/frameworks-technologies/gestures.qdoc
+++ b/doc/src/frameworks-technologies/gestures.qdoc
@@ -59,176 +59,115 @@
 
     \section1 Overview
 
-    QGesture is the central class in Qt's gesture framework, providing
-    the API used by classes that represent specific gestures, such as
-    QPanGesture, QPinchGesture, and QSwipeGesture. These standard
-    classes are ready to use, and each exposes functions and
-    properties that give gesture-specific information about the user's
-    input. This is described in the \l{Using Standard Gestures With Widgets}
-    section.
-
-    QGesture is also designed to be subclassed and extended so that
-    support for new gestures can be implemented by developers. Adding
-    support for a new gesture involves implementing code to recognize
-    the gesture from incoming events. This is described in the
+    QGesture is the central class in Qt's gesture framework, providing a container
+    for information about gestures performed by the user, such as panning, pinching
+    and swiping. QGesture exposes properties that give general information that is
+    common to all gestures, and these can be extended to provide additional
+    gesture-specific information.
+
+    Developers can also implement new gestures by subclassing and extending the
+    QGestureRecognizer class. Adding support for a new gesture involves implementing
+    code to recognize the gesture from input events. This is described in the
     \l{Creating Your Own Gesture Recognizer} section.
 
     \section1 Using Standard Gestures with Widgets
 
-    Gesture objects are applied directly to widgets and other controls that accept
-    user input \mdash these are the \e{target objects}. When a gesture object is
-    constructed, the target object is typically passed to the constructor, though
-    it can also be passed as the argument to the \l{QGesture::}{setGestureTarget()}
-    function.
+    Gestures can be enabled for instances of QWidget and QGraphicsObject subclasses.
+    An object that accepts gesture input is referred to as a \e{target object}.
 
-    \snippet examples/gestures/imageviewer/imagewidget.cpp construct swipe gesture
+    To enable a gesture for a target object, call its QWidget::grabGesture() or
+    QGraphicsObject::grabGesture() function with an argument describing the
+    required gesture type. The standard types are defined by the Qt::GestureType
+    enum and include many commonly used gestures.
+
+    \snippet examples/gestures/imageviewer/imagewidget.cpp enable gestures
 
     In the above code, the gesture is set up in the constructor of the target object
-    itself, so the argument to the QSwipeGesture constructor is \e this.
+    itself.
+
+    When the user performs a gesture, QGestureEvent events will be delivered to the
+    target object, and these can be handled by reimplementing the QWidget::event()
+    handler function for widgets or QGraphicsItem::sceneEvent() for graphics objects.
+
+    For convenience, the \l{Image Gestures Example} reimplements the general
+    \l{QWidget::}{event()} handler function and delegates gesture events to a
+    specialized gestureEvent() function:
 
-    When the user performs a gesture, various signals may be emitted by the
-    gesture object. To monitor the user's actions, you need to connect signals
-    from the gesture object to slots in your code.
+    \snippet examples/gestures/imageviewer/imagewidget.cpp event handler
 
-    \snippet examples/gestures/imageviewer/imagewidget.cpp connect swipe gesture
+    The gesture events delivered to the target object can be examined individually
+    and dealt with appropriately:
 
-    Here, the \l{QGesture::}{triggered()} signal is used to inform the application
-    that a gesture was used. More precise monitoring of a gesture can be implemented
-    by connecting its \l{QGesture::}{started()}, \l{QGesture::}{canceled()} and
-    \l{QGesture::}{finished()} signals to slots.
+    \snippet examples/gestures/imageviewer/imagewidget.cpp gesture event handler
 
-    Responding to a signal is simply a matter of obtaining the gesture that sent
-    it and examining the information it contains.
+    Responding to a gesture is simply a matter of obtaining the QGesture object
+    delivered in the QGestureEvent sent to the target object and examining the
+    information it contains.
 
-    \snippet examples/gestures/imageviewer/imagewidget.cpp swipe slot start
+    \snippet examples/gestures/imageviewer/imagewidget.cpp swipe function
 
     Here, we examine the direction in which the user swiped the widget and modify
     its contents accordingly.
 
-    \section1 Using Standard Gestures with Graphics Items
-
-    The approach used for applying gestures to widgets can also be used with
-    graphics items. However, instead of passing a target object to the
-    gesture object's constructor, you set a target graphics item with the
-    \l{QGesture::}{setGraphicsItem()} function.
 
     \section1 Creating Your Own Gesture Recognizer
 
-    QGesture is a base class for a user defined gesture recognizer class. In
-    order to implement the recognizer you will need to subclass the
-    QGesture class and implement the pure virtual function
-    \l{QGesture::}{filterEvent()} to filter out events that are not relevant
-    to your gesture.
-
-    Once you have implemented the \l{QGesture::}{filterEvent()} function to
-    make your own recognizer you can process events. A sequence of events may,
-    according to your own rules, represent a gesture. The events can be singly
-    passed to the recognizer via the \l{QGesture::}{filterEvent()} function
-    or as a stream of events by specifying a parent source of events. The events
-    can be from any source and could result in any action as defined by the user.
-    The source and action need not be graphical, though that would be the most
-    likely scenario. To find how to connect a source of events to automatically
-    feed into the recognizer see the QGesture documentation.
-
-    Recognizers based on QGesture can emit any of the following signals to
-    indicate their progress in recognizing user input:
-
-    \list
-    \o \l{QGesture::}{triggered()} is emitted when a gesture is recognized.
-    \o \l{QGesture::}{started()} indicates that the gesture object has started
-    to recognize user input.
-    \o \l{QGesture::}{finished()} is emitted when the gesture object has
-    recognized the user input as a gesture, and finished handling it.
-    \o \l{QGesture::}{canceled()} indicates that the gesture was canceled,
-    either by the user or by the application.
-    \endlist
-
-    These signals are emitted when the state changes with the call to
-    \l{QGesture::}{updateState()}, more than one signal may
-    be emitted when a change of state occurs. There are four GestureStates
-
-    \table
-    \header \o New State            \o Description              \o QGesture Actions on Entering this State
-    \row    \o Qt::NoGesture        \o Initial value            \o emit \l {QGesture::}{canceled()}
-    \row    \o Qt::GestureStarted   \o A continuous gesture has started \o emit \l{QGesture::}{started()} and emit \l{QGesture::}{triggered()}
-    \row    \o Qt::GestureUpdated   \o A gesture continues      \o emit \l{QGesture::}{triggered()}
-    \row    \o Qt::GestureFinished  \o A gesture has finished.  \o emit \l{QGesture::}{finished()}
-    \endtable
-
-    \note \l{QGesture::started()}{started()} can be emitted if entering any
-    state greater than NoGesture if NoGesture was the previous state. This
-    means that your state machine does not need to explicitly use the
-    Qt::GestureStarted state, you can simply proceed from NoGesture to
-    Qt::GestureUpdated to emit a \l{QGesture::started()}{started()} signal
-    and a \l{QGesture::triggered()}{triggered()} signal.
-
-    You may use some or all of these states when implementing the pure
-    virtual function \l{QGesture::filterEvent()}{filterEvent()}.
-    \l{QGesture::filterEvent()}{filterEvent()} will usually implement a
-    state machine using the GestureState enums, but the details of which
-    states are used is up to the developer.
-
-    You may also need to reimplement the virtual function \l{QGesture::reset()}{reset()}
-    if internal data or objects need to be re-initialized. The function must
-    conclude with a call to \l{QGesture::updateState()}{updateState()} to
-    change the current state to Qt::NoGesture.
-
-    \section1 The ImageViewer Example
-
-    To illustrate how to use QGesture we will look at the ImageViewer
-    example. This example uses QPanGesture, a standard gesture, and an
-    implementation of TapAndHoldGesture. Note that TapAndHoldGesture is
-    platform-dependent.
-
-    \snippet doc/src/snippets/gestures/imageviewer/tapandholdgesture.cpp tapandhold-reset
-
-    In ImageViewer we see that the ImageWidget class uses two gestures:
-    \l QPanGesture and TapAndHoldGesture. The
-    QPanGesture is a standard gesture which is part of Qt.
-    TapAndHoldGesture is defined and implemented as part of the example.
-    The ImageWidget listens for signals from the gestures, but is not
-    interested in the \l{QGesture::started()}{started()} signal.
-
-    \snippet doc/src/snippets/gestures/imageviewer/imagewidget.h imagewidget-slots
-
-    TapAndHoldGesture uses QTouchEvent events and mouse events to detect
-    start, update and end events that can be mapped onto the GestureState
-    changes. The implementation in this case uses a timer as well. If the
-    timeout event occurs a given number of times after the start of the gesture
-    then the gesture is considered to have finished whether or not the
-    appropriate touch or mouse event has occurred. Also if a large jump in
-    the position of the event occurs, as calculated by the \l {QPoint::manhattanLength()}{manhattanLength()}
-    call, then the gesture is canceled by calling \l{QGesture::reset()}{reset()}
-    which tidies up  and uses \l{QGesture::updateState()}{updateState()} to
-    change state to NoGesture which will result in the \l{QGesture::canceled()}{canceled()}
-    signal being emitted by the recognizer.
-
-    ImageWidget handles the signals by connecting the slots to the signals,
-    although \c canceled() is not connected here.
-
-    \snippet doc/src/snippets/gestures/imageviewer/imagewidget.cpp  imagewidget-connect
-
-    These functions in turn will have to be aware of which gesture
-    object was the source of the signal since we have more than one source
-    per slot. This is easily done by using the QObject::sender() function
-    as shown here
-
-    \snippet doc/src/snippets/gestures/imageviewer/imagewidget.cpp imagewidget-triggered-1
-
-    As \l{QGesture::triggered()}{triggered()} signals are handled by
-    gestureTriggered() there may be position updates invoking calls to,
-    for example, goNextImage(), this will cause a change in the image
-    handling logic of ImageWidget and a call to updateImage() to display
-    the changed state.
-
-    Following the logic of how the QEvent is processed we can summmarize
-    it as follows:
-    \list
-        \o filterEvent() becomes the event filter of the parent ImageWidget object
-        for a QPanGesture object and a TapAndHoldGesture object.
-        \o filterEvent() then calls updateState() to change states
-        \o updateState() emits the appropriate signal(s) for the state change.
-        \o The signals are caught by the defined slots in ImageWidget
-        \o The widget logic changes and an update() results in a paint event.
-    \endlist
+    Adding support for a new gesture involves creating and registering a new gesture
+    recognizer. Depending on the recognition process for the gesture, it may also
+    involve creating a new gesture object.
+
+    To create a new recognizer, you need to subclass QGestureRecognizer to create a
+    custom recognizer class. There is one virtual function that you must reimplement
+    and two others that can be reimplemented as required.
+
+    \section2 Filtering Input Events
+
+    The \l{QGestureRecognizer::}{filterEvent()} function must be reimplemented.
+    This function handles and filters the incoming input events for the target objects
+    and determines whether or not they correspond to the gesture the recognizer is
+    looking for.
+
+    Although the logic for gesture recognition is implemented in this function,
+    possibly using a state machine based on the Qt::GestureState enums, you can store
+    persistent information about the state of the recognition process in the QGesture
+    object supplied.
+
+    Your \l{QGestureRecognizer::}{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.
+
+    \section2 Custom Gestures
+
+    If you choose to represent a gesture by a custom QGesture subclass, you will need to
+    reimplement the \l{QGestureRecognizer::}{createGesture()} function to construct
+    instances of your gesture class instead of standard QGesture instances. Alternatively,
+    you may want to use standard QGesture instances, but add additional dynamic properties
+    to them to express specific details of the gesture you want to handle.
+
+    \section2 Resetting Gestures
+
+    If you use custom gesture objects that need to be reset or otherwise specially
+    handled when a gesture is canceled, you need to reimplement the
+    \l{QGestureRecognizer::}{reset()} function to perform these special tasks.
+
+    Note that QGesture objects are only created once for each combination of target object
+    and gesture type, and they are reused every time the user attempts to perform the
+    same gesture type on the target object. As a result, it can be useful to reimplement
+    the \l{QGestureRecognizer::}{reset()} function to clean up after each previous attempt
+    at recognizing a gesture.
+
+
+    \section1 Using a New Gesture Recognizer
+
+    To use a gesture recognizer, construct an instance of your QGestureRecognizer
+    subclass, and register it with the application with
+    QApplication::registerGestureRecognizer(). A recognizer for a given type of
+    gesture can be removed with QApplication::unregisterGestureRecognizer().
+
+
+    \section1 Further Reading
+
+    The \l{Image Gestures Example} shows how to enable gestures for a widget in
+    a simple image viewer application.
 */