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

     2 **

     3 ** Copyright (C) 2010 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 #include "private/qgesturemanager_p.h"

    46 

    47 QT_BEGIN_NAMESPACE

    48 

    49 /*!

    50    \class QGestureRecognizer

    51    \since 4.6

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

    53    \ingroup gestures

    54 

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

    56    monitoring input events sent to QWidget and QGraphicsObject subclasses.

    57    QGestureRecognizer is the base class for implementing custom gestures.

    58 

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

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

    61    framework.

    62 

    63    \section1 Recognizing Gestures

    64 

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

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

    67    about the user's input.

    68 

    69    Gestures are created when the framework calls create() to handle user input

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

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

    72 

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

    74    receive events for it in its recognize() handler function.

    75 

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

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

    78 

    79    \section1 Supporting New Gestures

    80 

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

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

    83    the application by calling QGestureRecognizer::registerRecognizer(). You can also

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

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

    86 

    87    Your custom QGestureRecognizer subclass needs to reimplement the recognize()

    88    function to handle and filter the incoming input events for QWidget and

    89    QGraphicsObject subclasses. Although the logic for gesture recognition is

    90    implemented in this function, you can store persistent information about the

    91    state of the recognition process in the QGesture object supplied. The

    92    recognize() function must return a value of QGestureRecognizer::Result that

    93    indicates the state of recognition for a given gesture and target object.

    94    This determines whether or not a gesture event will be delivered to a target

    95    object.

    96 

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

    98    reimplement the create() function to construct instances of your gesture class.

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

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

   101 

   102    \sa QGesture

   103 */

   104 

   105 /*!

   106     \enum QGestureRecognizer::ResultFlag

   107 

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

   109     a gesture recognizer state machine.

   110 

   111     The result consists of a state value (one of Ignore, MayBeGesture,

   112     TriggerGesture, FinishGesture, CancelGesture) and an optional hint

   113     (ConsumeEventHint).

   114 

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

   116 

   117     \value MayBeGesture The event changed the internal state of the recognizer,

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

   119     filter more events to decide. Gesture recognizers in the MayBeGesture state

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

   121 

   122     \value TriggerGesture The gesture has been triggered and the appropriate

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

   124     QGestureEvent.

   125 

   126     \value FinishGesture The gesture has been finished successfully and the

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

   128     QGestureEvent.

   129 

   130     \value CancelGesture The event made it clear that it is not a gesture. If

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

   132     gesture is canceled and the appropriate QGesture object will be delivered

   133     to the target as a part of a QGestureEvent.

   134 

   135     \value ConsumeEventHint This hint specifies that the gesture framework

   136     should consume the filtered event and not deliver it to the receiver.

   137 

   138     \omitvalue ResultState_Mask

   139     \omitvalue ResultHint_Mask

   140 

   141     \sa QGestureRecognizer::recognize()

   142 */

   143 

   144 /*!

   145     Constructs a new gesture recognizer object.

   146 */

   147 QGestureRecognizer::QGestureRecognizer()

   148 {

   149 }

   150 

   151 /*!

   152     Destroys the gesture recognizer.

   153 */

   154 QGestureRecognizer::~QGestureRecognizer()

   155 {

   156 }

   157 

   158 /*!

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

   160     given \a target (QWidget or QGraphicsObject).

   161 

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

   163     object if necessary.

   164 */

   165 QGesture *QGestureRecognizer::create(QObject *target)

   166 {

   167     Q_UNUSED(target);

   168     return new QGesture;

   169 }

   170 

   171 /*!

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

   173 

   174     Reimplement this function to implement additional requirements for custom QGesture

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

   176     need special handling when the gesture is reset.

   177 */

   178 void QGestureRecognizer::reset(QGesture *gesture)

   179 {

   180     if (gesture) {

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

   182         d->state = Qt::NoGesture;

   183         d->hotSpot = QPointF();

   184         d->isHotSpotSet = false;

   185     }

   186 }

   187 

   188 /*!

   189     \fn QGestureRecognizer::recognize(QGesture *gesture, QObject *watched, QEvent *event)

   190 

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

   192     object as required, and returns a suitable result for the current recognition step.

   193 

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

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

   196 

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

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

   199 

   200     \sa QGestureRecognizer::Result

   201 */

   202 

   203 /*!

   204     Registers the given \a recognizer in the gesture framework and returns a gesture ID

   205     for it.

   206 

   207     The application takes ownership of the \a recognizer and returns the gesture type

   208     ID associated with it. For gesture recognizers which handle custom QGesture

   209     objects (i.e., those which return Qt::CustomGesture in a QGesture::gestureType()

   210     function) the return value is a generated gesture ID with the Qt::CustomGesture

   211     flag set.

   212 

   213     \sa unregisterRecognizer(), QGestureRecognizer::create(), QGesture

   214 */

   215 Qt::GestureType QGestureRecognizer::registerRecognizer(QGestureRecognizer *recognizer)

   216 {

   217     return QGestureManager::instance()->registerGestureRecognizer(recognizer);

   218 }

   219 

   220 /*!

   221     Unregisters all gesture recognizers of the specified \a type.

   222 

   223     \sa registerRecognizer()

   224 */

   225 void QGestureRecognizer::unregisterRecognizer(Qt::GestureType type)

   226 {

   227     QGestureManager::instance()->unregisterGestureRecognizer(type);

   228 }

   229 

   230 QT_END_NAMESPACE