1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the QtGui module of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 #include "qgesturerecognizer.h"

    43 

    44 #include "private/qgesture_p.h"

    45 

    46 QT_BEGIN_NAMESPACE

    47 

    48 /*!

    49    \class QGestureRecognizer

    50    \since 4.6

    51    \brief The QGestureRecognizer class provides the infrastructure for gesture recognition.

    52    \ingroup gestures

    53 

    54    Gesture recognizers are responsible for creating and managing QGesture objects and

    55    monitoring input events sent to QWidget and QGraphicsObject subclasses.

    56    QGestureRecognizer is the base class for implementing custom gestures.

    57 

    58    Developers that only need to provide gesture recognition for standard gestures do not

    59    need to use this class directly. Instances will be created behind the scenes by the

    60    framework.

    61 

    62    \section1 Recognizing Gestures

    63 

    64    The process of recognizing gestures involves filtering input events sent to specific

    65    objects, and modifying the associated QGesture objects to include relevant information

    66    about the user's input.

    67 

    68    Gestures are created when the framework calls createGesture() to handle user input

    69    for a particular instance of a QWidget or QGraphicsObject subclass. A QGesture object

    70    is created for each widget or item that is configured to use gestures.

    71 

    72    Once a QGesture has been created for a target object, the gesture recognizer will

    73    receive events for it in its filterEvent() handler function.

    74 

    75    When a gesture is canceled, the reset() function is called, giving the recognizer the

    76    chance to update the appropriate properties in the corresponding QGesture object.

    77 

    78    \section1 Supporting New Gestures

    79 

    80    To add support for new gestures, you need to derive from QGestureRecognizer to create

    81    a custom recognizer class, construct an instance of this class, and register it with

    82    the application by calling QApplication::registerGestureRecognizer(). You can also

    83    subclass QGesture to create a custom gesture class, or rely on dynamic properties

    84    to express specific details of the gesture you want to handle.

    85 

    86    Your custom QGestureRecognizer subclass needs to reimplement the filterEvent() function

    87    to handle and filter the incoming input events for QWidget and QGraphicsObject subclasses.

    88    Although the logic for gesture recognition is implemented in this function, you can

    89    store persistent information about the state of the recognition process in the QGesture

    90    object supplied. The filterEvent() function must return a value of Qt::GestureState that

    91    indicates the state of recognition for a given gesture and target object. This determines

    92    whether or not a gesture event will be delivered to a target object.

    93 

    94    If you choose to represent a gesture by a custom QGesture subclass, you will need to

    95    reimplement the createGesture() function to construct instances of your gesture class.

    96    Similarly, you may need to reimplement the reset() function if your custom gesture

    97    objects need to be specially handled when a gesture is canceled.

    98 

    99    \sa QGesture

   100 */

   101 

   102 /*!

   103     \enum QGestureRecognizer::ResultFlags

   104 

   105     This enum describes the result of the current event filtering step in

   106     a gesture recognizer state machine.

   107 

   108     The result consists of a state value (one of Ignore, NotGesture,

   109     MaybeGesture, GestureTriggered, GestureFinished) and an optional hint

   110     (ConsumeEventHint).

   111 

   112     \value Ignore The event does not change the state of the recognizer.

   113 

   114     \value NotGesture The event made it clear that it is not a gesture. If the

   115     gesture recognizer was in GestureTriggered state before, then the gesture

   116     is canceled and the appropriate QGesture object will be delivered to the

   117     target as a part of a QGestureEvent.

   118 

   119     \value MaybeGesture The event changed the internal state of the recognizer,

   120     but it isn't clear yet if it is a gesture or not. The recognizer needs to

   121     filter more events to decide. Gesture recognizers in the MaybeGesture state

   122     may be reset automatically if they take too long to recognize gestures.

   123 

   124     \value GestureTriggered The gesture has been triggered and the appropriate

   125     QGesture object will be delivered to the target as a part of a

   126     QGestureEvent.

   127 

   128     \value GestureFinished The gesture has been finished successfully and the

   129     appropriate QGesture object will be delivered to the target as a part of a

   130     QGestureEvent.

   131 

   132     \value ConsumeEventHint This hint specifies that the gesture framework should

   133     consume the filtered event and not deliver it to the receiver.

   134 

   135     \omitvalue ResultState_Mask

   136     \omitvalue ResultHint_Mask

   137 

   138     \sa QGestureRecognizer::filterEvent()

   139 */

   140 

   141 /*!

   142     Constructs a new gesture recognizer object.

   143 */

   144 QGestureRecognizer::QGestureRecognizer()

   145 {

   146 }

   147 

   148 /*!

   149     Destroys the gesture recognizer.

   150 */

   151 QGestureRecognizer::~QGestureRecognizer()

   152 {

   153 }

   154 

   155 /*!

   156     This function is called by Qt to create a new QGesture object for the

   157     given \a target (QWidget or QGraphicsObject).

   158 

   159     Reimplement this function to create a custom QGesture-derived gesture

   160     object if necessary.

   161 */

   162 QGesture *QGestureRecognizer::createGesture(QObject *target)

   163 {

   164     Q_UNUSED(target);

   165     return new QGesture;

   166 }

   167 

   168 /*!

   169     This function is called by the framework to reset a given \a gesture.

   170 

   171     Reimplement this function to implement additional requirements for custom QGesture

   172     objects. This may be necessary if you implement a custom QGesture whose properties

   173     need special handling when the gesture is reset.

   174 */

   175 void QGestureRecognizer::reset(QGesture *gesture)

   176 {

   177     if (gesture) {

   178         QGesturePrivate *d = gesture->d_func();

   179         d->state = Qt::NoGesture;

   180         d->hotSpot = QPointF();

   181         d->targetObject = 0;

   182     }

   183 }

   184 

   185 /*!

   186     \fn QGestureRecognizer::filterEvent(QGesture *gesture, QObject *watched, QEvent *event)

   187 

   188     Handles the given \a event for the \a watched object, updating the state of the \a gesture

   189     object as required, and returns a suitable Result for the current recognition step.

   190 

   191     This function is called by the framework to allow the recognizer to filter input events

   192     dispatched to QWidget or QGraphicsObject instances that it is monitoring.

   193 

   194     The result reflects how much of the gesture has been recognized. The state of the

   195     \a gesture object is set depending on the result.

   196 

   197     \sa Qt::GestureState

   198 */

   199 

   200 QT_END_NAMESPACE