/****************************************************************************

**

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

** All rights reserved.

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

**

** This file is part of the documentation of the Qt Toolkit.

**

** $QT_BEGIN_LICENSE:LGPL$

** No Commercial Usage

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

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

** contained in the Technology Preview License Agreement accompanying

** this package.

**

** GNU Lesser General Public License Usage

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

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

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

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

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

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

**

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

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

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

**

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

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

**

**

**

**

**

**

**

**

** $QT_END_LICENSE$

**

****************************************************************************/

/*!

    \page gestures-overview.html

    \title Gestures Programming

    \ingroup frameworks-technologies

    \startpage index.html Qt Reference Documentation

    \brief An overview of the Qt support for Gesture programming.

    Qt includes a framework for gesture programming that gives has the ability

    to form gestures from a series of events, independently of the input methods

    used. A gesture could be a particular movement of a mouse, a touch screen

    action, or a series of events from some other source. The nature of the input,

    the interpretation of the gesture and the action taken are the choice of the

    developer.

    \tableofcontents

    \section1 Overview

    QGesture is the central class in Qt's gesture framework, providing a container

    for information about gestures performed by the user. QGesture exposes

    properties that give general information that is common to all gestures, and

    these can be extended to provide additional gesture-specific information.

    Common panning, pinching and swiping gestures are represented by specialized

    classes: QPanGesture, QPinchGesture and QSwipeGesture.

    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

    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}.

    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/imagegestures/imagewidget.cpp enable gestures

    In the above code, the gesture is set up in the constructor of the target object

    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:

    \snippet examples/gestures/imagegestures/imagewidget.cpp event handler

    The gesture events delivered to the target object can be examined individually

    and dealt with appropriately:

    \snippet examples/gestures/imagegestures/imagewidget.cpp gesture event handler

    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/imagegestures/imagewidget.cpp swipe function

    Here, we examine the direction in which the user swiped the widget and modify

    its contents accordingly.

    \section1 Creating Your Own Gesture Recognizer

    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.

*/