--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/src/frameworks-technologies/gestures.qdoc Mon Jan 11 14:00:40 2010 +0000
@@ -0,0 +1,173 @@
+/****************************************************************************
+**
+** 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.
+*/