diff -r 000000000000 -r 1918ee327afb doc/src/frameworks-technologies/gestures.qdoc --- /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. +*/